How Reverse‑Skill Routes Cybersecurity Tasks to AI Agents

Reverse‑skill routes cybersecurity tasks by scoring user prompts against regex patterns defined in config/routing.json, selecting the highest‑priority match from the priority array, and consulting a three‑axis markdown matrix only when multiple routes achieve equal scores.

The zhaoxuya520/reverse-skill repository implements a data‑driven routing engine that matches natural‑language security requests to specialized AI agents. The system combines a canonical JSON configuration, a human‑readable disambiguation matrix, and cross‑platform execution scripts to determine the most appropriate skill module for any given cybersecurity task.

The Three‑Layer Routing Architecture

Reverse‑skill determines the correct AI agent by integrating three distinct data sources that work together to resolve ambiguity and ensure consistency.

Routing JSON: The Single Source of Truth

The config/routing.json file serves as the canonical routing definition. It contains:

• Route definitions (R1, R2, etc.) with keyword objects specifying must, exclude, and mustAll regex patterns
• Priority array (lines 325‑329) that determines the winner when multiple routes score
• Fallback configuration (fallbackId: "R0") for unmatched requests

Each route in the JSON structure accumulates a hit (score + 1) when a user input matches a must pattern. The exclude field cancels hits for false positives, while mustAll requires every listed pattern to be present before scoring.

Routing Matrix: Human‑Readable Disambiguation

The routing.md file provides a three‑axis view consulted only when the primary route is ambiguous:

1. Target Type (lines 18‑46) — APK, binary, firmware, cloud, etc.
2. User Intent (lines 71‑120) — Natural‑language phrasing such as "decode APK" or "bypass EDR"
3. Toolchain (lines 150‑210) — Concrete tools like IDA, radare2, Frida, or Playwright

When multiple routes achieve identical scores, the routing script falls back to this matrix to select the most specific skill. The matrix is purely advisory; any conflict resolves in favor of the JSON definition.

Routing Scripts: Execution Engine

The skills/scripts/ directory contains the execution protocol:

• master-route.ps1 / master-route.sh — Parses routing.json, computes scores, and selects the PRIMARY skill
• verify-routing-coherence.ps1 — Validates that every rule in the markdown matrix exists in JSON and vice‑versa
• test-routing.ps1 / test-routing.sh — Automated test harness executing sample prompts against expected routes

Scoring and Selection Logic

The routing engine evaluates user input through a deterministic scoring algorithm implemented in master-route.ps1.

Pattern Matching Rules

Each route contains keyword objects evaluated in sequence:

• must — Regex patterns that trigger a hit (score + 1) when matched
• exclude — Patterns that cancel a hit, preventing false positives
• mustAll — Requires all listed patterns to be present before counting the hit

Priority Resolution

After scoring all routes against the input, the script consults the priority array (lines 325‑329 in routing.json). The first route appearing in this array with the highest score becomes the PRIMARY skill. This ordering mechanism allows fine‑grained control over precedence when multiple skills could handle similar tasks.

Fallback Handling

If no route achieves a score, the system defaults to R0 (general reverse‑engineering) defined by fallbackId. According to routing.md lines 77‑88, unmatched requests also trigger a workflow prompting users to propose new skills, making the system self‑extending.

Handling Ambiguity with the Three‑Axis Matrix

When the scoring algorithm produces a tie, the engine invokes disambiguation logic using routing.md. The script maps the ambiguous input against the Target Type → User Intent → Toolchain axes to identify the most specific match.

For example, if both R3 (JS/frontend reverse) and R11 (pentest tools) score equally for the prompt "capture HTTP traffic and replay requests", the matrix consults the User Intent axis. Since "capture HTTP" aligns more closely with frontend reverse‑engineering analysis than infrastructure pentesting, the system selects R3 as the primary route.

Routing Scripts and Execution Protocol

The routing workflow follows a strict protocol enforced by the PowerShell and Bash implementations.

PowerShell Routing Example (Windows)

Invoke the master routing script with a raw user prompt:

# Route a cybersecurity task to the appropriate AI agent

$prompt = "I need to unpack an APK and bypass its certificate pinning"
.\skills\scripts\master-route.ps1 -Hint $prompt

The script returns a JSON object containing the selected route (R1), the skill path (apk-reverse/SKILL.md), and the matched keywords. This output directly determines which AI agent module receives the task.

Bash Test Suite (Linux/macOS)

Validate routing behavior across the entire skill matrix:

# Execute the full routing test suite

bash skills/scripts/test-routing.sh

The suite feeds representative prompts through the engine, verifies each resolves to the expected route, and reports discrepancies between actual and expected PRIMARY selections.

Coherence Verification

Before deploying changes, run the coherence validator:

.\skills\scripts\verify-routing-coherence.ps1

This script ensures that every rule documented in the three‑axis matrix has a corresponding entry in routing.json, preventing documentation drift.

Fallback and Extensibility

The routing architecture supports seamless extension through data‑driven configuration.

• Fallback Skill (R0) — Catches any request not matching specific routes, providing general reverse‑engineering capabilities
• Skill Proposals — When routing fails, the system surfaces the "Route Not Matched — Handling" protocol (lines 77‑88 in routing.md), prompting users to define new keyword patterns and priority entries

This design ensures that additions to routing.json or routing.md immediately alter the behavior of the AI agent selection engine without requiring code changes.

Summary

• Primary routing relies on config/routing.json, where regex patterns (must, exclude, mustAll) generate scores and the priority array (lines 325‑329) breaks ties.
• Disambiguation uses the three‑axis matrix in routing.md (Target Type, User Intent, Toolchain) only when multiple routes achieve equal scores.
• Execution is handled by master-route.ps1 (Windows) and master-route.sh (Linux/macOS), which parse the JSON and return the PRIMARY skill path.
• Validation scripts (verify-routing-coherence.ps1, test-routing.ps1) ensure JSON and markdown definitions remain synchronized.
• Fallback to route R0 and user‑driven skill proposals make the system self‑validating and extensible.

Frequently Asked Questions

How does reverse‑skill handle conflicting keyword matches?

When multiple routes match the same input, the system consults the priority array in routing.json (lines 325‑329). The route appearing earliest in this array with the highest score wins. If scores are identical and the priority array does not resolve the conflict, the engine falls back to the three‑axis matrix in routing.md to select the most specific match based on Target Type and User Intent.

What happens when no routes match the cybersecurity task?

If no route achieves a positive score, the system defaults to the fallback route R0 defined by fallbackId in routing.json. According to routing.md lines 77‑88, the system also initiates a "Route Not Matched" protocol that prompts the user to propose a new skill definition, allowing the routing table to expand organically.

Can the routing logic be tested without executing the full AI agent?

Yes. The repository includes test-routing.ps1 and test-routing.sh, which run a suite of sample prompts against the routing engine and validate the PRIMARY selection without invoking the actual skill modules. Additionally, verify-routing-coherence.ps1 checks that the JSON configuration and markdown matrix remain synchronized, catching schema drift before deployment.

Where is the routing priority order defined?

The priority array is defined in config/routing.json at lines 325‑329. This ordered list determines precedence when multiple routes achieve equal scores. Routes appearing earlier in this array take precedence over those appearing later, providing deterministic control over skill selection when keyword overlap occurs between different cybersecurity domains.

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