How to Add a New Routing Rule Without Breaking Existing Benchmarks

Add a failing benchmark case first, then update skills/config/routing.json and skills/MASTER-ROUTING.md, and finally run the local verification scripts to confirm all 173 test cases pass.

The reverse-skill project routes every hint to the correct skill through a single JSON-based routing system. Adding a new routing rule requires syncing four files: the routing configuration, the benchmark suite, the documentation table, and the verification scripts. This guide walks through the exact workflow used in the zhaoxuya520/reverse-skill repository.

The Routing Architecture

All routing decisions flow from skills/config/routing.json. This file contains:

• A routes object mapping route identifiers to skill metadata
• A priority array defining match order
• Match criteria: keywords, mustAll, and exclude fields

Platform-specific routers—skills/scripts/master-route.ps1 for Windows and skills/scripts/master-route.sh for Linux/macOS/Kali—parse this file at runtime to select the primary skill for a given hint.

The system enforces correctness through three verification layers:

• Regression benchmark: skills/tests/routing-benchmark.json with 173 hint-to-route test cases
• Coherence verification: skills/scripts/verify-routing-coherence.ps1 cross-checks JSON against documentation
• CI enforcement: .github/workflows/ci.yml runs all checks on every push

Step-by-Step Workflow to Add a New Routing Rule

Step 1: Create a Failing Benchmark Case

Before touching any routing logic, add a test case to skills/tests/routing-benchmark.json that will fail until your new rule exists. This test-driven approach guarantees the benchmark catches implementation gaps.

{
  "hint": "my new technique",
  "expect": "R99"
}

The benchmark runner will report "benchmark ghost expects" until the R99 route resolves this hint correctly.

Step 2: Edit routing.json

Insert the new route into skills/config/routing.json. Provide all required fields:

{
  "routes": {
    "R99": {
      "label": "New Technique",
      "skill": "skills/new-technique/SKILL.md",
      "keywords": ["newtech", "exploit"],
      "mustAll": [],
      "exclude": []
    }
  },
  "priority": ["R0", "R1", "...", "R99"]
}

Critical: Append the route identifier to the priority array in the correct position. Higher-priority routes appear earlier; the first matching route wins.

Step 3: Update MASTER-ROUTING.md

Add a corresponding row to skills/MASTER-ROUTING.md to maintain parity between machine-readable configuration and human documentation. The verify-routing-coherence.ps1 script validates this alignment—mismatches trigger "routing.json route count suspicious" errors.

Step 4: Run the Benchmark Locally

Execute the platform-appropriate test script before committing:

Windows:

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

Linux/macOS/Kali:

bash skills/scripts/test-routing.sh

All 173 cases must pass, including your new entry.

Step 5: Commit and Push

The CI workflow defined in .github/workflows/ci.yml automatically re-runs the benchmark suite. Any regression—missing routes, priority misordering, or documentation drift—will block the build with specific error messages.

Verification Scripts Reference

Script	Purpose	Location
test-routing.ps1 / test-routing.sh	Execute 173-case benchmark suite	skills/scripts/
verify-routing-coherence.ps1	Validate JSON/MD alignment and route count consistency	skills/scripts/

These scripts emit actionable diagnostics: "benchmark ghost expects" indicates a missing route implementation; "routing.json route count suspicious" signals documentation drift.

Summary

• Benchmark first: Add failing test cases to routing-benchmark.json before implementation
• Single source of truth: All route logic lives in skills/config/routing.json
• Triple sync required: Match changes across JSON, benchmark, and MASTER-ROUTING.md
• Local verification: Run test-routing.ps1 or test-routing.sh to catch regressions before CI
• Clear diagnostics: Error messages directly identify the inconsistency type

Frequently Asked Questions

What happens if I forget to update the priority array?

The router may select the wrong skill for ambiguous hints. The verify-routing-coherence.ps1 script will not catch this specifically, but the benchmark in test-routing.ps1 will fail when hints resolve to unexpected routes. Always verify your new case passes locally before pushing.

Can I add multiple routing rules in one commit?

Yes, provided each rule has a corresponding benchmark case and MASTER-ROUTING.md entry. The coherence script validates total route counts, so bulk updates are safe when all three files change atomically.

Why does the benchmark use 173 fixed test cases?

This number represents the current regression coverage for all supported hint-to-route mappings in zhaoxuya520/reverse-skill. Adding a rule increments the count; the CI enforces that all historical cases continue passing, preventing silent behavioral changes to existing routing logic.

What format should skill paths use in the skill field?

Use relative paths from the repository root: skills/{skill-name}/SKILL.md. The platform routers resolve these paths against the runtime working directory when loading skill documentation.

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