# Where Are the Routing Rules Defined in reverse-skill? The Complete Guide

> Discover where routing rules are defined in reverse-skill. Learn about the single source of truth for route definitions and keyword matching at skills/config/routing.json.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-21

---

**The routing rules in reverse-skill are defined exclusively in [`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 all route definitions, keyword matching patterns, and priority ordering across the entire project.**

The reverse-skill project implements a sophisticated query routing system that directs user requests to specialized reverse-engineering skills. All routing logic—spanning 41 distinct routes (R1 through R41), keyword matching criteria, and priority ordering—lives in a single JSON configuration file. Understanding this architecture is essential for modifying routing behavior or debugging route selection issues.

## Central Routing Configuration File

### Location and Purpose

The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file is the exclusive location where routing rules are defined in reverse-skill. This file contains every route definition, scoring rule, and metadata field required by the routing engine. Any modification to routing behavior—whether adding new routes, updating keyword patterns, or changing priority order—requires editing this specific file.

### JSON Schema Structure

The configuration file implements a hierarchical schema with three primary components:

1. **Metadata** – Contains the description, fallback route identifier (`fallbackId`), scoring rules, and maintainer information.

2. **`routes` object** – Maps route IDs (R1, R2, through R41) to route definitions containing:
   - `label`: Human-readable route name
   - `skill`: Path to the implementing skill markdown file (e.g., [`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/apk-reverse/SKILL.md))
   - `keywords`: Array of regex patterns including `must`, `exclude`, and `mustAll` conditions

3. **`priority` array** – Defines evaluation order; routes are checked sequentially against this list, with the first matching high-score route becoming the **PRIMARY** route.

## How Scripts Consume the Routing Rules

All routing scripts read from the same JSON source. Here is how different components load and parse the configuration:

**PowerShell Implementation**

The `master-route.ps1` script loads the configuration using standard PowerShell cmdlets:

```powershell

# master-route.ps1 snippet

$RoutingPath = Join-Path $PSScriptRoot '..\config\routing.json'
$Routing = Get-Content $RoutingPath -Raw | ConvertFrom-Json

# $Routing.routes now holds all route definitions

```

**Bash Implementation**

The [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) script processes the file using `jq` for JSON parsing:

```bash

# master-route.sh snippet

routing_file="skills/config/routing.json"
routing_json=$(cat "$routing_file")

# Use jq to extract routes and priorities

routes=$(echo "$routing_json" | jq -r '.routes')
priority=$(echo "$routing_json" | jq -r '.priority')

```

**Python Implementation**

For custom tooling or validation scripts, Python can directly implement the matching logic:

```python
import json, pathlib, re

with open('skills/config/routing.json') as f:
    data = json.load(f)

def match_route(query):
    for route_id in data['priority']:
        route = data['routes'][route_id]
        for kw in route['keywords']:
            if re.search(kw['must'], query, re.I):
                if 'exclude' in kw and re.search(kw['exclude'], query, re.I):
                    continue
                return route['skill']   # e.g. "apk-reverse/SKILL.md"

    return data['routes'][data['fallbackId']]['skill']

```

## Route Matching and Priority Logic

The routing engine evaluates queries against the `priority` array sequentially. For each route in the priority list, the engine checks if the query matches all required keyword patterns.

**Keyword Matching Criteria**

Each route defines a `keywords` array containing regex patterns:

- **`must`**: Required pattern that must match the query
- **`exclude`**: Pattern that disqualifies the route if matched
- **`mustAll`**: All patterns in this set must match (when specified)

When multiple routes match a query, the **priority array** determines selection order. The first route in this ordered list that achieves a qualifying match score becomes the active route. If no routes match, the system falls back to the route specified by `fallbackId` in the metadata section.

## Key Files in the Routing Ecosystem

While [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) contains the definitions, several scripts interact with this file:

- **`skills/scripts/master-route.ps1`**: PowerShell entry point that reads the JSON and executes route selection logic
- **[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)**: Bash equivalent for Linux, macOS, and Kali environments
- **`skills/scripts/verify-routing-coherence.ps1`**: Validation script ensuring JSON integrity against documentation
- **[`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh)** and **`test-routing.ps1`**: Test suites exercising routing logic against the JSON definitions

Because these scripts reference the JSON file dynamically, any changes to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) take effect immediately without requiring code modifications to the routing engine itself.

## Summary

- **Single Source of Truth**: All routing rules are defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
- **41 Routes**: The system manages routes R1 through R41 with unique identifiers
- **Three Core Sections**: Metadata, `routes` object, and `priority` array
- **Regex-Based Matching**: Keywords use `must`, `exclude`, and `mustAll` patterns for flexible query parsing
- **Priority-Ordered Evaluation**: The `priority` array determines precedence when multiple routes match
- **Zero-Code Updates**: Modifying the JSON file automatically updates routing behavior across all PowerShell and Bash scripts

## Frequently Asked Questions

### Can I modify routing rules without editing the script code?

Yes. Because [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) is the single source of truth, you can add new routes, update keyword patterns, or change priority order by editing only this file. The `master-route.ps1`, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh), and verification scripts read the configuration dynamically, so changes apply immediately without code deployment.

### What happens if multiple routes match a user query?

The routing engine consults the `priority` array, which defines the exact evaluation order. The first route in this ordered list that matches the query's keywords becomes the **PRIMARY** route. This deterministic approach ensures consistent routing even when queries could technically match multiple skill definitions.

### How are keywords evaluated in the routing rules?

Each route contains a `keywords` array with regex patterns. The engine checks the `must` pattern first; if matched, it verifies the `exclude` pattern does not match. Some routes specify `mustAll` requiring multiple patterns to match simultaneously. Keywords are evaluated case-insensitively against the user query string.

### Where is the fallback route configured?

The fallback route is defined in the **Metadata** section of [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) under the `fallbackId` key. This route handles queries that fail to match any defined route patterns, ensuring the system always returns a valid skill path even for unrecognized inputs.