How to Add New Keyword Rules to routing.json Without Breaking Tests

To safely add new keyword rules to routing.json in the zhaoxuya520/reverse-skill repository, you must synchronize four elements: the route entry, the matching skill markdown file, the priority array, and passing verification tests.

The routing.json file serves as the single source of truth for all routing logic in the reverse-skill system. Three PowerShell scripts—master-route.ps1, verify-routing-coherence.ps1, and test-routing.ps1—read this file directly at runtime. A comprehensive verification suite validates internal consistency, making strict adherence to the update protocol essential.

Understanding the routing.json Structure

The skills/config/routing.json file contains two top-level objects:

• routes — a dictionary mapping route IDs to route definitions
• priority — an ordered array of route IDs determining match precedence

Each route requires three mandatory fields:

Field	Description
label	Human-readable description of the route
skill	Relative path to the skill markdown file
keywords	Array of keyword objects with filtering rules

Keyword objects must include a must regular expression. Optional fields include exclude (negative match), mustAll (all patterns required), and note (documentation).

Step-by-Step: Adding a New Keyword Rule

Follow this checklist in exact order to maintain test compliance.

Step 1: Select an Unused Route Identifier

Choose a route ID not present in the existing "routes" object. For example, if R40 exists, use R41.

Step 2: Create the Route Entry

Add a new object under "routes" with complete field definitions.

{
  "R41": {
    "label": "Network packet capture",
    "skill": "pcap-analysis/SKILL.md",
    "keywords": [
      {
        "must": "pcap|wireshark|tcpdump|packet.?capture|流量.?抓取",
        "note": "Matches raw network capture analysis requests"
      }
    ]
  }
}

Step 3: Create the Corresponding Skill File

Ensure the skill path points to an existing, tracked file. Create pcap-analysis/SKILL.md with appropriate content, or reference an existing markdown file.

Step 4: Update the Priority Array

Insert the new route ID into "priority" at the desired precedence position. Higher-priority routes appear earlier in the array.

"priority": [
  "R4", "R1", "R2", "R3", "R30", "R41", "R31", "R33", "R5"
]

In this example, R41 matches before R31 but after R30.

Step 5: Run Verification Scripts

Execute the coherence validator:

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

Then run the quick regression suite:

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

What the Tests Validate

The verify-routing-coherence.ps1 script enforces four invariants according to the source code:

1. Route count minimum — at least 30 routes must be defined
2. Field completeness — every route has label, skill, and keywords
3. Skill file existence — each skill path resolves to a tracked repository file
4. Priority alignment — the priority list contains exactly the same set of route IDs as the routes object (1-to-1 correspondence)

Failure on any check causes the router to fall back to the generic R0 route, breaking expected routing behavior.

Common Failure Modes and Fixes

Symptom	Cause	Resolution
"Priority mismatch" error	Route ID exists in routes but not priority, or vice versa	Ensure 1-to-1 correspondence between both structures
"Missing skill file" error	skill path points to non-existent or untracked file	Create the markdown file or correct the path
Route never matches	Priority position too low	Move the route ID earlier in the priority array
False positive matches	must regex too broad	Add exclude patterns or refine the regex

Key Files in the Routing System

• skills/config/routing.json — central routing definition read by all scripts
• skills/scripts/verify-routing-coherence.ps1 — structural and logical validation
• skills/scripts/test-routing.ps1 — regression testing with -Quick flag for fast feedback
• skills/scripts/master-route.ps1 — runtime router that executes the matching logic

Summary

• Four elements must stay synchronized: route entry, skill file, priority position, and test passage
• Always run both verification scripts before committing changes
• Priority order determines match precedence—place higher-specificity rules first
• The must regex is mandatory in every keyword object; use exclude to prevent false positives
• Missing any step triggers fallback to R0, breaking expected routing behavior

Frequently Asked Questions

What happens if I forget to update the priority array?

The verify-routing-coherence.ps1 script detects the mismatch and reports a priority alignment error. The router will disregard the orphan route and may fall back to R0 when processing queries that should match the new rule.

Can I reuse an existing skill markdown file for a new route?

Yes. Multiple routes can reference the same skill path. This is useful when different keyword patterns should trigger identical behavior. The priority array still requires each route ID to be unique.

How do I test my new route without running the full suite?

Use the -Quick flag with test-routing.ps1: powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1 -Quick. This runs essential validation without exhaustive regression scenarios.

What regex features are supported in the must field?

Standard PowerShell/.NET regular expressions are supported, including alternation (|), quantifiers (?, *, +), character classes, and Unicode-aware patterns. The ? quantifier pairs well with optional spacing patterns like packet.?capture to match both "packet capture" and "packetcapture".

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