# How to Build the reverse‑skill Project from Source: A Complete Setup Guide

> Learn how to build the reverse-skill project from source. This guide covers installing dependencies, cloning the repo, and running bootstrap scripts for AI-driven reverse engineering. No compilation needed.

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

---

**The reverse‑skill project does not require compilation; "building" consists of installing runtime dependencies, cloning the repository, and running bootstrap scripts to generate the tool index and prepare the environment for AI‑driven reverse engineering.**

The **reverse‑skill** repository by zhaoxuya520 is a modular collection of routing scripts, skill definitions, and helper utilities designed for AI‑assisted reverse engineering workflows. Since it is a pure‑text codebase without compiled components, building it from source means setting up the runtime environment and generating the local tool index that enables the routing system to discover and invoke external binaries. This guide covers every step for Linux, macOS, and Windows systems based on the actual source code structure.

---

## Prerequisites for Building reverse‑skill

Before cloning the repository, install the core runtime dependencies that power the various skills and scripts.

| Dependency | Minimum Version | Purpose | Installation Command |
|------------|---------------|---------|-------------------|
| **Java JDK** | 17+ | Powers `jadx`, `apktool`, and other Java‑based reverse engineering tools | Linux: `sudo apt install openjdk-17-jdk`<br>macOS: `brew install openjdk` |
| **Node.js** | 22+ | Runs MCP bridge scripts and JavaScript‑based skills | Linux: `sudo apt install nodejs npm`<br>macOS: `brew install node` |
| **Python** | 3.x (with `pipx`) | Executes Frida scripts, helper utilities, and Python‑based skills | Linux: `sudo apt install python3 python3-venv python3-pip pipx`<br>macOS: `brew install python` |
| **AI client** | — | Claude Code, Codex CLI, Cursor, or similar agent that drives the router | Install from vendor documentation |
| **Platform toolkits** | — | Android SDK, radare2, Ghidra, Burp Suite, etc. (detected post‑setup) | See [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) after running the refresh script |

> **Tip:** After installing the prerequisites above, the repository's own **tool‑index** generator will probe your system and produce a personalized list of missing external binaries with exact install commands for your platform.

---

## Step 1: Clone the reverse‑skill Repository

Since the project contains no compiled artifacts, cloning is sufficient to obtain the complete source.

```bash
git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill

```

The repository structure includes:
- `skills/scripts/` — bootstrap and routing scripts
- `skills/` — skill definitions and auto‑generated index files
- `docs/platforms/` — OS‑specific setup documentation
- `kali/` — specialized instructions for Kali Linux

---

## Step 2: Generate the Tool Index

The **tool index** is the heart of the reverse‑skill routing system. Running the refresh script is mandatory; it detects installed tools and writes both human‑readable and machine‑readable indices.

### Linux / macOS

```bash
bash skills/scripts/refresh-tool-index.sh

```

### Windows (PowerShell)

```powershell
powershell -File skills/scripts/refresh-tool-index.ps1

```

Upon completion, the script outputs:

```

✅ Tool index refreshed
  markdown=skills/tool-index.md
  json=skills/tool-index.json

```

