# How the Reverse-Skill Auto-Installation Bootstrap Mechanism Works: A Complete Technical Guide

> Explore the reverse-skill bootstrap mechanism. This guide details how a Bash orchestrator uses a JSON manifest to automatically fetch, verify, and install security tools across platforms.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-25

---

**The reverse-skill bootstrap mechanism uses a self-contained Bash orchestrator that reads a JSON manifest to automatically fetch, cryptographically verify, and install security analysis tools while handling cross-platform dependencies and MCP server registration.**

The reverse-skill repository eliminates manual toolchain configuration through a sophisticated auto-installation system. This bootstrap mechanism combines a declarative manifest with intelligent dependency resolution to deploy reverse engineering utilities via a single command. This article examines the internal architecture of the reverse-skill bootstrap system, tracing execution from CLI parsing through SHA-256 verification to final MCP registration.

## Three-Component Architecture

The bootstrap system consists of three tightly coupled components stored in the repository:

- **[`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json)** – A JSON catalogue defining every supported tool, version pins, SHA-256 digests, and post-install actions.
- **[`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh)** – The main orchestrator handling argument parsing, platform detection, and installation dispatch.
- **Helper Functions** – Reusable Bash utilities for GitHub asset resolution, cryptographic verification, archive extraction, and MCP configuration.

## The Bootstrap Manifest

The [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) file serves as the single source of truth for the bootstrap mechanism. It declares **bootstrapDependencies** (such as `pipx` and `pnpm` versions required by the installer itself) and **capability entries** specifying source repositories, release tags, asset regular expressions, and expected checksums.

Parsed via thin Python wrappers (`manifest_field` and `manifest_dependency`), the manifest enables the script to resolve tool metadata without hardcoding URLs. For example, the **jadx** entry specifies the GitHub repository `skylot/jadx`, the asset regex `^jadx-1\.5\.6\.zip$`, and the release tag `v1.5.6`, allowing the bootstrapper to locate and verify the correct binary dynamically.

## Execution Flow and Orchestration

### CLI Argument Parsing and Environment Detection

When invoking `bash skills/scripts/bootstrap-reverse.sh jadx apktool --mcp-host=claude`, the script first collects arguments through a dedicated parsing block (lines 50-63). The `--list` flag outputs all capabilities defined in the `ALL_CAPABILITIES` array, while `--mcp-host=` determines whether the system performs MCP registration.

Platform detection occurs via `uname -s`, yielding `linux` or `macos` to drive conditional installer selection. The script then validates **Python 3** presence, which remains mandatory for safely extracting nested JSON fields from the manifest.

### Preparing Bootstrap Dependencies

Before installing user-requested tools, the mechanism ensures its own runtime dependencies exist. The `ensure_python_runtime` chain installs `pipx` and `pnpm` through platform-appropriate methods—`install_github_release` for Linux or `install_brew`/`install_apt` for macOS—ensuring the bootstrapper can handle Python and Node-based tools later in the process.

## Dependency Resolution and Expansion

Security tools often require companion utilities. The `cap_depends` function defines these edges (for instance, `idapro` requiring `idalib-mcp`), while `expand_capabilities` (lines 97-118) builds a flattened, de-duplicated installation list. This dependency graph resolution prevents duplicate installations and ensures dependent services start before their consumers.

## The Six-Step Capability Installation Pattern

Each tool installation follows a standardized workflow implemented in `ensure_capability` and specific installer functions like `ensure_jadx` or `ensure_apktool`:

1. **Existence Check** – The `has_cmd` utility verifies if the binary already exists in `$PATH` to skip redundant work.
2. **Runtime Provisioning** – Installs required language runtimes (Java, Node.js, Python) via `ensure_java_runtime` or similar helpers if missing.
3. **Asset Resolution** – `latest_github_asset_meta` queries the GitHub API to resolve the correct release URL based on the manifest's regex and tag constraints.
4. **Cryptographic Verification** – Downloads the asset via `curl`, then `verify_sha256` compares the digest against the manifest entry or falls back to the GitHub API-provided checksum.
5. **Extraction and Placement** – `extract_archive` unpacks the binary into `$TOOLS_ROOT` (defaulting to `~/tools`), preserving directory structures.
6. **Path Activation** – Exports the binary location to `$PATH` (e.g., `export PATH="$dest/bin:$dest:$PATH"`) for immediate availability.

