# How reverse-skill Automatically Routes Security Tasks to Different Modules: A Technical Deep Dive

> Discover how reverse-skill automatically routes security tasks. Learn about parsing user hints, regex keyword rules, and deterministic routing in this technical deep dive.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-24

---

**reverse-skill automatically routes security tasks by parsing user hints against regex keyword rules defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), scoring each candidate route, and selecting the primary module via a deterministic priority-ordered algorithm implemented in `master-route.ps1`.**

The `zhaoxuya520/reverse-skill` repository implements an intelligent, configuration-driven routing engine that automatically directs security analysis tasks to specialized skill modules without硬编码 logic. By centralizing routing definitions in a single JSON file and employing PowerShell-based pattern matching, the system ensures that tasks like APK reverse engineering, penetration testing, or vulnerability analysis reach the appropriate handler based on natural language hints.

## The Routing Architecture Pipeline

The routing system operates as a declarative pipeline where configuration drives behavior. All routing intelligence resides in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), while the execution logic lives entirely within `skills/scripts/master-route.ps1`.

### Configuration as the Single Source of Truth

The [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) file serves as the authoritative routing table, containing:
- Unique route identifiers (e.g., `R1`, `R11`, `R0`)
- Human-readable labels and skill module paths
- Regex-based keyword rules (`must`, `mustAll`, `exclude`)
- A `priority` array that defines tie-breaking precedence
- A `fallbackId` (defaults to `R0`) for unmatched inputs

### Runtime Execution Flow

When `master-route.ps1` receives a task hint, it executes a five-phase pipeline: loading configuration, normalizing input, pattern matching against keywords, scoring candidates, and applying priority-based selection. The script outputs a [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) file containing the primary route, confidence level, and secondary candidates.

## Step-by-Step Task Routing Logic

### 1. Loading and Normalizing Input

The router first loads the configuration and prepares the hint text. In `master-route.ps1` lines 28-30, the script reads the JSON configuration:

```powershell
$cfg = Get-Content $configPath -Raw -Encoding UTF8 | ConvertFrom-Json

```

The hint text undergoes normalization at lines 13-15 to ensure consistent matching:

```powershell
$t = if ($Hint) { $Hint.ToLowerInvariant() } else { '' }

```

Note that CJK characters remain unchanged during normalization, ensuring compatibility with Chinese security terminology like "反编译" (decompile) or "加固" (hardening).

### 2. Keyword Matching with Regex Rules

For each route defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), the script evaluates keyword objects containing three rule types:

- **`must`**: A regex that must match for the route to score
- **`mustAll`**: An array where all regexes must match
- **`exclude`**: A regex that cancels the hit if matched

The matching logic in `master-route.ps1` lines 39-50 implements these rules:

```powershell
if ($null -ne $kw.must -and $t -match $kw.must) { $hit = $true }
if ($hit -and $null -ne $kw.exclude -and $t -match $kw.exclude) { $hit = $false }

```

For example, the APK reverse engineering route (`R1`) uses a comprehensive regex pattern:

```json
"must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b|android.?reverse|安卓|反编译.?apk|apk.?加固|重打包|root.?detect|root.?检测|证书.?校验|pinning.?绕过"

```

### 3. Scoring and Priority Resolution

Each successful keyword hit increments the route's score. As implemented in lines 54-58:

```powershell
foreach ($item in $sel) {
    $scores[$item] = $scores[$item] + 1
}

```

The selection algorithm then walks the `priority` array (lines 73-87), checking scores in deterministic order. The first route with the highest score wins; if multiple routes share the top score, the one appearing earlier in the `priority` array receives the assignment.

### 4. Fallback Handling

When no keywords match, the system defaults to the `fallbackId`. Lines 91-94 in `master-route.ps1` implement this safety mechanism:

```powershell
if ($null -eq $primary) { $primary = $fallbackId }

```

This ensures that even ambiguous or novel task descriptions receive routing to a general-purpose handler rather than failing silently.

## Configuration Structure in routing.json

Each route entry follows a standardized schema linking keywords to skill modules:

```json
"R1": {
  "label": "APK reverse",
  "skill": "apk-reverse/SKILL.md",
  "keywords": [
    {
      "must": "\\bapk\\b|smali|jadx|...",
      "note": "android 裸词/root 检测/证书校验/pinning 绕过 均为 APK 分析常见诉求"
    }
  ]
}

```

The `priority` array at the bottom of the file defines the deterministic order:

