Most autonomous coding agents fail at security tasks for a predictable reason: they hallucinate tool paths and dive straight into execution without establishing methodology. Point an LLM at an unpacked binary, an obfuscated frontend script, or a CTF binary, and it will often attempt brute-force bash calls instead of systematically triaging the target.
Reverse-Skill addresses this failure mode directly. Rather than treating an agent as an unconstrained operator, Reverse-Skill acts as a deterministic skill-routing engine, tool indexer, and self-evolving knowledge repository. It structures environments like Claude Code, Codex CLI, Cursor, Cline, and Windsurf around a simple invariant: the agent must read the routing rules before invoking a single tool.
Architectural Overview: Route First, Execute Second
The framework is structured into two core layers:
- Core Routing & Control Layer: Contains the routing logic, centralized entry points, dynamic tool indexes, and migration validation scripts.
- Knowledge Base Layer: Houses domain-specific datasets and capture-the-flag matrices, positioned under the package root to preserve relative path integrity.
reverse-skill/
├── RULES.md # Global routing constraints and bootstrap rules
├── skill_routing_matrix.md # Target-to-skill dispatch matrix
├── ctf_routing_matrix.md # CTF-specific triage paths
├── entrypoints/
│ └── main.py # Central orchestrator entry point
├── scripts/
│ ├── tool_index_refresh.py # Local toolchain discovery and indexing
│ └── idapro_mcp_entry.py # IDA Pro HTTP service wrapper
└── experience_journal/
├── index.md # Central index of solved edge-cases
└── field_journal_logs/ # Structured write-backs (YYYYMMDD_scenario.md)
Integrating Reverse-Skill with an agent relies on four foundational pillars:
- The Package Directory: The physical root where scripts, rules, and indices reside.
- The MCP / External Tool Bridge: The communication layer exposing local execution endpoints to the agent.
- Prompt Injection Configuration: Pinning workspace instructions to load global rules on startup.
- Methodology Enforcement: Enforcing a strict "Route First, Execute Second" constraint where
RULES.mdandskill_routing_matrix.mdare evaluated before execution begins.
The Dispatch Matrix: Mapping Contexts to Capabilities
When an agent encounters a target, it consults skill_routing_matrix.md or ctf_routing_matrix.md instead of guessing execution parameters. This routes the problem space to concrete workflows and specialized toolchains.
| Scenario | Recommended Entry Point |
|---|---|
exe / dll / so / elf | skill_routing_matrix.md#binary_reverse_engineering |
Frontend signature / encrypted parameters | skill_routing_matrix.md#frontend_analysis_and_evasion |
HTTP capture / browser sampling / request replay | anything-analyzer + skill_routing_matrix.md#dynamic_browser_analysis |
Penetration testing / port scanning / vulnerability scanning | skill_routing_matrix.md#network_penetration_testing |
Firmware / IoT / router pentesting | skill_routing_matrix.md#firmware_iot_penetration_testing |
N-day / patch diff / CVE PoC writing | skill_routing_matrix.md#n_day_vulnerability_research |
Exploit writing / pwn / stack-heap-kernel exploitation | skill_routing_matrix.md#exploit_development |
EDR / AV bypass / red-team delivery | skill_routing_matrix.md#red_team_operations |
Browser/desktop automation | skill_routing_matrix.md#browser_desktop_automation |
Symbol migration / cross-version comparison | skill_routing_matrix.md#symbol_management |
Diagrams / architecture diagrams / attack-path diagrams | skill_routing_matrix.md#diagram_generation |
CTF challenge | ctf_routing_matrix.md |
Toolchain Indexing and Runtime Verification
A common failure in agentic workflows is assuming dependencies exist in standardized global paths. Reverse-Skill decouples path configuration from execution logic by relying on a dynamically generated tool_index.json.
| Category | Tool Stack | Architectural Role |
|---|---|---|
| Core Runtimes | Python, Git | Base automation and execution layer. |
| Android / APK Analysis | JD-GUI, APK-Tool, Jadx | Bytecode decompilation and asset extraction. |
| Dynamic & Browser Tools | anything-analyzer, jshookmcp | DOM inspection, script hooks, and HTTP interception. |
| Static Binary Analysis | IDA Pro, Ghidra, Radare2 / Cutter | Disassembly, decompilation, and control-flow recovery. |
| Domain Knowledge Base | CTF Knowledge Base | Structured references for competitive security problems. |
Bootstrapping the Environment
On any new deployment or post-migration setup, the local environment must be scanned to reconcile tool locations. The bundled tool_index.json should never be trusted across machines.
bashpython scripts/tool_index_refresh.py
This updates tool_index.json with absolute paths valid for the current host.
When integrating deep static analysis via IDA Pro, the agent interfaces through an HTTP MCP wrapper:
bashpython scripts/idapro_mcp_entry.py
This service launches the background HTTP handler, confirms endpoint availability, and isolates critical system binaries into a temporary staging directory to bypass OS file-locking issues.
For dynamic runtime analysis, anything-analyzer exposes an MCP endpoint (configured by default at http://localhost:23816/). If port bindings, addresses, or authentication tokens shift across environments, the client MCP configuration must be updated to maintain the bridge.
The Auto-Evolution Loop: Experience Journals
Static rule sets degrade as target architectures and toolchains change. Reverse-Skill enforces continuous state capture by requiring the agent to log actionable post-mortems into experience_journal/field_journal_logs/.
Write-backs are triggered automatically when:
- A complex reverse engineering or testing workflow completes.
- A runtime toolchain conflict or environment trap is resolved.
- A bootstrap defect within the routing framework is identified and patched.
- An edge case outside the baseline routing matrix is encountered.
- A task fails, but the root cause provides verifiable negative constraints.
Every log entry uses the naming format YYYYMMDD_scenario.md and contains the target environment state, exact reproduction commands, verified solutions, and edge-case boundaries. Before executing a task, the agent checks experience_journal/index.md to avoid previously documented operational failures.
Migration Auditing and Fallback Modes
When moving the framework between environments (such as changing operating systems, usernames, or disk layouts), paths must be audited systematically. Hardcoded script references inside MCP configs, RULES.md, and helper scripts must be reconciled before execution starts.
If an automated capability installation fails, the agent is restricted from generating speculative workarounds. Instead, it must switch to Guided Manual Configuration Mode and present a deterministic recovery playbook:
markdown**[Capability Name]** **[Issue Description]** **Manual Steps:** 1. [Step 1] [Verification command] 2. [Step 2] [Verification command]
For instance, if ida-pro-mcp fails to bind, the framework guides the operator through cloning the repository, deploying the IDA plugin, initializing the service manually, and validating HTTP connectivity from the MCP client.
Operating Boundary & Bottom Line
Reverse-Skill is built specifically for authorized security assessments, educational research, and CTF competitions. Operating against targets without explicit authorization is illegal, and operators carry full responsibility for execution safety.
By enforcing rigid routing matrices, dynamic tool indexing, and continuous write-back journaling, Reverse-Skill converts coding agents from unpredictable conversational models into disciplined, repeatable engineering systems.
Repository Reference: https://github.com/zhaoxuya520/reverse-skill