reverse-skill: A Routing Layer That Tells AI Agents Which Reverse Engineering Tool to Use

What Problem This Routing Pack Solves

AI agents that receive a task like 'decompile this APK' often guess between jadx, apktool, Frida, IDA, and BurpSuite. The README states this directly: agents don't know which tool fits which task, and each task type needs a different playbook. reverse-skill addresses that by acting as a decision layer between the user's request and the actual tool execution. It is for teams doing authorized penetration testing, security research, and CTF work who use Claude Code, Codex, Cursor, OpenCode, or another compatible client. The package does not perform the reverse engineering itself. It routes the agent to a methodology, checks what tools are available on the machine, and then runs a workflow that produces a timeline and an Evidence to Finding to Path report. The intended user is someone who already has a toolchain installed and needs structure around it.

The Routing Architecture: One JSON File Drives Everything

The core of the system is a single structured configuration file at skills/config/routing.json. The README calls it the 'routing single source of truth' and lists 43 rules labeled R0 through R44. A PowerShell script, skills/scripts/master-route.ps1, reads that file and performs one-shot primary triage. The data flow is explicit in the README: user task goes to RULES.md, then to MASTER-ROUTING or master-route.ps1, then to case-init which creates a scope.md containing auth and network profile information. No target action happens until that scope is ready. After that, the scenario skill runs, which may invoke tools, MCP servers, or scripts. The output is a timeline plus an Evidence to Finding to Path structure, ending in a report and a field journal. This design keeps the routing logic separate from client-specific adapters, which is why the same routing.json can work across Claude Code and Cursor. The separation is a deliberate choice: the routing core is validated by cross-platform CI on Windows and Ubuntu, while client adapters remain optional.

Getting It Running: Clone, Refresh the Tool Index, Then Let the Agent Read

Installation is a git clone: git clone https://github.com/zhaoxuya520/reverse-skill.git. There is no package manager step. After cloning, you must refresh the local tool index so the router knows what is installed. On Windows the command is powershell -File skills/scripts/refresh-tool-index.ps1. On Linux or macOS it is bash skills/scripts/refresh-tool-index.sh. Kali Linux has its own script at kali/scripts/refresh-tool-index.sh. The generated file skills/tool-index.md lists detected tools. The prerequisites are Java or JDK for jadx and apktool, Node.js 22.12 or later for the JS toolchain and MCP servers, and Python 3.x for Frida and helper scripts. The README tells AI agents to read README_AI.md first and follow its instructions strictly. That file is the bootstrap for the agent, while RULES.md holds the global routing rules and the scope gate. The key operational file is skills/scripts/case-init.ps1, which creates a case directory with scope, timeline, and workitems.

Scope Gate and Authorization: A Real Constraint, Not a Slogan

The README emphasizes that case-init creates a scope.md with auth and network_profile, and that no target ACT occurs until ready. This is a meaningful design point, not a marketing phrase. The routing rules include a scope gate before any action. That means the system is built to refuse or pause work on a target that has not been authorized. For a pentesting tool, this is the difference between a script that fires commands blindly and one that forces a checkpoint. However, the gate is only as strong as the rules in RULES.md and the agent's obedience to them. If an AI client ignores instructions, the gate is advisory. The README does not claim any technical enforcement mechanism, such as a sandbox or a network block. So the scope gate is a procedural control, not a security boundary. Anyone using this in a real engagement must verify that the agent actually stops when scope.md is missing or when auth is not confirmed.

Scenario Coverage: Where the Router Has Playbooks

The routing matrix lists 21 scenario entries. APK and Android analysis lives in skills/apk-reverse. Binary reverse for exe, dll, so, and elf files is split between skills/ida-reverse and skills/radare2. Frontend JS and encrypted parameters go to skills/js-reverse. There are dedicated modules for .NET, DSL VM custom opcode, malware with YARA, pentest scanning, attack chain orchestration, case review, and CTF with a separate orchestrator containing 42 sub-skills. Firmware and IoT, patch diff for N-day, pwn and exploit development, EDR bypass, API and GraphQL, supply chain and SBOM, and LLM security each have their own folder. OLLVM deobfuscation is a reference file. The breadth is substantial, but the README does not state how deep each playbook goes. Some entries like 'EDR bypass' and 'attack chain' are sensitive and may not be appropriate for all users. The routing matrix is the map, but the actual quality depends on the content inside each skill directory, which is not detailed in the README.

Maintenance and Upgrade Cost: A Single Source of Truth, But You Maintain the Tools

The project centralizes routing rules in routing.json, which makes updates to the routing logic a matter of editing one file. The README mentions a regression benchmark of 173 cases, which suggests that changes to routing.json can be validated against a known set of tasks. That is a maintenance advantage over scattering rules across multiple skill files. However, the tool index is auto-generated, meaning you must rerun the refresh script after installing or removing tools. The README does not describe an automated update mechanism for the skill modules themselves. You clone the repo and pull updates, but the local tool index is your responsibility. The license is MIT, which permits commercial use and modification with attribution. There is no mention of a contribution process beyond a link, so the upgrade path is community-driven. The last push is dated 2026-08-08 with a v1.0.1 release, so the project is active, but the README does not specify a changelog policy beyond a CHANGELOG.md file.

Limitations and When This Is the Wrong Tool

The most obvious limitation is that reverse-skill does not install or manage the reverse engineering tools. It only checks what is present and routes accordingly. If jadx is missing, the router cannot magically produce a decompilation. The README lists prerequisites, but the user must install Java, Node, and Python, plus the actual tools like IDA Pro, radare2, or Ghidra. The 'Built With' section names those three, but IDA Pro is commercial and not free. That is a cost barrier for some teams. Another limitation is the reliance on an AI agent to follow the routing rules. The system is only as disciplined as the model behind the client. If the agent decides to skip the scope gate or misread the routing matrix, the evidence trail breaks. For teams that need deterministic, non-AI-driven tool orchestration, a traditional script or a CI pipeline would be more reliable. Also, the README does not mention any support for mobile iOS beyond a folder, and the depth of the CTF orchestrator is unknown from the README.

A Real Alternative: Direct Tool Scripts vs. AI Routing

The alternative to reverse-skill is not another AI skill pack; it is writing direct shell or PowerShell scripts that hardcode the toolchain for each scenario. For example, a team could have a script that takes an APK path and runs apktool decode, then jadx, then a manifest parser, without any AI involvement. That approach is deterministic, fast, and does not depend on a model's judgment. The difference is that a direct script cannot handle a novel task that does not match a prewritten pattern. reverse-skill's routing.json and the AI agent can adapt to an unfamiliar binary or a CTF challenge by reading the scenario skill and choosing a tool on the fly. But that flexibility comes at the cost of unpredictability and the need to trust the agent's reasoning. For a strictly repeatable pipeline, such as a CI job that analyzes every new APK the same way, a direct script is simpler and easier to audit. reverse-skill is better suited for exploratory work where the task varies and the agent needs a decision framework.

Editorial conclusion

Adopt reverse-skill if you run AI agents against reverse engineering and pentesting tasks and want a repeatable, client-neutral routing layer that checks installed tools before acting. Do not adopt it if you expect it to install tools or guarantee authorization; the scope gate and auth check are your responsibility. Before use, verify that routing.json matches your tool paths, run the refresh-tool-index script for your platform, and read RULES.md to confirm the scope gate matches your legal boundaries. The project's value is in the routing decision and evidence structure, not in the tools themselves.

Official sources

1. Official README
2. Project repository
3. Release notes