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

> Learn the recommended workflow for adding new routing rules to routing.json in the reverse-skill repository. Create tests, update config, sync docs, and verify with scripts.

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

---

**To add new routing rules to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) are tested, documented, and synchronized across all platform-native routers (`master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

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

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

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

```

On Linux or macOS:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and validates every entry in [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json).

On Windows:

```powershell
.\skills\scripts\test-routing.ps1

```

On Linux or macOS:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md), [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json), and [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) summaries, ensuring the new routing entry appears in the top-level documentation.

On Windows:

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

```

On Linux or macOS:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
- [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json)
- [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json)**: The deterministic test suite that protects against routing regressions.
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)**: An advisory documentation file providing alternative disambiguation views.

## Summary

- **Always** add a regression case to [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) before modifying [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to maintain test coverage.
- **[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh), [`verify-routing-coherence.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify-routing-coherence.sh), and [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) on Linux, macOS, or Kali systems to perform identical validation and generation tasks.