How to Configure the reverse-skill Project: Complete Setup Guide

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	https://adoptium.net/
Node.js ≥ 22.12	Runs the JS toolchain, MCP servers, and anything-analyzer	https://nodejs.org/
Python ≥ 3.x	Executes Frida scripts and helper utilities	https://python.org/
AI client	Consumes the routing pack (Claude Code, Codex CLI, Cursor, etc.)	–

These requirements are documented in README.md#prerequisites.

Clone the Repository

Start by cloning the reverse-skill repository to your local machine:

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#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 (PowerShell-centric)
Kali Linux	kali/README-kali.md
Ubuntu/Debian/Mint/Pop!_OS	docs/platforms/linux.md
macOS	docs/platforms/macos.md
Other / unknown	docs/PLATFORMS.md

Manual OS Detection Commands

Use these commands to confirm your platform before proceeding:

# 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 and tool-index.json files are git-ignored and must be generated fresh on each machine. This step is mandatory—RULES.md will abort execution if the tool index is missing.

Windows

powershell -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

Linux / macOS

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

Kali Linux

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

Reference: Refresh instructions appear in both the human README.md#installation and the AI bootstrap README_AI.md#0-first-instruction-for-the-ai.

Verify the Generated Index

After execution, inspect the tool availability report:

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 encodes the canonical behavior chain (steps 0-14). The AI must read this file after the tool-index is available:

less RULES.md

Reference: Full rule set at [RULES.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)

What the Rules Enforce

1. Authorization gate – 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 (primary fast ladder) or skills/routing.md (full matrix) to select sub-skills
4. Ops contracts – skills/ops/scope-contract.md, role-map.md, and 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 -File skills/scripts/case-init.ps1 -Hint "<your-task>"

Unix-like Systems

pwsh -File skills/scripts/case-init.ps1 -Hint "<your-task>"

This creates work/<case>/scope.md and injects required fields including auth.status=granted and network_profile.

Reference: 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 -File skills/scripts/master-route.ps1 -Hint "<your-task>"

Linux / macOS / Kali

# Via PowerShell Core

pwsh -File skills/scripts/master-route.ps1 -Hint "<your-task>"

# Or simply inspect the markdown controller

less skills/MASTER-ROUTING.md

The router reads 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

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):

{
  "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 -File ida-reverse/scripts/start.ps1

Quick-Start Checklist

Copy and execute these commands for rapid reverse-skill configuration:

# 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)	Human-oriented introduction and prerequisites
[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)	Global behavior chain with auth and routing guarantees
[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)	Full scenario → skill matrix
[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)	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) / .ps1	Tool index generators
skills/scripts/master-route.ps1	One-shot task router
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)	Kali-specific deployment
[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)	macOS deployment guide

Complete Ubuntu Configuration Example

Follow this end-to-end example for fresh Ubuntu machines:

# 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 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 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 and start the service with powershell -File <service>/scripts/start.ps1
Case init fails to write work/<case>/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 using the platform-specific refresh script—this is mandatory
• Load 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, 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 (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 and 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 and skills/tool-index.json with new yes/no entries. To make the tool routable, you must also add entries to skills/MASTER-ROUTING.md or 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/<case-id>/, starting with 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.

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