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

> Safely add custom routing rules to routing.json. Use unique IDs, verify coherence, and run tests to prevent regressions. Extend routing without breaking your project.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-19

---

**The safest way to extend [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) / `test-routing.ps1`** — Runs keyword-matching test cases against every route to detect regressions
- **`master-route.ps1` / [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)** — The runtime entry points that read [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```json
"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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) determines evaluation order. Insert your new ID at the desired position:

```json
"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:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash

# 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

```json
{
  "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh) / `test-routing.ps1` | Full regression test harness |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Auto-generated human-readable routing matrix |
| `skills/scripts/master-route.ps1` / [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) | Runtime dispatch scripts consuming [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) after editing [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)?

No. The `verify-routing-coherence` script automatically regenerates markdown tables. Manual edits to [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) are overwritten and will trigger test failures if they diverge from the generated output.