How reverse-skill Routes AI Agent Tasks to Cybersecurity Skills: A Technical Deep-Dive

reverse-skill uses a deterministic routing pipeline that matches user prompts against a keyword matrix in routing.json, scores matches by priority, and dispatches to the appropriate SKILL.md module for execution.

The open-source reverse-skill framework provides a structured, reproducible way to translate natural-language security requests into concrete cybersecurity workflows. At its core lies a deterministic routing system that eliminates guesswork by enforcing explicit pattern matching, priority-based arbitration, and tool-verified execution. This article examines the exact mechanism by which the framework routes AI agent tasks to specialized cybersecurity skills.

The Routing Pipeline: 8 Stages from Prompt to Execution

The routing architecture follows a strictly sequential pipeline defined in docs/ARCHITECTURE.md and implemented across PowerShell scripts and JSON configuration files.

Stage 1: Intent Detection via Keyword Matrix

When a user submits a prompt, the system first consults skills/config/routing.json to identify whether the request contains security-relevant trigger keywords.

Each route entry (e.g., R1, R2, R3) defines:

• A label for human readability
• A skill path pointing to a SKILL.md file
• A keywords array with must patterns (regular expressions that must match) and optional exclude patterns

For example, the APK reverse engineering route (R1) uses this pattern set:

{
  "R1": {
    "label": "APK reverse",
    "skill": "apk-reverse/SKILL.md",
    "keywords": [
      {
        "must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b|android.?reverse|安卓|反编译.?apk|apk.?加固|重打包|root.?detect|root.?检测|证书.?校验|certificate.?pinning|pinning.?绕过|签名.?校验",
        "note": "android 裸词/root 检测/证书校验/pinning 绕过 均为 APK 分析常见诉求"
      }
    ]
  }
}

The engine compiles these regular expressions and evaluates them against the normalized user prompt.

Stage 2: Building the Candidate Route Set

If multiple routes match, the system collects all candidates rather than terminating early. This allows priority-based arbitration in the next stage. The matching engine respects both must and exclude patterns, ensuring false positives are filtered before scoring.

Stage 3: Priority-Based Route Arbitration

The priority array in routing.json establishes a total ordering for tie-breaking:

"priority": [
  "R4", "R1", "R2", "R3", "R30", "R31", "R33", "R5",
  "R9", "R21", "R22", "R6", "R7", "R8", "R34", "R28",
  "R17", "R16", "R18", "R24", "R37", "R23", "R35",
  "R25", "R36", "R29", "R38", "R32", "R26", "R27",
  "R10", "R11", "R12", "R13", "R14", "R15", "R19",
  "R40", "R20", "R39", "R0"
]

Routes are sorted first by match score, then by their position in this array. The highest-scoring route with the earliest priority index becomes the PRIMARY route. This deterministic ordering prevents non-deterministic routing and ensures consistent behavior across identical prompts.

Stage 4: Primary Path Resolution via MASTER-ROUTING.md

The skills/MASTER-ROUTING.md file mirrors the priority array and maps each route to its concrete skill directory. This file serves as the execution contract between the routing engine and skill modules.

When the primary route is selected, the engine extracts the skill field value (e.g., apk-reverse/SKILL.md) and prepares for execution.

Stage 5: Tool Chain Verification

Before launching any skill, the system validates that all required external tools are available by consulting skills/tool-index.md. This inventory tracks:

• Tool installation status
• Version compatibility
• Executable paths

Missing tools trigger the bootstrap-reverse.ps1 self-installation process.

Stage 6: Bootstrap-Driven Tool Installation

The bootstrap system reads bootstrap-manifest.json to determine installation strategies per tool:

flowchart TD
    Need[检测到缺少工具] --> ReadManifest[读取 bootstrap-manifest.json]
    ReadManifest --> Kind{安装类型?}
    Kind -->|github-release-zip| GH[下载 ZIP 解压]
    Kind -->|pip-package| Pip[pip install]
    GH & Pip --> Verify{验证可用?}
    Verify -->|成功| AddPath[加入 PATH 并刷新 tool-index]
    Verify -->|失败| Manual[输出手动安装指引]

Supported installation types include github-release-zip, pip-package, npm-package, and manual. Successful installation refreshes tool-index.md and updates the system PATH before proceeding.

Stage 7: Skill Execution

With tooling verified, the AI client opens the selected SKILL.md and follows its prescribed workflow. These skill files contain:

• Step-by-step procedural instructions
• PowerShell or Python script invocations
• Expected outputs and validation criteria
• Error handling paths

The execution is deterministic: the same prompt, routed to the same skill, produces the same sequence of operations.

Stage 8: Evidence Generation and Self-Evolution

Post-execution, results flow through two final modules:

• case-review/SKILL.md — generates structured evidence graphs validating findings
• docs-generator/SKILL.md — produces final reports and visual diagrams

Outcomes are written to field-journal for audit trails. The routing index (routing.md) updates if new patterns emerge, enabling the system to improve future routing accuracy without manual intervention.

Entry Point: master-route.ps1

The entire pipeline is invoked through a single PowerShell entry point:

# Resolve the user hint to a primary skill and execute it

powershell -File skills\scripts\master-route.ps1 -Hint "I need to analyse a malicious Android APK"

This script orchestrates stages 1–7, delegating to helper functions for pattern matching, priority sorting, and tool verification. It returns structured output suitable for downstream evidence processing.

Key Architecture Benefits

• Deterministic routing — same input always produces same output, critical for forensic reproducibility
• Explicit prioritization — human-readable priority array prevents routing conflicts
• Self-healing toolchain — automatic dependency resolution reduces operational friction
• Audit-ready execution — complete logging through field-journal enables compliance verification
• Evolvable patterns — runtime updates to routing indices improve accuracy without code changes

Summary

• reverse-skill routes AI agent tasks through an 8-stage deterministic pipeline from routing.json keyword matching to SKILL.md execution
• Pattern matching uses regular expression matrices with must/exclude rules, scored and arbitrated by a priority array
• Tool verification via tool-index.md triggers automatic bootstrap installation before any skill runs
• Entry point at skills/scripts/master-route.ps1 accepts natural language hints and orchestrates full execution
• Self-evolution through field-journal feedback ensures routing accuracy improves with each operation

Frequently Asked Questions

How does reverse-skill handle ambiguous prompts that match multiple skills?

The framework collects all matching routes, scores each by pattern strength, then applies the priority array in routing.json as a tie-breaker. The route with the highest score and earliest priority position wins. This deterministic arbitration prevents random selection and ensures consistent routing for similar prompts.

What happens if a required tool is missing during skill execution?

The system reads tool-index.md to detect missing dependencies, then invokes bootstrap-reverse.ps1 to install them automatically. The bootstrap process consults bootstrap-manifest.json for per-tool installation strategies (GitHub releases, pip, npm, or manual). Only after successful verification does execution proceed to the skill itself.

Can the routing patterns be customized for organizational needs?

Yes. The routing.json file uses a standard JSON schema where each route defines label, skill path, and keyword patterns. Administrators can add new routes, modify regular expressions, or reprioritize the array. Changes take effect immediately on the next prompt without restarting the routing engine, as master-route.ps1 reads the configuration at runtime.

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