```json
"priority": [
  "R4","R1","R2","R3","R30","R31","R33","R5","R9","R21","R0"
]

```

Routes listed earlier in this array take precedence when scores tie, allowing fine-grained control over routing behavior without modifying the matching logic.

## Runtime Implementation in master-route.ps1

The `master-route.ps1` script functions as the routing engine's brain. After scoring completes, it generates a structured output file at `$OutDir/route-scope.md` containing the primary route identifier, label, skill path, and confidence assessment. Lines 39-71 handle the output generation using explicit UTF-8 encoding to prevent character corruption:

```powershell
$utf8 = New-Object System.Text.UTF8Encoding $true
[System.IO.File]::WriteAllText("$OutDir/route-scope.md",$sb.ToString(),$utf8)

```

This design decouples the routing decision from execution, allowing downstream systems to consume the routing decision via the generated markdown file.

## Verification and Consistency Checks

The repository includes `skills/scripts/verify-routing-coherence.ps1` to maintain configuration integrity. This validation script performs several critical checks:

- **Schema validation**: Every route must contain `label`, `skill`, and `keywords` properties
- **Priority completeness**: The `priority` array must include every route ID exactly once
- **Documentation sync**: Verifies that [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) matches the JSON configuration
- **Hard-code detection**: Ensures `master-route.ps1` contains no embedded routing tables, enforcing the configuration-driven architecture

The verification script scans `master-route.ps1` for forbidden patterns like `$map = [ordered]`, failing the build if hard-coded routing logic is detected.

## Practical Usage Example

To route a task automatically, invoke the master router with a descriptive hint:

```powershell
.\skills\scripts\master-route.ps1 `
    -Hint "I need to decompile an APK, run jadx and check for root detection" `
    -OutDir "$env:TEMP\my-route"

```

Given this input, the router:
1. Matches keywords: `apk`, `jadx`, `root detection`
2. Scores route `R1` (APK reverse) highest
3. Generates [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md):
   ```markdown
   primary: R1
   primary_label: APK reverse
   primary_skill: skills/apk-reverse/SKILL.md
   secondary: (none)
   ```

Conversely, a hint like "run nmap on a host" matches the penetration testing route (`R11`) because its keywords include `nmap|masscan|metasploit|...`.

## Summary

- **reverse-skill** automatically routes security tasks through a configuration-driven pipeline defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and executed by `master-route.ps1`.
- The system uses **regex keyword matching** with `must`, `mustAll`, and `exclude` rules to score candidate routes based on user hints.
- **Priority-based selection** ensures deterministic routing when multiple routes match, using the ordered array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to break ties.
- A **fallback mechanism** (route `R0`) catches unmatched inputs, preventing routing failures.
- **Continuous verification** via `verify-routing-coherence.ps1` ensures the routing table, priority list, and documentation remain synchronized.

## Frequently Asked Questions

### How does reverse-skill handle ambiguous task descriptions?

When a hint matches multiple routes, **reverse-skill** applies the `priority` array defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) as a deterministic tie-breaker. The script iterates through the priority list in order, selecting the first route that achieves the highest score. This ensures consistent routing decisions even for complex hints that contain keywords from multiple security domains, such as "analyze this APK with Frida" (which might match both mobile and dynamic analysis routes).

### What happens if no keywords match the user hint?

If no regex patterns match the normalized hint, the router defaults to the `fallbackId` specified in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) (typically `R0`). As implemented in `master-route.ps1` lines 91-94, this fallback assignment ensures that every task receives a routing destination even when the input lacks recognizable security terminology, preventing pipeline failures and ensuring users always receive a skill module assignment.

### Can I add custom security modules to the routing system?

Yes, adding new modules requires only editing [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Create a new route entry with a unique ID, specify the `skill` path pointing to your module documentation, define appropriate `keywords` with regex patterns that identify your module's domain, and insert the ID into the `priority` array. The `verify-routing-coherence.ps1` script will validate your changes, ensuring the new route integrates correctly with the existing priority order and contains all required fields.

### How does the system prevent routing logic from drifting out of sync?

The `verify-routing-coherence.ps1` script enforces architectural integrity by continuously validating that no routing logic is hard-coded in `master-route.ps1` (checking for patterns like `$map = [ordered]`), ensuring the `priority` array contains exactly one entry per route, and verifying that [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) documentation reflects the current [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) state. This automated verification prevents the configuration drift that typically plagues manual routing systems.