How to Add New Routing Rules to routing.json in the reverse-skill Repository

To add new routing rules to routing.json in the reverse-skill repository, you must first create a regression test case, update the JSON configuration and priority array, synchronize the documentation tables, and verify coherence using PowerShell or Bash scripts before committing.

The reverse-skill repository implements a deterministic routing system that uses skills/config/routing.json as its single source of truth for all skill disambiguation decisions. When integrating new technologies or workflows that require custom routing logic, developers must follow a specific multi-step workflow to maintain consistency between the configuration, documentation, and automated test suites. This guide details the exact procedure based on the repository's source code and CI requirements.

Step-by-Step Workflow for Adding Routing Rules

The repository enforces a strict eight-step workflow to ensure that changes to routing.json are tested, documented, and synchronized across all platform-native routers (master-route.ps1 and master-route.sh).

1. Add a Regression Test Case

Before modifying any routing logic, insert a new test entry into skills/tests/routing-benchmark.json. This file serves as the regression suite that validates routing decisions.

Each case must specify the input hint and the expected rule ID. For example, when adding a "Ghidra headless" skill:

{
    "hint": "ghidra headless decompile",
    "expect": "R42",
    "quick": true
}

Place this block within the cases array. This guarantees that the new rule is exercised by the automated router tests and prevents future regressions.

2. Update routing.json

Modify skills/config/routing.json to add or alter a rule inside the routes object. Each rule requires a unique ID, a label, a skill path, and keyword patterns.

{
    "R42": {
        "label": "Ghidra headless",
        "skill": "ghidra-headless/SKILL.md",
        "keywords": [
            { "must": "ghidra|headless|analyzeheadless", "note": "Ghidra without UI" }
        ]
    }
}

If the new rule changes disambiguation precedence, adjust the priority array so the order matches the intended hierarchy. The priority array determines tie-breakers when multiple rules match a given input.

3. Synchronize the Priority Table

Open skills/MASTER-ROUTING.md and insert the new rule ID at the correct position in the priority table. The order in this markdown file must be identical to the priority array in routing.json.

This synchronization ensures that human-readable documentation remains consistent with the machine-readable configuration, which is critical for debugging routing decisions.

4. Verify Routing Coherence

Run the coherence verification script to enforce consistency between the JSON file, the markdown priority table, and any generated documentation.

On Windows:

.\skills\scripts\verify-routing-coherence.ps1

On Linux or macOS:

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

This script acts as an early guardrail, catching mismatches before they reach the CI pipeline.

5. Run the Router Test Suite

Execute the routing test harness against the benchmark file to ensure all cases pass. This script reads routing.json and validates every entry in routing-benchmark.json.

On Windows:

.\skills\scripts\test-routing.ps1

On Linux or macOS:

bash skills/scripts/test-routing.sh

All tests must pass before proceeding. This step confirms that the router correctly maps input hints to the new rule ID.

6. Regenerate the Tool Index

Update the master skill catalog by running the index refresh script. This regenerates tool-index.md, tool-index.json, and SKILL.md summaries, ensuring the new routing entry appears in the top-level documentation.

On Windows:

.\skills\scripts\refresh-tool-index.ps1

On Linux or macOS:

bash skills/scripts/refresh-tool-index.sh

7. Update Auxiliary Documentation (Optional)

If the new route requires explanatory context for human readers, edit skills/routing.md. This file provides a three-axis disambiguation view but is purely advisory; it does not affect routing logic. Changes here are not validated by coherence checks.

8. Commit and Validate via CI

Stage the modified files, which typically include:

• skills/config/routing.json
• skills/tests/routing-benchmark.json
• skills/MASTER-ROUTING.md
• Any regenerated index files

Commit and push your changes. The CI pipeline automatically runs the router tests and coherence checks; the pull request can only be merged after these checks succeed.

Core Files in the Routing System

Understanding the role of each file clarifies why the workflow requires specific synchronization steps:

• skills/config/routing.json: The single source of truth containing the routes object and priority array. All platform-native routers read this file directly.
• skills/tests/routing-benchmark.json: The deterministic test suite that protects against routing regressions.
• skills/MASTER-ROUTING.md: The human-readable priority table that must mirror the JSON priority array for documentation consistency.
• skills/scripts/verify-routing-coherence.ps1: The validation script that ensures JSON and markdown tables remain synchronized.
• skills/scripts/test-routing.ps1: The automated test harness that drives the router against the benchmark cases.
• skills/scripts/refresh-tool-index.ps1: The documentation generator that updates top-level catalogs after routing changes.
• skills/routing.md: An advisory documentation file providing alternative disambiguation views.

Summary

• Always add a regression case to routing-benchmark.json before modifying routing.json to maintain test coverage.
• routing.json is the single source of truth; only edit this file for routing logic changes, keeping the priority array synchronized with MASTER-ROUTING.md.
• Run verify-routing-coherence.ps1 (or .sh) locally to catch documentation mismatches before committing.
• Execute test-routing.ps1 (or .sh) to validate that all routing decisions match expected benchmark outputs.
• Regenerate indices with refresh-tool-index.ps1 to keep top-level documentation current.
• The CI pipeline enforces these checks automatically; merges are blocked until coherence and routing tests pass.

Frequently Asked Questions

What is the single source of truth for routing logic in reverse-skill?

The skills/config/routing.json file serves as the single source of truth. According to the source code, all platform-native routers (master-route.ps1 and master-route.sh) read this file directly to determine skill disambiguation, and it is the only file that should be edited for routing changes.

Why must I update routing-benchmark.json before modifying routing.json?

The repository treats the benchmark file as a regression prevention mechanism. Adding a test case first ensures that any subsequent changes to routing.json are immediately validated against a deterministic expected output, preventing silent failures that would break routing for existing skills.

What happens if the priority array in routing.json doesn't match MASTER-ROUTING.md?

The coherence verification script (verify-routing-coherence.ps1) will fail, blocking both local validation and CI pipeline execution. The priority array determines the disambiguation hierarchy when multiple rules match, so mismatches between code and documentation create uncertainty about actual routing behavior.

Are there Bash alternatives to the PowerShell scripts?

Yes. For every PowerShell script in skills/scripts/, a Bash equivalent exists with the same base name but a .sh extension. Use test-routing.sh, verify-routing-coherence.sh, and refresh-tool-index.sh on Linux, macOS, or Kali systems to perform identical validation and generation tasks.

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