How Reverse-Skill Routes AI Agents to Specific Security Analysis Methodologies

Reverse-Skill implements a deterministic, single-source-of-truth routing engine that parses natural language hints against a centralized JSON table to select the correct security analysis skill from 43 predefined methodologies.

The zhaoxuya520/reverse-skill repository provides a structured routing architecture that connects AI agents with specialized security capabilities. By enforcing rigid validation rules and platform-agnostic entry points, the system ensures that requests—whether targeting Windows Active Directory or kernel container escapes—resolve to concrete, tested workflows without ambiguity.

The Three-Component Routing Architecture

Reverse-Skill separates routing concerns into three tightly coupled layers that guarantee consistent behavior across Windows, Linux, macOS, and Kali environments.

Platform-Native Entry Points

The routing process begins with thin platform-specific wrappers located in skills/scripts/. On Windows, master-route.ps1 handles invocation, while Linux, macOS, and Kali systems use master-route.sh. Both scripts execute identical logic: they accept a user hint via the -Hint or --hint parameter, load the authoritative configuration, and return the PRIMARY skill directory. These scripts must read skills/config/routing.json at runtime; any hard-coded routing table triggers a failure in the CI validation suite.

The Authoritative Routing Table

All routing decisions derive from skills/config/routing.json, the sole authoritative definition of available routes. This file contains 43 structured rules, each specifying a label, target skill directory (e.g., skills/pwn-chain), and a keywords object with three matching patterns:

• must: Regular expressions where at least one must match
• mustAll: Patterns that must all match simultaneously
• exclude: Patterns that disqualify the route if matched

Routes are evaluated in the order defined by the priority array. The first route satisfying all keyword constraints is selected as the PRIMARY skill.

Advisory Disambiguation Matrix

When the JSON table cannot find a confident match, the system consults skills/routing.md. This human-readable file provides a three-axis view mapping keywords to skills with priority indicators. It serves strictly as an advisory fallback and never overrides the JSON source of truth.

Routing Execution Flow

The deterministic pipeline ensures traceability from natural language input to concrete skill execution through six distinct stages.

1. Router Invocation

An AI client triggers the platform router with a natural language hint. On Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "Enumerate AD domain trusts"

On Linux or macOS:

./skills/scripts/master-route.sh --hint "Exploit container breakout via kernel vulnerability"

2. Configuration Loading and Validation

The script constructs the absolute path to skills/config/routing.json using $configPath = Join-Path $skillsRoot 'config/routing.json' (PowerShell) or equivalent Bash logic. It validates the schema by confirming:

• Route count is ≥ 30
• Every route contains label, skill, and keywords fields
• The JSON is parsable and non-empty

Validation failures abort execution immediately, preventing the router from operating on stale or corrupted data.

3. Keyword-Based Route Selection

The router iterates through the routes array in priority order, testing the user hint against each rule's keyword constraints:

foreach ($route in $routing.routes) {
    if ($hint -match $route.keywords.must -and $hint -notmatch $route.keywords.exclude) {
        $selected = $route; 
        break
    }
}

The must patterns perform inclusive matching, while exclude patterns function as negative filters. The first matching route's skill field (e.g., wifi-wireless or competition-kernel-container-escape) determines the target directory under skills/.

4. Coherence Verification

Before execution, the build-time script verify-routing-coherence.ps1 cross-verifies the selected route against three consistency checks:

• All routing.json entries have corresponding entries in MASTER-ROUTING.md (the priority table)
• No route references a missing SKILL.md file in its target directory
• Priority arrays in documentation map 1-to-1 with JSON ordering

This script runs in every CI build and rejects any pull request containing hard-coded routing tables in the master routers.

5. Disambiguation Fallback

If no route matches with sufficient confidence, the orchestrator loads skills/routing.md to present the human-readable disambiguation matrix. This three-axis view (keywords ↔ skill ↔ priority) assists manual selection or auxiliary tooling, though the final routing decision still requires a valid JSON entry.

6. Skill Execution

Once resolved, the system loads the target skill's SKILL.md file (e.g., skills/pwn-chain/SKILL.md). This markdown file defines the concrete workflow, upstream entry points, and downstream actions, maintaining complete traceability from the initial hint through to methodology execution.

Safety Mechanisms and Extensibility

The architecture enforces four critical guarantees that prevent drift and ensure reliability:

• Single Source of Truth: Routing logic lives exclusively in routing.json. Files like MASTER-ROUTING.md and routing.md are generated or derived artifacts updated automatically by extract-summaries.ps1.
• Platform Consistency: Both PowerShell and Bash routers consume identical JSON configurations, ensuring Windows and Linux deployments route identically.
• CI Validation: verify-routing-coherence.ps1 validates against routing-benchmark.json test cases in every build, catching mismatches between documentation, tests, and runtime configuration.
• Schema Extensibility: Adding a new security methodology requires only a new entry in routing.json and an accompanying SKILL.md in the appropriate subdirectory; the matrix and priority documentation regenerate automatically.

Practical Routing Examples

Route a Windows Wi-Fi credential extraction request:

.\skills\scripts\master-route.ps1 -Hint "Extract saved Wi-Fi passwords from Windows"

# → Primary skill resolved to skills/wifi-wireless

Route a Linux kernel container escape on Kali:

./skills/scripts/master-route.sh --hint "Exploit container breakout via kernel vulnerability"

# → Primary skill resolved to skills/competition-kernel-container-escape

Summary

• Reverse-Skill routes AI agents through platform-native scripts (master-route.ps1 and master-route.sh) that enforce cross-platform consistency.
• The authoritative routing table (skills/config/routing.json) contains 43 keyword-driven rules using must, mustAll, and exclude patterns evaluated by priority.
• Coherence verification via verify-routing-coherence.ps1 prevents hard-coded tables and ensures documentation matches runtime behavior.
• An advisory disambiguation matrix (skills/routing.md) provides fallback guidance without overriding the JSON source of truth.
• The system guarantees traceability by linking every route to a concrete SKILL.md file defining the security analysis methodology.

Frequently Asked Questions

What file serves as the single source of truth for routing decisions?

The skills/config/routing.json file serves as the exclusive authoritative definition. All routing scripts must read this file at runtime; CI checks in verify-routing-coherence.ps1 explicitly reject any hard-coded routing tables found in the platform routers.

How does the router handle ambiguous or unclear user hints?

When keyword matching fails to produce a confident PRIMARY route, the system falls back to skills/routing.md. This three-axis disambiguation matrix provides a human-readable mapping of keywords to skills and priority levels, though it functions strictly as an advisory reference rather than an override mechanism.

What prevents the routing table from becoming inconsistent with documentation?

The verify-routing-coherence.ps1 script runs during every CI build to enforce consistency. It validates that routing.json matches entries in MASTER-ROUTING.md, confirms all referenced skill directories exist, and verifies that benchmark tests in routing-benchmark.json align with the current route definitions.

How do I add a new security analysis methodology to the routing system?

Extend routing.json with a new route entry specifying the label, target skill directory, and keywords object (including must, mustAll, and exclude arrays). Create the corresponding SKILL.md file in the target subdirectory under skills/. The extract-summaries.ps1 utility automatically updates routing.md and MASTER-ROUTING.md to reflect the new route.

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