# Core Components of the reverse-skill Architecture: A Deep Dive into the Cybersecurity Skills Router > Explore the core components of the reverse-skill architecture. Discover how markdown routing matrices, automation scripts, and ops contracts create deterministic cybersecurity workflows. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: deep-dive - Published: 2026-08-25 --- **The reverse-skill architecture consists of markdown-based routing matrices contract files, automation scripts, and ops contracts that transform vague cybersecurity tasks into deterministic, tool-aware workflows.** The reverse-skill repository by zhaoxuya520 implements a **routing-first, act-later** philosophy for AI-driven cybersecurity analysis. When an AI agent or human analyst submits a task, the system traverses a deterministic chain of contracts, matrices, and scripts to identify the exact skill (playbook) and required tooling. This article examines each architectural component with references to specific source files and their interactions. --- ## The Routing Layer: MASTER-ROUTING.md and routing.md The routing layer determines which skill directory handles a given task. It operates on a **fast-path with fallback** design. ### MASTER-ROUTING.md: The Primary Fast-Path Matrix Located at [[`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), this file maps high-level task keywords (APK, iOS, JS, firmware, etc.) directly to concrete skill directories. The matrix enables rapid skill selection without exhaustive pattern matching. ### routing.md: The Exhaustive Fallback Table When [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) cannot resolve a task, the system consults [[`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). This file contains the complete list of supported scenarios and their corresponding skill entries, ensuring no valid task goes unhandled. The routing scripts automate this two-tier lookup: ```bash # Execute the primary router with a user hint (PowerShell) powershell -File skills/scripts/master-route.ps1 -Hint "APK dynamic analysis" # Verify routing consistency across both matrices powershell -File skills/scripts/verify-routing-coherence.ps1 ``` --- ## Governance and Validation: RULES.md and Scope Contracts Before any action executes, the reverse-skill architecture enforces **gate-keeping rules** and **formal contracts**. ### RULES.md: Global Gate-Keeper The [[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) file at repository root mandates that every case must have an approved scope before tool invocation. This prevents unfocused or unauthorized operations. ### Ops Contracts in skills/ops/ The [`skills/ops/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/skills/ops) directory contains structured contracts that formalize workflow execution: - **scope contract**: Defines case boundaries and objectives - **evidence-finding-path**: Traces how artifacts are discovered and preserved - **role-map**: Assigns responsibilities to AI agents or human analysts - **timeline-workitem**: Tracks chronological progress - **sandbox-profile**: Configures isolated execution environments - **supply-chain checks**: Validates tool and data provenance The `case-init.ps1` script materializes these contracts into a working directory: ```bash # Initialize a new case with scope contract powershell -File skills/scripts/case-init.ps1 -Hint "firmware extraction" -CaseName "router-fw-2024" # Creates: work/router-fw-2024/scope.md with ops/ contracts applied ``` --- ## Skill Execution: SKILL.md Entry Points and tool-index.md Once routing completes, execution transfers to **skill-specific playbooks** with **dynamic tool verification**. ### SKILL.md: Per-Skill Execution Plans Every subdirectory under [`skills/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/skills) contains a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file. For example, [[`skills/ida-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ida-reverse/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ida-reverse/SKILL.md) specifies: - **ACTION-REQUIRED** description - Toolchain requirements - Step-by-step procedure - Expected outputs and validation criteria ### tool-index.md: Auto-Generated Tool Inventory The [[`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) file maintains real-time status of locally available tools: IDA Pro, Ghidra, Frida, radare2, JADX, and others. All scripts consult this index before execution to determine whether **bootstrap steps** are required. Refresh and query the tool inventory: ```bash # Regenerate tool status (Linux/macOS) bash skills/scripts/refresh-tool-index.sh # Read current tool availability cat skills/tool-index.md | grep -A2 "ida-pro" ``` --- ## Automation Layer: scripts/ Directory The [`skills/scripts/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/skills/scripts) directory implements the routing workflow in PowerShell and Bash: | Script | Function | |--------|----------| | `master-route.ps1` | Executes keyword-to-skill lookup | | `case-init.ps1` | Creates scoped work directories with contracts | | `bootstrap-tool-index.ps1` | Installs or configures missing tools | | `verify-routing-coherence.ps1` | Cross-checks [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) against [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) | | [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) | Linux/macOS tool discovery | These scripts bridge the markdown-based configuration layer with the operating environment. --- ## Knowledge and Experience: field-journal/ and CTF-Sandbox-Orchestrator/ The architecture incorporates **feedback loops** that improve routing accuracy over time. ### field-journal/: Real-World Precedents The [`skills/field-journal/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/skills/field-journal) directory archives actual case studies, seed exploits, and precedent documents. These feed back into routing matrix refinements—when a novel technique succeeds, it elevates to formal [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) documentation. ### CTF-Sandbox-Orchestrator/: Multi-Stage Challenge Engine The [`CTF-Sandbox-Orchestrator/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/CTF-Sandbox-Orchestrator) submodule demonstrates advanced orchestration capabilities. It coordinates 40+ sub-skills across multi-stage CTF challenges, proving the router can manage **complex dependency chains** and **stateful progression**. --- ## Documentation and AI Integration ### README_AI.md: Agent Bootstrap Protocol The [[`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) file specifies how AI agents should initialize: 1. Read [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) for constraints 2. Invoke `master-route.ps1` for skill selection 3. Execute `case-init.ps1` for scope formalization 4. Consult [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) before tool execution 5. Log outcomes to `field-journal/` ### docs/ and ARCHITECTURE.md The [`docs/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/docs) directory contains platform-specific installation guides, while [[`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) provides visual diagrams of component relationships. --- ## The Complete Workflow Execution A typical reverse-skill session follows this deterministic sequence: 1. **Validate**: [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) checks case approval status 2. **Fast-track**: [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) matches task keywords to skill directory 3. **Fallback**: [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) resolves edge cases not in fast-path 4. **Create**: `case-init.ps1` establishes `work//scope.md` with ops contracts 5. **Select**: Target [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) loads execution plan 6. **Verify**: [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) confirms tool availability 7. **Bootstrap**: `bootstrap-tool-index.ps1` installs missing dependencies 8. **Track**: Evidence, timeline, and roles recorded per `ops/` contracts 9. **Log**: Outcomes written to `field-journal/` for pattern learning --- ## Summary - **Two-tier routing**: [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) provides fast-path resolution; [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) serves as exhaustive fallback - **Contract-driven governance**: [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and `skills/ops/` enforce scope control, evidence handling, and role assignment - **Dynamic tool awareness**: [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) and bootstrap scripts ensure required tools are present before execution - **Modular skill architecture**: Each [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) encapsulates a complete playbook with toolchain specifications - **Learning feedback loop**: `field-journal/` captures real outcomes to refine future routing decisions - **CTF-grade orchestration**: The `CTF-Sandbox-Orchestrator` demonstrates scalability to complex multi-stage operations --- ## Frequently Asked Questions ### What is the difference between MASTER-ROUTING.md and routing.md? [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) is the **fast-path matrix** for common tasks—it maps high-frequency keywords directly to skill directories for millisecond-level resolution. [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) is the **comprehensive fallback** containing every supported scenario, consulted when fast-path lookup fails. According to the zhaoxuya520/reverse-skill source code, `master-route.ps1` attempts the fast-path first, then degrades gracefully to the full table. ### How does reverse-skill ensure required reverse engineering tools are available? The architecture uses **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** as a centralized, auto-generated inventory. Scripts query this file before execution; if a required tool (e.g., IDA Pro, Ghidra, Frida) is absent or misconfigured, **`bootstrap-tool-index.ps1`** triggers installation or reconfiguration. The [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) script updates the inventory on Unix systems. ### Can reverse-skill handle multi-stage cybersecurity operations? Yes. The `CTF-Sandbox-Orchestrator/` submodule demonstrates this capability by coordinating **40+ sub-skills** across complex CTF challenges. The `ops/timeline-workitem` contract tracks state between stages, and `ops/sandbox-profile` ensures isolated execution environments for each phase. ### What prevents unauthorized or unfocused operations in reverse-skill? The **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** file at repository root mandates **case-init scope approval** before any tool invocation. The `case-init.ps1` script enforces this by requiring a valid hint and case name, then generating a [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contract that bounds all subsequent actions. The `ops/scope` contract provides additional runtime enforcement.