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

Configure routing rules in reverse-skill by editing skills/config/routing.json to define route objects with unique IDs, keyword patterns (must, exclude, mustAll), and skill paths, then update the priority array to resolve ties, and validate changes using the verify-routing-coherence and test-routing scripts.

The reverse-skill repository uses a centralized JSON-driven routing system to match user requests against specialized markdown skill modules. All routing logic is defined in a single configuration file that determines which skill handles each query based on regex keyword scoring and priority resolution. Understanding how to properly configure these routing rules is essential for extending the system or fine-tuning request handling.

Understanding the Routing Architecture in reverse-skill

The routing system operates through skills/config/routing.json, which serves as the single source of truth for request dispatching. This file contains a schema definition, a fallback route (R0) for unmatched requests, and a priority array that breaks ties when multiple routes achieve identical match scores.

Core Components of routing.json

Each route entry (e.g., R1, R2) contains three required fields: label for human-readable identification, skill pointing to the relative path of the markdown implementation (e.g., apk-reverse/SKILL.md), and keywords—an array of pattern objects.

Keyword objects support four pattern types:

• must – A regular expression that must be present in the request for the rule to match
• exclude – A regular expression that must not be present for the rule to match
• mustAll – An array of additional regex patterns that all must match simultaneously
• note – Free-form comments used by maintainers to document pattern intent

How the Routing Engine Evaluates Requests

The engine, implemented in skills/scripts/master-route.ps1 and skills/scripts/master-route.sh, processes requests through a four-stage pipeline:

1. Keyword matching – The request text is scanned against every route's must, exclude, and mustAll patterns
2. Scoring – A route gains one point for each keyword rule that successfully matches
3. Priority resolution – The route with the highest score wins; if scores tie, the engine selects whichever route appears first in the priority array
4. Fallback – If no route matches, the system defaults to route R0 (general reverse-engineering)

How to Add a New Route in reverse-skill

Adding a routing rule requires modifying both the routes object and the priority array in skills/config/routing.json.

1. Create a unique route ID inside the "routes" block using a fresh Rxx identifier that does not clash with existing keys (e.g., R42).

2. Define the route object with the required schema:

"R42": {
  "label": "Terraform security",
  "skill": "terraform-security/SKILL.md",
  "keywords": [
    { 
      "must": "terraform|tf|infrastructure.?as.?code|iac", 
      "note": "Detect IaC security queries" 
    }
  ]
}

3. Insert the new route ID into the "priority" array at the appropriate position. Routes earlier in the array win ties, so place the ID where you want it to rank relative to existing routes:

"priority": [
  "R4", "R1", "R41", "R42", "R0"
]

4. Run the verification script to ensure consistency:

powershell -File skills/scripts/verify-routing-coherence.ps1

Or on Linux/macOS:

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

5. Test the change with the routing test suite:

powershell -File skills/scripts/test-routing.ps1

How to Modify Existing Routing Rules

Refining Keyword Patterns with Exclude Rules

To prevent false positives, add exclude patterns to disambiguate overlapping routes. For example, to prevent the "APK reverse" route (R1) from matching LLM-related queries:

{
  "must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b",
  "exclude": "llm|prompt|jailbreak",
  "note": "Prevent LLM-related queries from matching R1"
}

Adjusting Route Priority

To change which route wins when multiple routes match with equal scores, reorder the IDs in the "priority" array. Move more specific routes earlier in the list to ensure they take precedence over general-purpose routes.

Common Routing Configuration Mistakes

Issue	Why it Happens	How to Avoid
Duplicate route IDs	JSON keys must be unique within the routes object	Use a fresh Rxx number each time you add a route
Mis-ordered priority	The priority array does not contain the new route ID	Always edit the priority array immediately after adding or removing a route
Over-broad must regex	Causes unrelated requests to be routed incorrectly	Use word boundaries (\b) and specific terms; test with the routing scripts
Missing exclude in conflicting keywords	Two routes can both match the same request, leading to unexpected routing	Add exclude patterns to disambiguate or adjust the priority order

Testing and Validating Your Changes

After editing skills/config/routing.json, validation is mandatory before the changes take effect. The skills/scripts/verify-routing-coherence.ps1 (and its Bash counterpart verify-routing-coherence.sh) checks that:

• Every route ID in routes appears exactly once in the priority array
• No duplicate IDs exist in either section
• The JSON structure adheres to the expected schema

Once verification passes, execute skills/scripts/test-routing.ps1 or skills/scripts/test-routing.sh to run the functional test suite. These scripts simulate requests against your new patterns to confirm they match intended queries and exclude unintended ones.

The markdown documentation in skills/MASTER-ROUTING.md and the generated summary in skills/INDEX.md are automatically synchronized by the master scripts, so you only need to edit skills/config/routing.json directly.

Summary

• skills/config/routing.json is the central configuration file for all routing rules in the reverse-skill repository
• Each route requires a unique ID (Rxx format), descriptive label, skill path to the markdown module, and keywords array
• Keywords use must, exclude, and mustAll regex patterns to determine matches; scores are tallied to select the best route
• The priority array determines the winner when multiple routes achieve identical match scores
• Always run verify-routing-coherence and test-routing scripts after modifications to ensure system integrity

Frequently Asked Questions

What is the format of the routing.json file in reverse-skill?

The file contains a JSON object with a schema section (version metadata), a priority array (ordered list of route IDs), and a routes object containing key-value pairs where keys are route IDs like R1, R2, and values are objects specifying label, skill (relative path to markdown), and keywords (array of pattern objects with must, exclude, mustAll, and note fields).

How do I prevent false positives when configuring routing rules?

Use the exclude field in keyword objects to block unwanted matches, and employ word boundaries (\b) in your must regex patterns to ensure you match whole words rather than substrings. Always test patterns using skills/scripts/test-routing.ps1 or skills/scripts/test-routing.sh before finalizing changes.

What happens if two routes have the same match score?

The routing engine consults the priority array in skills/config/routing.json and selects whichever route appears first in that ordered list. Place more specific routes earlier in the array to ensure they win ties against general-purpose routes that might also match.

Where are the routing validation scripts located?

The verification and test scripts reside in skills/scripts/, including verify-routing-coherence.ps1 and verify-routing-coherence.sh for checking JSON consistency, plus test-routing.ps1 and test-routing.sh for functional validation of pattern matching logic.

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