The generated **[`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)** contains a table with:
- Detected tool names and versions
- Missing tool indicators
- Platform‑specific **install‑hint** strings (e.g., `apt: sudo apt install radare2`)

Follow these hints to install any missing dependencies before proceeding.

---

## Step 3: Verify Routing Coherence (Optional)

A validation script checks that the generated tool index aligns with the routing manifest defined in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md).

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

```

If the script reports **OK**, your environment is correctly aligned with the routing tables.

---

## Step 4: Complete Platform‑Specific Setup

The repository provides detailed setup guides for common platforms. Consult the file matching your operating system:

| Platform | Documentation Path | Special Notes |
|----------|-------------------|---------------|
| Linux / Debian / Ubuntu | [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) | Standard `apt` workflows |
| macOS | [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) | `brew`‑based installation |
| Kali Linux | [`kali/README-kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md) | Includes [`kali/scripts/quick-setup.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/quick-setup.sh) helper |

These files contain exact commands for installing remaining external binaries such as **radare2**, **Ghidra**, or **Burp Suite** that the tool index identified as missing.

---

## Step 5: Invoke the reverse‑skill Router

With the index built, you can now use the system via AI client integration or direct command‑line invocation.

### Via AI Client

Configure your AI agent (Claude Code, Codex CLI, etc.) to call the routing endpoints. The agent reads [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) to select appropriate skill chains.

### Via Command Line

Run the master routing script for one‑shot triage:

#### Linux / macOS (requires PowerShell Core)

```bash
bash skills/scripts/master-route.ps1

```

#### Windows

```powershell
powershell -File skills/scripts/master-route.ps1

```

The script:
1. Parses [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) for routing rules
2. Consults [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) for the skill matrix
3. Launches the appropriate tool chain (e.g., `jadx` → [`frida-run.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/frida-run.sh) → `graphviz`)

---

## Complete Build Example: Ubuntu

Below is a verified command sequence for a fresh Ubuntu 22.04/24.04 system. Adapt package manager commands for macOS using `brew`.

```bash

# Install core runtimes

sudo apt update && sudo apt install -y openjdk-17-jdk nodejs npm python3 python3-venv python3-pip pipx

# Clone the repository

git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill

# Generate tool index (detects existing tools, identifies gaps)

bash skills/scripts/refresh-tool-index.sh

# Review missing tools and install them

cat skills/tool-index.md

# Example: install radare2

sudo apt install radare2

# Example: install Ghidra manually per the install-hint in the index

# Optional: verify routing coherence

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

# Run a master route (e.g., APK analysis)

pwsh skills/scripts/master-route.ps1

```

---

## Key Source Files in reverse‑skill

| File | Purpose |
|------|---------|
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Detects tools, generates [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and `.json` |
| `skills/scripts/master-route.ps1` | Primary routing entry point for AI agents and CLI use |
| `skills/scripts/verify-routing-coherence.ps1` | Validates routing tables against the manifest |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Skill matrix defining tool chains for each analysis scenario |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Routing rules governing how inputs map to skills |
| [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) / [`macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/macos.md) | Platform‑specific dependency installation |
| [`kali/README-kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md) | Kali Linux quick‑start with automated setup script |

---

## Summary

- **No compilation required** — reverse‑skill is a pure‑text routing system.
- **Three core dependencies** — Java JDK 17+, Node.js 22+, and Python 3.x with `pipx`.
- **Mandatory bootstrap** — run [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) (Linux/macOS) or `.ps1` (Windows) to generate the tool index.
- **Self‑documenting setup** — the generated [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) tells you exactly which external binaries are missing and how to install them.
- **AI‑ready** — once indexed, invoke via `master-route.ps1` or integrate with Claude Code, Codex CLI, or Cursor.

---

## Frequently Asked Questions

### Does reverse‑skill require compilation or a build system like Make or CMake?

No. The reverse‑skill repository contains only scripts, markdown documentation, and routing definitions. As confirmed by the source structure, there are no `Makefile`, [`CMakeLists.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CMakeLists.txt), or compiled artifacts. Building the project means preparing the runtime environment and generating the local tool index.

### What happens if I skip running the refresh‑tool‑index script?

The routing system will fail to locate external binaries. The `skills/scripts/master-route.ps1` script and AI client integrations depend on [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) to resolve tool paths. Without this file, skill invocations will error with "tool not found" messages even if the binaries are installed on your system.

### Can I use reverse‑skill on Windows without PowerShell?

Partially. While the refresh script has a dedicated `.ps1` version for Windows, the `master-route.ps1` script currently requires PowerShell Core (`pwsh`) on all platforms. The repository is designed primarily for Unix‑like environments; Windows users should install PowerShell Core for full functionality.

### How do I keep my tool index current after installing new reverse engineering tools?

Simply rerun the refresh script:

```bash
bash skills/scripts/refresh-tool-index.sh

```

This updates both [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) (human‑readable) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) (machine‑readable) with newly detected tools and versions. The routing system automatically picks up these changes on the next invocation of `master-route.ps1`.