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

reverse-skill automatically routes security tasks by parsing user hints against regex keyword rules defined in 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, while the execution logic lives entirely within skills/scripts/master-route.ps1.

Configuration as the Single Source of Truth

The 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 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:

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

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

$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, 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:

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:

"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:

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:

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:

"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:

"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:

$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 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:

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

   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 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 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 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 (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. 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 documentation reflects the current routing.json state. This automated verification prevents the configuration drift that typically plagues manual routing systems.

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