How to Add a Custom Routing Rule to `routing.json` Without Breaking the Test Suite

The safest way to extend routing.json is to use a unique route ID, run the verify-routing-coherence script to catch schema and priority mismatches, then execute the full test-routing suite to verify no regressions occur.

The zhaoxuya520/reverse-skill repository uses skills/config/routing.json as the single source of truth for all task-routing logic. This file drives every routing-related component—from PowerShell and Bash scripts to the automatic summary generator—so modifications must maintain strict consistency with the existing test infrastructure.

Understand the Routing Architecture

Before adding any rule, understand how the system validates changes. Three core components enforce correctness:

• verify-routing-coherence.ps1 — Validates JSON schema, checks that every route ID appears exactly once in the priority list, and regenerates markdown tables
• test-routing.sh / test-routing.ps1 — Runs keyword-matching test cases against every route to detect regressions
• master-route.ps1 / master-route.sh — The runtime entry points that read routing.json to dispatch tasks

Any mismatch between these components causes immediate test failures, so the validation scripts act as a safety net.

Choose a Unique Route ID

Route IDs follow the pattern Rxx where xx is a two-digit number. Before selecting an ID:

1. Open skills/config/routing.json
2. Examine the "routes" object for existing IDs
3. Pick an unused number (e.g., R42 if unassigned)

Duplicate IDs cause the coherence checker to fail with a JSON parsing error.

Define the New Route Entry

Insert your new route anywhere inside the "routes" object—order within this object does not affect functionality. A minimal valid definition:

"R42": {
  "label": "My Custom Skill",
  "skill": "my-custom-skill/SKILL.md",
  "keywords": [
    { "must": "mycustom|specialword|anotherterm", "note": "Optional human-readable hint" }
  ]
}

Field requirements:

• label — Short human-readable name displayed in generated tables
• skill — Relative path to the skill's markdown implementation
• keywords — Array of matching objects; minimum one "must" regex per object

Advanced keyword options include "exclude" (negative match), "mustAll" (all patterns required), and "note" (documentation).

Update the Priority List

The "priority" array at the bottom of routing.json determines evaluation order. Insert your new ID at the desired position:

"priority": [
  "R4", "R1", "R2", "R3", "R30", "R31", "R5", "R9", "R21",
  "R22", "R6", "R7", "R8", "R34", "R28", "R17", "R16", "R18", "R24",
  "R37", "R23", "R42",
  "R35", "R25", "R36", "R29", "R38", "R32", "R26", "R27",
  "R10", "R11", "R12", "R13", "R14", "R15", "R19", "R40", "R20",
  "R39", "R41", "R0"
]

Omitting the ID from "priority" causes verify-routing-coherence.ps1 to fail, as the test enforces that every defined route has exactly one priority entry.

Run the Coherence Verification Script

Execute the appropriate script for your platform to catch structural errors before running the full test suite:

# Linux / macOS

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

# Windows PowerShell

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

This validates:

• JSON well-formedness against the schema version
• One-to-one correspondence between "routes" keys and "priority" entries
• Synchronization of generated markdown tables with MASTER-ROUTING.md

Success output: Routing coherence check passed with exit code 0.

Execute the Full Routing Test Suite

Run the comprehensive keyword-matching tests to verify no regressions:

# Linux / macOS

bash skills/scripts/test-routing.sh

# Windows PowerShell

.\skills\scripts\test-routing.ps1

The suite verifies:

• Existing routes continue matching their intended intents
• No overlapping regexes now route queries to the wrong skill
• The fallback route R0 triggers when no rule matches

Failed tests display the route ID and offending input string, enabling precise regex adjustments.

Complete Example: Adding a Docker Escape Rule

{
  "R42": {
    "label": "Docker Escape",
    "skill": "container-escape/SKILL.md",
    "keywords": [
      {
        "must": "docker\\s+escape|container\\s+breakout|cgroup\\s+exploit",
        "note": "Detects queries about breaking out of Docker containers"
      }
    ]
  }
}

Insert R42 into the priority list after related container rules (e.g., after R23), then run both verification scripts.

Key Files for Reference

File	Purpose
skills/config/routing.json	Central routing configuration—only file to edit
skills/scripts/verify-routing-coherence.ps1	Schema, priority, and table synchronization checker
skills/scripts/test-routing.sh / test-routing.ps1	Full regression test harness
skills/MASTER-ROUTING.md	Auto-generated human-readable routing matrix
skills/scripts/master-route.ps1 / master-route.sh	Runtime dispatch scripts consuming routing.json

Summary

• Use unique Rxx IDs to avoid JSON collisions
• Run verify-routing-coherence first to catch structural errors
• Update the priority array or the coherence check fails
• Execute test-routing to confirm no keyword-matching regressions
• Commit only after both scripts pass with exit code 0

Frequently Asked Questions

What happens if I forget to add my route ID to the priority list?

The verify-routing-coherence script fails with an error indicating the priority list is missing a route. The test enforces a strict one-to-one mapping between defined routes and priority entries, so you must include every Rxx ID exactly once.

Can I reuse an existing route ID for a similar skill?

No. Duplicate IDs cause JSON parsing errors in all routing scripts. The coherence checker detects this immediately. Always select an unused two-digit number when adding custom routing rules.

Do I need to manually update MASTER-ROUTING.md after editing routing.json?

No. The verify-routing-coherence script automatically regenerates markdown tables. Manual edits to MASTER-ROUTING.md are overwritten and will trigger test failures if they diverge from the generated output.

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