How to Implement On-Demand Bootstrap for Missing Tools in a Reverse-Skill

The reverse-skill framework automatically installs required external tools only when a skill needs them, using a declarative manifest system that supports GitHub releases, package managers, and MCP server registration.

The reverse-skill repository (zhaoxuya520/reverse-skill) eliminates manual environment setup by implementing on-demand bootstrap for missing tools. This architecture ensures skills declare their dependencies explicitly, triggering secure, deterministic installations the first time a capability is requested. The system combines a JSON manifest catalog, a PowerShell bootstrap driver, and skill-level directives to keep tooling synchronized across Windows, macOS, and Linux environments.

The Three Core Components of On-Demand Bootstrap

Every automatic installation relies on three tightly-coupled components that work together to resolve, install, and register missing capabilities.

bootstrap-manifest.json

The manifest located at skills/scripts/bootstrap-manifest.json serves as the single source of truth for all auto-installable capabilities. Each entry declares the installation method, verification command, and optional post-install steps.

Key fields include:

• bootstrapKind: Defines the installation strategy (github-zip, winget-package, pip-package, npm-package, git-clone, go-install, or local-http-mcp)
• assetSha256: Pinned SHA-256 hash for GitHub release validation
• canAutoInstall: Boolean flag indicating whether the tool can be downloaded automatically or requires manual installation
• dependsOn: Array of transitive dependencies expanded by the bootstrap script

bootstrap-reverse.ps1

The PowerShell driver at skills/scripts/bootstrap-reverse.ps1 receives capability requests, resolves their definitions, and executes the appropriate installation strategy. This script implements several key functions:

• Expand-CapabilityDependencies: Recursively includes transitive dependsOn entries from the manifest
• Get-ReverseBootstrapDefinition: Retrieves the JSON definition for a named capability
• Ensure-Capability: Dispatches to specialized installers based on the bootstrapKind value
• Ensure-McpServer: Registers MCP server endpoints in Claude or Codex configuration files

Skill NEXT Directives

Individual skills trigger the bootstrap process through a NEXT directive declared in their SKILL.md file. This declarative approach allows a skill to request specific capabilities before execution begins, automatically triggering installation for any missing tools.

How the On-Demand Bootstrap Flow Works

The bootstrap process follows a deterministic six-step pipeline that ensures tools are installed securely and registered correctly.

1. Capability request: A skill declares dependencies using the -Capability parameter (e.g., @('jadx','r2'))
2. Dependency expansion: The script calls Expand-CapabilityDependencies to include any transitive dependsOn entries defined in the manifest
3. Definition lookup: Get-ReverseBootstrapDefinition fetches the JSON object for each requested capability
4. Installation execution:
   • GitHub zip: Ensure-GitHubZipInstall downloads the release asset, validates the SHA-256 digest, extracts it, and adds the bin folder to $env:PATH
   • Winget: Ensure-WingetPackage runs silent installation using the package ID from the manifest
   • Pip / npm: Invokes python -m pip or npm -g with optional post-install commands (e.g., npx playwright install)
   • Git clone / Go install: Dedicated helpers clone repositories or compile Go binaries
   • Local HTTP MCP: Starts services and registers MCP endpoints for tools like IDA Pro
5. MCP registration: If the capability provides an MCP server, the script writes the server definition into Claude Desktop or Codex configuration files using Get-ClaudeMcpConfig and Set-CodexMcpServer
6. Tool-index refresh: The script executes refresh-tool-index.ps1 to rebuild tool-index.md, making new executables discoverable by ToolDiscovery.ps1

Implementing Bootstrap in Your Skills

Declaring Capability Dependencies

Add a NEXT directive to your skill's SKILL.md to trigger automatic installation when tools are missing:

# In skills/your-skill/SKILL.md

# ----------------------------------------------------

# The skill needs jadx for decompilation and radare2 for binary analysis.

# If either tool is missing, bootstrap it on the fly.

NEXT:
  powershell -NoProfile -ExecutionPolicy Bypass `
    -File "<skill-root>\scripts\bootstrap-reverse.ps1" `
    -Capability @('jadx','r2')

The framework checks the local tool-index.md before execution. If jadx or r2 is absent, the bootstrap script runs automatically.

The Bootstrap Script Entry Point

The entry point in bootstrap-reverse.ps1 handles parameter validation and orchestrates the installation flow:

# bootstrap-reverse.ps1 – entry point (simplified)

