# How to Configure Custom Routing Rules in reverse-skill: A Complete Guide

> Learn to configure custom routing rules in reverse-skill. This guide covers defining routes, registering IDs, creating tests, and validating coherence for seamless integration.

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

---

**To configure custom routing rules in reverse-skill, define a new route object in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), register the route ID in the `priority` array, create multilingual benchmark tests, and execute the verification scripts to validate routing coherence.**

The `reverse-skill` repository implements a deterministic routing engine that matches user hints against regex keyword patterns to dispatch the appropriate reverse-engineering skill. When you configure custom routing rules in reverse-skill, you extend the single source of truth located at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) while maintaining synchronization with automated test suites and documentation matrices.

## Understanding the Routing Architecture

The routing system operates through a scoring mechanism implemented in **`skills/scripts/master-route.ps1`** (Windows) and **[`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)** (Linux/macOS/Kali). These entry-point scripts load [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and execute the following logic:

1. **Keyword Matching** – Each route defines regex patterns in the `keywords` array. The router calculates scores by counting pattern matches against the user hint.
2. **Priority Resolution** – When multiple routes achieve identical scores, the `priority` array (located near line 324) determines the winner through deterministic ordering.
3. **Fallback Handling** – If no keywords match, the router defaults to the route specified by **`fallbackId`** (typically `R0` at lines 5–7).

Every route object requires a unique ID (e.g., `R40`), a human-readable `label`, a `skill` path pointing to the corresponding [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file, and a `keywords` array containing objects with `must` (regex pattern) and `note` (description) properties.

## Step-by-Step Guide to Adding Custom Routes

### Step 1: Define the Route Object in routing.json

Open **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** and add a unique entry to the `routes` object. Use a standardized ID format like `R40`:

```json
{
  "R40": {
    "label": "Web API reverse",
    "skill": "web-api-reverse/SKILL.md",
    "keywords": [
      {
        "must": "swagger|openapi|rest.?api|graphql|api.?reverse|web.?api|http.?service",
        "note": "Matches any hint mentioning API specifications or HTTP-service reverse engineering"
      }
    ]
  }
}

```

Insert this object within the existing `routes` map, maintaining consistent ordering with other route definitions.

### Step 2: Update the Priority Array

Locate the **`priority`** array near the end of [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) (around line 324). Append your new route ID to establish tie-breaking precedence:

```json
"priority": [
  "R1", "R2", "...", "R39", "R40"
]

```

Routes appearing earlier in this array take precedence when multiple candidates achieve identical match scores.

### Step 3: Create Multilingual Benchmark Tests

Update **[`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json)** with test cases in both English and Chinese to validate the new route:

```json
{
  "hint": "I need to reverse engineer a swagger API",
  "expected": "web-api-reverse/SKILL.md"
}

```

The CI test suite (`skills/scripts/test-routing.ps1` and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh)) executes these benchmarks to ensure the routing logic correctly identifies your skill across language contexts.

### Step 4: Verify Routing Coherence

Execute the verification script to confirm that [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) remains synchronized with **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)**:

```bash

# Windows

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

# Linux/macOS/Kali

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

```

Successful execution returns **ALL PASS**, indicating no drift exists between the JSON configuration and the human-readable documentation matrix.

### Step 5: Execute the Full Test Suite

Validate your changes against the complete routing test harness:

```bash

# Windows PowerShell

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

# Unix-based systems

bash skills/scripts/test-routing.sh

```

The output should indicate comprehensive success (e.g., `166/166 ALL PASS`). If tests fail, refine the `keywords` regex patterns or adjust the `priority` ordering.

## Key Files in the Routing Ecosystem

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – Central configuration containing all route definitions, keyword regex patterns, and the `priority` ordering array.
- **`skills/scripts/master-route.ps1`** – Windows entry point that executes the scoring and selection logic.
- **[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)** – Unix entry point supporting Linux, macOS, and Kali distributions.
- **[`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json)** – Test harness containing multilingual example hints and expected skill outcomes.
- **`skills/scripts/verify-routing-coherence.ps1`** – Cross-platform linting tool ensuring JSON and documentation alignment.
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)** – Human-readable reference matrix documenting route priorities and descriptions.

## Summary

To successfully configure custom routing rules in reverse-skill:

- **Define** new route objects in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with unique IDs, regex-based `keywords`, and `skill` paths.
- **Register** route IDs in the `priority` array to establish deterministic tie-breaking behavior.
- **Test** changes by adding English and Chinese entries to [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) and executing the test scripts.
- **Verify** coherence between configuration and documentation using `verify-routing-coherence.ps1`.
- **Maintain** consistency with [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) to ensure developer reference materials remain accurate.

## Frequently Asked Questions

### How does reverse-skill resolve routing conflicts when multiple routes match?

When multiple routes achieve identical match scores against a user hint, the router consults the **`priority`** array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to deterministically select the winner. Routes appearing earlier in the array take precedence over later entries, ensuring consistent skill selection even with ambiguous inputs.

### What regex syntax does reverse-skill support for keyword patterns?

The **`must`** field within keyword objects accepts standard regular expressions supported by PowerShell and Bash regex engines. This includes alternation (e.g., `swagger|openapi`), optional quantifiers (e.g., `rest.?api`), and character classes. The patterns are evaluated case-sensitively by the `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) scripts.

### Is it mandatory to update MASTER-ROUTING.md when adding custom routes?

While the JSON file serves as the single source of truth, you must run **`verify-routing-coherence.ps1`** to ensure [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) remains synchronized. This verification step is mandatory for CI/CD compliance, though the markdown file functions as human-readable documentation rather than operational code.

### What happens if I omit my route ID from the priority array?

Omission from the **`priority`** array does not prevent route matching, but it removes deterministic tie-breaking capability. When multiple routes achieve identical scores, the system cannot guarantee which skill executes, potentially causing unpredictable routing behavior. Always register new IDs in the priority array to ensure consistent, reproducible results.