# How to Configure the reverse-skill Project: Complete Setup Guide
> Configure the reverse-skill project with this complete setup guide. Install prerequisites, clone the repo, refresh the index, and run the master router for automated security tasks.
- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-04
---
**To configure reverse-skill, install Java/Node.js/Python prerequisites, clone the repository, run the platform-specific tool-index refresh script, and execute the master router to begin automated security task routing.**
The **reverse-skill** project is an open-source skill-router that automatically routes security-oriented tasks—APK analysis, binary reverse engineering, CTF challenges, and penetration testing—to the appropriate workflows. Proper configuration involves platform detection, local tool-index generation, and AI-agent bootstrap activation. This guide walks through each step using the actual source files from the `zhaoxuya520/reverse-skill` repository.
## Prerequisites for reverse-skill Configuration
Before running any scripts, ensure these components are installed on your machine:
| Component | Purpose | Install Source |
|-----------|---------|--------------|
| **Java / JDK** | Powers `jadx` and `apktool` for Android analysis | |
| **Node.js ≥ 22.12** | Runs the JS toolchain, MCP servers, and `anything-analyzer` | |
| **Python ≥ 3.x** | Executes Frida scripts and helper utilities | |
| **AI client** | Consumes the routing pack (Claude Code, Codex CLI, Cursor, etc.) | – |
These requirements are documented in [`README.md#prerequisites`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md#prerequisites).
## Clone the Repository
Start by cloning the reverse-skill repository to your local machine:
```bash
git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill
```
## Detect Platform and Select the Platform Document
The AI bootstrap flow in [[`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md#0-first-instruction-for-the-ai) instructs the agent to identify your operating system and load the matching platform guide:
| Detected OS | Platform Document |
|-------------|-------------------|
| **Windows** | [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) (PowerShell-centric) |
| **Kali Linux** | [`kali/README-kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md) |
| **Ubuntu/Debian/Mint/Pop!_OS** | [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) |
| **macOS** | [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) |
| **Other / unknown** | [`docs/PLATFORMS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/PLATFORMS.md) |
### Manual OS Detection Commands
Use these commands to confirm your platform before proceeding:
```bash
# Linux (including Kali)
cat /etc/os-release
# macOS
uname -s # returns "Darwin"
# Windows (PowerShell)
$env:OS
```
Open the corresponding markdown file and verify any required system packages (e.g., `adb`, `radare2`) are installed before continuing with reverse-skill configuration.
## Generate the Local Tool Index
The **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** and **[`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json)** files are **git-ignored** and must be generated fresh on each machine. This step is mandatory—[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) will abort execution if the tool index is missing.
### Windows
```powershell
powershell -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1
```
### Linux / macOS
```bash
bash skills/scripts/refresh-tool-index.sh
```
### Kali Linux
```bash
bash kali/scripts/refresh-tool-index.sh
```
Reference: Refresh instructions appear in both the human [`README.md#installation`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md#installation) and the AI bootstrap [`README_AI.md#0-first-instruction-for-the-ai`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md#0-first-instruction-for-the-ai).
### Verify the Generated Index
After execution, inspect the tool availability report:
```bash
cat skills/tool-index.md | head
cat skills/tool-index.json | jq .
```
The `yes/no` entries tell the router which tools are present on your host.
## Load Global Routing Rules
**[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** encodes the **canonical behavior chain** (steps 0-14). The AI must read this file **after** the tool-index is available:
```bash
less RULES.md
```
Reference: Full rule set at [[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)
### What the Rules Enforce
1. **Authorization gate** – [`ops/precedent-auth.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/precedent-auth.md) must be satisfied before any ACT
2. **Tool-index check** – verifies required binaries exist on the host
3. **Routing logic** – uses [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) (primary fast ladder) or [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) (full matrix) to select sub-skills
4. **Ops contracts** – [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md), [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md), and [`identity-federation/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/identity-federation/IDENTITY.md) define case-level context
## Initialize a New Case (Optional but Recommended)
For each distinct target, create a case directory with a scope file. The AI-bootstrap script automates this:
### Windows
```powershell
powershell -File skills/scripts/case-init.ps1 -Hint ""
```
### Unix-like Systems
```bash
pwsh -File skills/scripts/case-init.ps1 -Hint ""
```
This creates `work//scope.md` and injects required fields including `auth.status=granted` and `network_profile`.
Reference: [`skills/scripts/case-init.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.ps1)
## Run the Primary Router
The actual routing is performed by **MASTER-ROUTING**, implemented as a one-shot PowerShell script with a markdown controller file.
### Windows
```powershell
powershell -File skills/scripts/master-route.ps1 -Hint ""
```
### Linux / macOS / Kali
```bash
# Via PowerShell Core
pwsh -File skills/scripts/master-route.ps1 -Hint ""
# Or simply inspect the markdown controller
less skills/MASTER-ROUTING.md
```
The router reads [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) → selects the correct sub-skill (e.g., `apk-reverse`, `radare2`, `pwn-chain`) → launches associated scripts or MCP services.
Reference: [`skills/scripts/master-route.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.ps1)
## Verify MCP Connectivity (Optional)
If using built-in MCP servers (`anything-analyzer`, `jshookmcp`, `burp-mcp`), ensure they are reachable. Example configuration from [[`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md):
```json
{
"mcpServers": {
"anything-analyzer": { "url": "http://localhost:23816/mcp" },
"idapro": { "url": "http://127.0.0.1:13337/mcp" },
"jshook": {
"command": "npx",
"args": ["-y", "@jshookmcp/jshook@0.3.4"],
"env": { "JSHOOK_BASE_PROFILE": "search" }
}
}
}
```
Start required services as needed:
```powershell
powershell -File ida-reverse/scripts/start.ps1
```
## Quick-Start Checklist
Copy and execute these commands for rapid reverse-skill configuration:
```powershell
# 1. Refresh tool index
powershell -File "skills\scripts\refresh-tool-index.ps1"
# 2. Verify OS detection (optional)
(Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion").ProductName
# 3. Initialize a case
powershell -File "skills\scripts\case-init.ps1" -Hint "analyze sample.apk"
# 4. Run the master router
powershell -File "skills\scripts\master-route.ps1" -Hint "analyze sample.apk"
# 5. Start MCP services (optional)
powershell -File "ida-reverse\scripts\start.ps1"
```
## Key Configuration Files Reference
| File | Purpose |
|------|---------|
| [[`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) | Human-oriented introduction and prerequisites |
| [[`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) | AI-agent bootstrap, OS detection, and routing flow |
| [[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Global behavior chain with auth and routing guarantees |
| [[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Primary fast-ladder routing table |
| [[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Full scenario → skill matrix |
| [[`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) | Main controller entry point |
| [[`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Generated local tool availability report |
| [[`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) / [`.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.ps1) | Tool index generators |
| [`skills/scripts/master-route.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.ps1) | One-shot task router |
| [`skills/scripts/case-init.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.ps1) | Case directory and scope.md creator |
| [[`kali/README-kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/README-kali.md) | Kali-specific deployment |
| [[`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) | Ubuntu/Debian deployment guide |
| [[`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) | macOS deployment guide |
## Complete Ubuntu Configuration Example
Follow this end-to-end example for fresh Ubuntu machines:
```bash
# Install prerequisites
sudo apt update && sudo apt install -y openjdk-11-jdk python3 python3-pip nodejs npm unzip
# Clone repository
git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill
# Confirm platform
cat /etc/os-release | grep PRETTY_NAME # Ubuntu 24.04 LTS
# Generate tool index
bash skills/scripts/refresh-tool-index.sh
# Verify specific tool detection
grep -i "jadx" skills/tool-index.md
# Initialize case
pwsh -File skills/scripts/case-init.ps1 -Hint "apk-reverse: analyze sample.apk"
# Execute router
pwsh -File skills/scripts/master-route.ps1 -Hint "apk-reverse: analyze sample.apk"
# Optional: start IDA Pro MCP
pwsh -File ida-reverse/scripts/start.ps1
```
## Troubleshooting Common Configuration Issues
| Symptom | Cause | Solution |
|---------|-------|----------|
| [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) missing or empty | Refresh script not run or missing executables | Re-run the appropriate `refresh-tool-index` script; install missing tools (e.g., `sudo apt install radare2`) and retry |
| Master router aborts: "RULES.md: tool-index missing" | [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) loaded before index generation | Always run the refresh step **before** loading rules |
| MCP service connection refused | Wrong port or service not started | Verify JSON config in [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) and start the service with `powershell -File /scripts/start.ps1` |
| Case init fails to write `work//scope.md` | `work/` directory missing or permission denied | Create manually with `mkdir -p work` or re-run with write permissions |
| Windows script execution blocked | PowerShell execution policy restriction | Run with `-ExecutionPolicy Bypass` as shown in examples |
## Summary
- **Install prerequisites**: Java JDK, Node.js ≥ 22.12, Python 3.x, and an AI client
- **Clone** the `zhaoxuya520/reverse-skill` repository
- **Detect your OS** and read the matching platform documentation
- **Generate [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** using the platform-specific refresh script—this is mandatory
- **Load [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** to establish global routing rules
- **Create a case** with `case-init.ps1` for each new target
- **Run the master router** (`master-route.ps1`) to dispatch tasks to appropriate workflows
- **Start MCP services** as needed for IDA Pro, anything-analyzer, or other integrations
Following this configuration process prepares reverse-skill for automated security task routing on any supported host.
## Frequently Asked Questions
### What happens if I skip the tool-index refresh step?
The system will fail to route tasks. According to the source code in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the canonical behavior chain checks for tool-index presence at step 2, and aborts with an error if it's missing. Always run [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (or `.ps1` on Windows) before attempting any task routing.
### Can I use reverse-skill without PowerShell on Linux or macOS?
Yes. While `master-route.ps1` and `case-init.ps1` are PowerShell scripts, you can run them via **PowerShell Core** (`pwsh`). Alternatively, open the markdown controller files directly—[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) and [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md)—and follow the embedded instructions manually. The shell scripts in `kali/scripts/` and `skills/scripts/` provide native Bash alternatives for some operations.
### How do I add a new tool to the reverse-skill router?
Install the tool on your system, then re-run the appropriate `refresh-tool-index` script. The script scans your `$PATH` and updates [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) with new `yes/no` entries. To make the tool routable, you must also add entries to [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) or [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) mapping scenarios to your new tool's skill module.
### Where does reverse-skill store case work and logs?
Case-specific files are created under `work//`, starting with [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) generated by `case-init.ps1`. This directory is git-ignored. Operational logs and temporary artifacts from skill execution typically reside within the case directory or in tool-specific output folders defined by each sub-skill's scripts.