The **jadx** installer (lines 267-279) exemplifies this pattern, detecting macOS to prefer Homebrew before falling back to GitHub release installation, while Linux proceeds directly to `install_github_release`.

## Platform-Specific Installation Strategies

The bootstrap mechanism adapts to different ecosystems through specialized installer functions:

- **`install_github_release`** – Downloads and verifies release assets for most Linux tools.
- **`install_brew`** – macOS package manager integration for native binaries.
- **`npm-global`** – Installs Node-based tools like `agent-browser` via `npm install -g`.
- **`winget-package`** – Windows package manager commands for tools like `nmap`.
- **`go-install`** – Compiles Go binaries from module paths with Docker fallback.
- **`local-http-mcp`** – Clones repositories, runs `pnpm install` and `pnpm dev`, then registers local MCP endpoints after port verification.

## MCP Server Registration

When users specify `--mcp-host=claude`, `--mcp-host=codex`, or `--mcp-host=both`, the bootstrapper invokes `write_mcp_server` (lines 78-98) to generate client-specific configuration files. Claude integration writes to `~/.claude/mcp.json`, while Codex uses `~/.codex/config.toml`.

For remote MCP capabilities (e.g., `xquik-mcp`), the script registers only the URL endpoint. For local services like `anything-analyzer`, it additionally executes `wait_for_port` and `test_mcp_http` to verify the service responds on its designated port (e.g., 23816) before finalizing registration.

## Practical Usage Examples

List every supported capability defined in the manifest:

```bash
bash skills/scripts/bootstrap-reverse.sh --list

```

Install a single tool with automatic platform detection and SHA-256 verification:

```bash
bash skills/scripts/bootstrap-reverse.sh jadx

```

Deploy multiple tools and start background services (waits for port availability):

```bash
bash skills/scripts/bootstrap-reverse.sh anything-analyzer --start-services

```

Register MCP configurations for both Claude and Codex without installing tools:

```bash
bash skills/scripts/bootstrap-reverse.sh --mcp-host=both

```

Skip the tool-index regeneration (useful for CI pipelines):

```bash
bash skills/scripts/bootstrap-reverse.sh jadx --skip-refresh

```

## Summary

- The reverse-skill bootstrap mechanism uses [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) as the central orchestrator and [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) as the declarative source of truth.
- **Dependency expansion** via `expand_capabilities` ensures tools install in the correct order with duplicates removed.
- Every installation follows a six-step pattern: existence check, runtime provisioning, asset resolution, SHA-256 verification, archive extraction to `$TOOLS_ROOT`, and path activation.
- Platform detection (`uname -s`) enables Linux-specific GitHub releases, macOS Homebrew integration, Windows winget support, and containerized Go builds.
- **MCP registration** automatically configures Claude and Codex clients when `--mcp-host` is specified, with health checks for local services.
- Exit codes indicate success (0), partial failures (1), or manual steps required (2).

## Frequently Asked Questions

### How does reverse-skill verify tool integrity during auto-installation?

The system uses the `verify_sha256` function to compare downloaded binaries against SHA-256 digests stored in [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json). If the manifest lacks a hash, the bootstrapper falls back to the digest provided by the GitHub API during asset resolution. This cryptographic verification occurs before extraction to prevent supply chain attacks.

### Can I customize the installation directory for reverse-skill tools?

Yes. The bootstrapper respects the `$TOOLS_ROOT` environment variable, defaulting to `~/tools` if unset. You can override this to install tools to a specific location:

```bash
TOOLS_ROOT=/opt/security-tools bash skills/scripts/bootstrap-reverse.sh jadx

```

### What platforms does the reverse-skill bootstrap mechanism support?

The script explicitly handles **Linux** and **macOS** through `uname -s` detection. Linux installations prefer GitHub releases or `apt`, while macOS utilizes Homebrew for native packages. Windows support exists for specific tools through `winget-package` entries, though the primary orchestrator targets POSIX environments.

### How do I register MCP servers without installing tools?

Use the `--mcp-host` flag without specifying capability names. The command `bash skills/scripts/bootstrap-reverse.sh --mcp-host=both` generates configuration files for Claude and Codex containing all defined MCP endpoints without downloading or extracting any binaries.