How to Configure Custom Routing Rules in reverse-skill: A Complete Guide

To configure custom routing rules in reverse-skill, define a new route object in skills/config/routing.json, register the route ID in the priority array, create multilingual benchmark tests, and execute the verification scripts to validate routing coherence.

The reverse-skill repository implements a deterministic routing engine that matches user hints against regex keyword patterns to dispatch the appropriate reverse-engineering skill. When you configure custom routing rules in reverse-skill, you extend the single source of truth located at skills/config/routing.json while maintaining synchronization with automated test suites and documentation matrices.

Understanding the Routing Architecture

The routing system operates through a scoring mechanism implemented in skills/scripts/master-route.ps1 (Windows) and master-route.sh (Linux/macOS/Kali). These entry-point scripts load skills/config/routing.json and execute the following logic:

1. Keyword Matching – Each route defines regex patterns in the keywords array. The router calculates scores by counting pattern matches against the user hint.
2. Priority Resolution – When multiple routes achieve identical scores, the priority array (located near line 324) determines the winner through deterministic ordering.
3. Fallback Handling – If no keywords match, the router defaults to the route specified by fallbackId (typically R0 at lines 5–7).

Every route object requires a unique ID (e.g., R40), a human-readable label, a skill path pointing to the corresponding SKILL.md file, and a keywords array containing objects with must (regex pattern) and note (description) properties.

Step-by-Step Guide to Adding Custom Routes

Step 1: Define the Route Object in routing.json

Open skills/config/routing.json and add a unique entry to the routes object. Use a standardized ID format like R40:

{
  "R40": {
    "label": "Web API reverse",
    "skill": "web-api-reverse/SKILL.md",
    "keywords": [
      {
        "must": "swagger|openapi|rest.?api|graphql|api.?reverse|web.?api|http.?service",
        "note": "Matches any hint mentioning API specifications or HTTP-service reverse engineering"
      }
    ]
  }
}

Insert this object within the existing routes map, maintaining consistent ordering with other route definitions.

Step 2: Update the Priority Array

Locate the priority array near the end of routing.json (around line 324). Append your new route ID to establish tie-breaking precedence:

"priority": [
  "R1", "R2", "...", "R39", "R40"
]

Routes appearing earlier in this array take precedence when multiple candidates achieve identical match scores.

Step 3: Create Multilingual Benchmark Tests

Update skills/tests/routing-benchmark.json with test cases in both English and Chinese to validate the new route:

{
  "hint": "I need to reverse engineer a swagger API",
  "expected": "web-api-reverse/SKILL.md"
}

The CI test suite (skills/scripts/test-routing.ps1 and test-routing.sh) executes these benchmarks to ensure the routing logic correctly identifies your skill across language contexts.

Step 4: Verify Routing Coherence

Execute the verification script to confirm that routing.json remains synchronized with skills/MASTER-ROUTING.md:

# Windows

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

# Linux/macOS/Kali

bash skills/scripts/verify-routing-coherence.ps1

Successful execution returns ALL PASS, indicating no drift exists between the JSON configuration and the human-readable documentation matrix.

Step 5: Execute the Full Test Suite

Validate your changes against the complete routing test harness:

# Windows PowerShell

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1

# Unix-based systems

bash skills/scripts/test-routing.sh

The output should indicate comprehensive success (e.g., 166/166 ALL PASS). If tests fail, refine the keywords regex patterns or adjust the priority ordering.

Key Files in the Routing Ecosystem

• skills/config/routing.json – Central configuration containing all route definitions, keyword regex patterns, and the priority ordering array.
• skills/scripts/master-route.ps1 – Windows entry point that executes the scoring and selection logic.
• skills/scripts/master-route.sh – Unix entry point supporting Linux, macOS, and Kali distributions.
• skills/tests/routing-benchmark.json – Test harness containing multilingual example hints and expected skill outcomes.
• skills/scripts/verify-routing-coherence.ps1 – Cross-platform linting tool ensuring JSON and documentation alignment.
• skills/MASTER-ROUTING.md – Human-readable reference matrix documenting route priorities and descriptions.

Summary

To successfully configure custom routing rules in reverse-skill:

• Define new route objects in skills/config/routing.json with unique IDs, regex-based keywords, and skill paths.
• Register route IDs in the priority array to establish deterministic tie-breaking behavior.
• Test changes by adding English and Chinese entries to routing-benchmark.json and executing the test scripts.
• Verify coherence between configuration and documentation using verify-routing-coherence.ps1.
• Maintain consistency with MASTER-ROUTING.md to ensure developer reference materials remain accurate.

Frequently Asked Questions

How does reverse-skill resolve routing conflicts when multiple routes match?

When multiple routes achieve identical match scores against a user hint, the router consults the priority array in skills/config/routing.json to deterministically select the winner. Routes appearing earlier in the array take precedence over later entries, ensuring consistent skill selection even with ambiguous inputs.

What regex syntax does reverse-skill support for keyword patterns?

The must field within keyword objects accepts standard regular expressions supported by PowerShell and Bash regex engines. This includes alternation (e.g., swagger|openapi), optional quantifiers (e.g., rest.?api), and character classes. The patterns are evaluated case-sensitively by the master-route.ps1 and master-route.sh scripts.

Is it mandatory to update MASTER-ROUTING.md when adding custom routes?

While the JSON file serves as the single source of truth, you must run verify-routing-coherence.ps1 to ensure skills/MASTER-ROUTING.md remains synchronized. This verification step is mandatory for CI/CD compliance, though the markdown file functions as human-readable documentation rather than operational code.

What happens if I omit my route ID from the priority array?

Omission from the priority array does not prevent route matching, but it removes deterministic tie-breaking capability. When multiple routes achieve identical scores, the system cannot guarantee which skill executes, potentially causing unpredictable routing behavior. Always register new IDs in the priority array to ensure consistent, reproducible results.

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