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

> Discover how Reverse Skill routes AI agents to specific security analysis methodologies. Learn how it uses natural language hints and a JSON table to select the right skill from 43 predefined options.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "Enumerate AD domain trusts"

```

On Linux or macOS:

```bash
./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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) entries have corresponding entries in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) (the priority table)
- No route references a missing [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file (e.g., [`skills/pwn-chain/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). Files like [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) and [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and an accompanying [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) in the appropriate subdirectory; the matrix and priority documentation regenerate automatically.

## Practical Routing Examples

Route a Windows Wi-Fi credential extraction request:

```powershell
.\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:

```bash
./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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)) that enforce cross-platform consistency.
- The **authoritative routing table** ([`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) matches entries in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), confirms all referenced skill directories exist, and verifies that benchmark tests in [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file in the target subdirectory under `skills/`. The `extract-summaries.ps1` utility automatically updates [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) to reflect the new route.