reverse-skill: a routing pack that stops AI coding agents from guessing reverse engineering commands

The problem reverse-skill solves is tool choice, not tool capability

Ask an AI coding agent to look at an APK and it will often reach for whatever command name it saw most often in training data. The README states the motivation plainly: agents "don't know whether to use jadx, apktool, Frida, IDA, or BurpSuite for a given task." That is a routing problem rather than a knowledge problem. The model usually knows what jadx does; it does not know that this particular task is a static unpacking job rather than a dynamic hooking job, and it does not know which of those tools are installed on the machine it is running on.

The second problem the project names is continuity. The README lists scattered tools, MCP servers and scripts across machines, and says the same mistakes get repeated because experience is not reused. The answer here is a case directory: case-init creates a scope file and a timeline, and the workflow ends by writing findings into a report and a field journal. That is a project-management wrapper around an agent, and it is the part that will outlive any individual tool wrapper.

Who it is for: someone who runs Claude Code, Codex, Cursor, OpenCode or a similar client and does APK analysis, binary reversing, frontend JS deobfuscation, firmware work, CTF challenges or authorized penetration testing. The repository is explicit about the boundary in its own description, which frames the pack for reverse engineering, authorized penetration testing and security research. Nothing in the README suggests the routing assumes authorization; the scope gate is a separate file, RULES.md, and it is the user's job to honor it.

How the routing ladder works: one JSON file, a scope gate, then a scenario skill

The README prints the data flow as a chain. A user task enters RULES.md, then MASTER-ROUTING or master-route.ps1 as the primary triage, then case-init writes scope.md carrying auth and network_profile, and only then does a scenario skill dispatch to tools, MCP servers or scripts. Output flows into a timeline, then an Evidence to Finding to Path structure, then a report and a field journal.

The single source of truth is skills/config/routing.json, described as holding 43 rules labelled R0 through R44. Note the off-by-one in the README's own table: 43 rules, R0 to R44, is 45 labels. That inconsistency is small but it is the kind of thing you want to resolve by opening the file, because the count tells you how much of the matrix is actually populated. The status table also lists 173 regression cases and 44 tracked modules, with CI on Windows and Ubuntu.

The scope gate is the design decision worth pausing on. The README's flow diagram annotates the case-init step with "auth + network_profile; no target ACT until ready." In other words, the router deliberately refuses to act before the case has an authorization record and a network profile. For professional work that is the correct default. For a quick CTF flag grab it adds a step, and a user who does not read RULES.md will wonder why the agent keeps asking for scope. The client model is described as client-neutral, with optional client adapters kept separate from the routing core, which is why the same routing.json can serve Claude Code and Cursor without duplication.

Installing reverse-skill and running a first triage

Prerequisites listed in the README are Java or a JDK for jadx and apktool, Node.js 22.12 or newer for the JS toolchain and MCP servers, Python 3.x for Frida and helper scripts, and a compatible AI client. Installation is a clone with no package manager step.

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

The second step is refreshing the tool index, which is what makes routing honest about what you actually have. Pick the command for your platform.

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

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

On Kali Linux the README points at a separate path, kali/scripts/refresh-tool-index.sh, and at kali/README-kali.md for the platform notes. After the refresh, open skills/tool-index.md. That file is auto-generated and lists the tools the script detected. If jadx is missing from it, every APK route will be filtered accordingly, so this file is the first thing to verify rather than the last.

For a first real run, the README gives an agent bootstrap file and a one-shot triage script. Point your client at README_AI.md and it is told to follow the instructions strictly, then run the primary router.

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

What you should see is a route decision derived from routing.json plus a case directory created by case-init.ps1 containing scope, timeline and workitems. The README does not print sample output for master-route.ps1, so treat the first run as a check that the script resolves your routing.json path correctly on your platform.

Where reverse-skill gets in the way