param(
    [Parameter(Mandatory)][string[]]$Capability,
    [switch]$StartServices
)

# Expand dependencies → install each missing capability

$expandedCapabilities = Expand-CapabilityDependencies -Names $Capability
foreach ($name in $expandedCapabilities) {
    $def = Get-ReverseBootstrapDefinition -Name $name
    if (-not $def) { continue }   # safety guard

    # Install according to the manifest’s `bootstrapKind`

    $ensureResult = Ensure-Capability -Name $name
    if ($StartServices -and $def.bootstrapKind -eq 'local-http-mcp') {
        # Example: start the local service after install

        & $PSScriptRoot\Start-${name}Service.ps1 $def
    }
}

# Refresh the tool index so the new binaries are discoverable

& (Join-Path $PSScriptRoot 'refresh-tool-index.ps1')

Adding New Capabilities to the Manifest

To make a new tool available for on-demand bootstrap, add an entry to skills/scripts/bootstrap-manifest.json:

{
  "name": "gdb",
  "bootstrapKind": "winget-package",
  "wingetId": "GnuWin32.GDB",
  "installDir": "%USERPROFILE%\\Tools\\gdb",
  "docsUrl": "https://www.gnu.org/software/gdb/",
  "canAutoInstall": true,
  "verifyCommand": "gdb"
}

After saving, any skill can request gdb with -Capability @('gdb'), triggering automatic installation via winget.

Handling Manual-Install-Only Tools

For tools requiring license agreements or manual setup (e.g., Burp Suite), set canAutoInstall to false and provide a hint:

{
  "name": "burpsuite-mcp",
  "bootstrapKind": "local-http-mcp",
  "canAutoInstall": false,
  "manualInstallHint": "Install Burp Suite from the official website, then add the MCP plugin from the extension store.",
  "mcpNames": ["burpsuite"],
  "mcpUrl": "http://localhost:9876/mcp",
  "servicePort": 9876,
  "verificationMode": "service-or-registration"
}

When requested, the bootstrap driver prints the warning with your hint and exits without attempting installation, ensuring compliance with licensing constraints.

Security and Verification Features

The on-demand bootstrap system enforces security through cryptographic verification and explicit declarations:

• Pinned hashes: GitHub releases require matching SHA-256 checksums in assetSha256
• Explicit paths: Installation directories are specified explicitly rather than inferred from system defaults
• Manual install flags: Sensitive or commercial tools must set canAutoInstall to false, preventing unauthorized downloads
• Verification commands: Each capability specifies a verifyCommand that confirms successful installation before the skill executes

Summary

• Declare capabilities in skills/scripts/bootstrap-manifest.json with explicit installation methods and verification hashes
• Trigger bootstrap via the NEXT directive in SKILL.md using the -Capability parameter array
• Let the driver handle complexity: bootstrap-reverse.ps1 manages transitive dependencies, platform differences, and MCP registration automatically
• Maintain security: Use canAutoInstall flags and pinned SHA-256 hashes to prevent unauthorized or unverified installations
• Update discovery: The script automatically runs refresh-tool-index.ps1 to populate tool-index.md, ensuring ToolDiscovery.ps1 can locate new binaries immediately

Frequently Asked Questions

What happens if a tool is already installed?

The bootstrap script checks the local tool-index.md before attempting installation. If the executable is present and passes the verifyCommand specified in the manifest, the script skips installation and proceeds immediately, avoiding redundant downloads or configuration changes.

Can I use on-demand bootstrap on Linux and macOS?

Yes. While the bootstrap driver is written in PowerShell (bootstrap-reverse.ps1), it supports cross-platform execution through PowerShell Core. Installation strategies like pip, npm, go-install, and git-clone work identically across operating systems, while platform-specific methods like winget gracefully skip or error on non-Windows systems.

How do I add support for a custom installation method?

Extend bootstrap-reverse.ps1 by adding a new Ensure-* function following the existing pattern (e.g., Ensure-CustomPackage). Update the switch statement in Ensure-Capability to dispatch to your new function when bootstrapKind matches your custom type. Document the required JSON schema in bootstrap-manifest.json for the new kind.

What is the tool-index.md file used for?

The tool-index.md file acts as a local registry of installed capabilities, generated by refresh-tool-index.ps1 and consumed by ToolDiscovery.ps1. It maps capability names to absolute paths, enabling skills to locate executables without assuming system PATH configuration or installation directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}