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

> Learn to configure routing rules in reverse-skill. Edit routing.json to define routes, set keywords, and manage priorities. Verify your setup with provided scripts for efficient skill routing.

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

---

**Configure routing rules in reverse-skill by editing [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to define route objects with unique IDs, keyword patterns (`must`, `exclude`, `mustAll`), and skill paths, then update the `priority` array to resolve ties, and validate changes using the `verify-routing-coherence` and `test-routing` scripts.**

The reverse-skill repository uses a centralized JSON-driven routing system to match user requests against specialized markdown skill modules. All routing logic is defined in a single configuration file that determines which skill handles each query based on regex keyword scoring and priority resolution. Understanding how to properly configure these routing rules is essential for extending the system or fine-tuning request handling.

## Understanding the Routing Architecture in reverse-skill

The routing system operates through [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), which serves as the single source of truth for request dispatching. This file contains a schema definition, a fallback route (`R0`) for unmatched requests, and a priority array that breaks ties when multiple routes achieve identical match scores.

### Core Components of routing.json

Each route entry (e.g., `R1`, `R2`) contains three required fields: `label` for human-readable identification, `skill` pointing to the relative path of the markdown implementation (e.g., [`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/apk-reverse/SKILL.md)), and `keywords`—an array of pattern objects. 

Keyword objects support four pattern types:

- **`must`** – A regular expression that must be present in the request for the rule to match
- **`exclude`** – A regular expression that must *not* be present for the rule to match
- **`mustAll`** – An array of additional regex patterns that all must match simultaneously
- **`note`** – Free-form comments used by maintainers to document pattern intent

### How the Routing Engine Evaluates Requests

The engine, implemented in `skills/scripts/master-route.ps1` and [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh), processes requests through a four-stage pipeline:

1. **Keyword matching** – The request text is scanned against every route's `must`, `exclude`, and `mustAll` patterns
2. **Scoring** – A route gains one point for each keyword rule that successfully matches
3. **Priority resolution** – The route with the highest score wins; if scores tie, the engine selects whichever route appears first in the `priority` array
4. **Fallback** – If no route matches, the system defaults to route `R0` (general reverse-engineering)

## How to Add a New Route in reverse-skill

Adding a routing rule requires modifying both the `routes` object and the `priority` array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json).

1. **Create a unique route ID** inside the `"routes"` block using a fresh `Rxx` identifier that does not clash with existing keys (e.g., `R42`).

2. **Define the route object** with the required schema:

```json
"R42": {
  "label": "Terraform security",
  "skill": "terraform-security/SKILL.md",
  "keywords": [
    { 
      "must": "terraform|tf|infrastructure.?as.?code|iac", 
      "note": "Detect IaC security queries" 
    }
  ]
}

```

3. **Insert the new route ID** into the `"priority"` array at the appropriate position. Routes earlier in the array win ties, so place the ID where you want it to rank relative to existing routes:

```json
"priority": [
  "R4", "R1", "R41", "R42", "R0"
]

```

4. **Run the verification script** to ensure consistency:

```powershell
powershell -File skills/scripts/verify-routing-coherence.ps1

```

Or on Linux/macOS:

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

```

5. **Test the change** with the routing test suite:

```powershell
powershell -File skills/scripts/test-routing.ps1

```

## How to Modify Existing Routing Rules

### Refining Keyword Patterns with Exclude Rules

To prevent false positives, add `exclude` patterns to disambiguate overlapping routes. For example, to prevent the "APK reverse" route (`R1`) from matching LLM-related queries:

```json
{
  "must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b",
  "exclude": "llm|prompt|jailbreak",
  "note": "Prevent LLM-related queries from matching R1"
}

```

### Adjusting Route Priority

To change which route wins when multiple routes match with equal scores, reorder the IDs in the `"priority"` array. Move more specific routes earlier in the list to ensure they take precedence over general-purpose routes.

## Common Routing Configuration Mistakes

| Issue | Why it Happens | How to Avoid |
|-------|----------------|--------------|
| **Duplicate route IDs** | JSON keys must be unique within the `routes` object | Use a fresh `Rxx` number each time you add a route |
| **Mis-ordered priority** | The `priority` array does not contain the new route ID | Always edit the priority array immediately after adding or removing a route |
| **Over-broad `must` regex** | Causes unrelated requests to be routed incorrectly | Use word boundaries (`\b`) and specific terms; test with the routing scripts |
| **Missing `exclude` in conflicting keywords** | Two routes can both match the same request, leading to unexpected routing | Add `exclude` patterns to disambiguate or adjust the priority order |

## Testing and Validating Your Changes

After editing [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), validation is mandatory before the changes take effect. The `skills/scripts/verify-routing-coherence.ps1` (and its Bash counterpart [`verify-routing-coherence.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify-routing-coherence.sh)) checks that:

- Every route ID in `routes` appears exactly once in the `priority` array
- No duplicate IDs exist in either section
- The JSON structure adheres to the expected schema

Once verification passes, execute `skills/scripts/test-routing.ps1` or [`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh) to run the functional test suite. These scripts simulate requests against your new patterns to confirm they match intended queries and exclude unintended ones.

The markdown documentation in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) and the generated summary in [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) are automatically synchronized by the master scripts, so you only need to edit [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) directly.

## Summary

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** is the central configuration file for all routing rules in the reverse-skill repository
- Each route requires a unique ID (Rxx format), descriptive `label`, `skill` path to the markdown module, and `keywords` array
- Keywords use `must`, `exclude`, and `mustAll` regex patterns to determine matches; scores are tallied to select the best route
- The **`priority`** array determines the winner when multiple routes achieve identical match scores
- Always run **`verify-routing-coherence`** and **`test-routing`** scripts after modifications to ensure system integrity

## Frequently Asked Questions

### What is the format of the routing.json file in reverse-skill?

The file contains a JSON object with a `schema` section (version metadata), a `priority` array (ordered list of route IDs), and a `routes` object containing key-value pairs where keys are route IDs like `R1`, `R2`, and values are objects specifying `label`, `skill` (relative path to markdown), and `keywords` (array of pattern objects with `must`, `exclude`, `mustAll`, and `note` fields).

### How do I prevent false positives when configuring routing rules?

Use the **`exclude`** field in keyword objects to block unwanted matches, and employ word boundaries (`\b`) in your `must` regex patterns to ensure you match whole words rather than substrings. Always test patterns using `skills/scripts/test-routing.ps1` or [`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh) before finalizing changes.

### What happens if two routes have the same match score?

The routing engine consults the **`priority`** array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and selects whichever route appears first in that ordered list. Place more specific routes earlier in the array to ensure they win ties against general-purpose routes that might also match.

### Where are the routing validation scripts located?

The verification and test scripts reside in **`skills/scripts/`**, including `verify-routing-coherence.ps1` and [`verify-routing-coherence.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify-routing-coherence.sh) for checking JSON consistency, plus `test-routing.ps1` and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) for functional validation of pattern matching logic.