The tool index is a snapshot, not a live check. You run refresh-tool-index and the file records what existed at that moment. Install Frida afterwards and the router may still route around it until you refresh again. The README does not describe a hook that re-runs the refresh automatically, so the index is a maintenance obligation rather than a background service.

The scope gate is a genuine cost in short sessions. RULES.md requires authorization and network profile context before the ACT phase. If you are working a CTF challenge in a sandbox, you will fill in a scope file for a target that needs no authorization record. The project does not document a bypass or a fast-path flag for that case, and inventing one is not something the README supports.

The coverage table is broad, and breadth is the risk. The scenario list runs from APK and iOS through firmware, EDR bypass, LLM security, supply chain and OLLVM deobfuscation. Some of those entries are directories with their own skills; others are a single reference markdown file, as with the OLLVM entry pointing at skills/reverse-engineering/references/ollvm-deobfuscation.md. A route into a reference document is not the same depth of support as a route into a module with scripts, and the README does not grade them. Check the directory before you assume a scenario is well covered.

Finally, the pack is PowerShell-first on the primary scripts. The README offers bash equivalents for the tool index and separate Linux and macOS platform docs, but the primary ladder names master-route.ps1 and case-init.ps1. On Linux you are relying on PowerShell Core being present or on the platform docs describing an alternative. Verify that before you plan around it.

How it differs from a plain MCP tool server

The obvious alternative is to skip the router and wire individual tools into your client directly, either as MCP servers or as shell commands the agent can call. That approach gives the model the same capabilities with none of the indirection. The difference in approach is where the intelligence sits: a tool server exposes an action and lets the model decide when to use it, while reverse-skill puts the decision in a declarative rules file and has the agent read the route rather than infer it.

That trade is real in both directions. A rules file of 43 entries is auditable and reviewable, and it produces the same route for the same task across sessions, which is what makes the case timeline meaningful. A model choosing freely will vary between runs. But a rules file cannot cover a task nobody wrote a rule for, and when routing.json has no match the README does not state what the fallback is. A tool server has no such gap because the model is always the fallback.

The second difference is the case artifacts. A raw tool server leaves no scope file and no timeline. If your work needs to hand a reviewable evidence chain to someone else, the case-review skill and the Evidence to Finding to Path structure are the reason to take on the extra layer. If nobody will ever read your notes, they are overhead.

Maintenance, licence and what a fork inherits

The repository is not archived, and the last push was on 2026-08-08, which is the same date as the v1.0.1 release. That is recent enough that the project is moving, but the release history you can see is a single tagged version, so there is no long track record of upgrade churn to reason about. A VERSION file sits at the top level alongside CHANGELOG.md, so version bumps should be traceable in the changelog.

The upgrade cost is concentrated in two files. routing.json is the single source of truth, and skills/INDEX.md and skills/tool-index.md are described as auto-generated. If you fork and edit routing.json, expect to re-run whatever generates INDEX.md, and expect merge conflicts there on every upstream pull. Local edits to the routing matrix are the most likely thing to break on upgrade.

Licensing is MIT, so the practical implication is that you can use, modify and redistribute the pack, including inside a commercial engagement, provided you keep the licence and copyright notice. That is a summary of the licence identifier given in the repository, not legal advice. One thing to check yourself: the pack references third-party tools such as IDA Pro, BurpSuite, radare2 and Ghidra. The MIT licence covers this repository, not those tools, and their own licences govern how you may ship or automate them.

Editorial conclusion

Adopt reverse-skill if you already run an AI coding client and you do authorized reverse engineering, malware triage or CTF work where a repeatable case directory matters more than raw speed. Do not adopt it if your work is unattended automation: the router assumes a human confirms scope before the ACT phase, and the README does not document a headless mode. Before trusting it, clone the repository, run the refresh script for your platform, and read skills/tool-index.md to confirm it detected the tools you actually have, because every routing decision downstream is filtered by that file.

Frequently asked questions

Official sources

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