# Where Is the Single Source of Truth for Reverse-Skill's Routing Configuration?

> Discover the single source of truth for reverse-skill's routing configuration. Learn where to find the routing.json file that maps tasks to skill markdown files.

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

---

**The single source of truth for reverse-skill's routing configuration is the [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file, which every master-route script, verification tool, and test harness reads to determine how incoming tasks map to specific skill markdown files.**

The reverse-skill framework uses a centralized JSON-based routing system to dispatch tasks to the appropriate skill documentation. Rather than scattering routing logic across multiple scripts, the architecture consolidates all route definitions—including keyword matching rules, priority ordering, and fallback behavior—into a single file that acts as the authoritative configuration. Every component in the `zhaoxuya520/reverse-skill` repository, from PowerShell entry points to Bash wrappers, references this file to maintain consistency across the entire system.

## The Central Routing Configuration File

The file [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) serves as the definitive routing table for the entire framework. This JSON structure contains a top-level `routes` object where each route identifier (such as `R1`, `R2`, through `R0`) maps to a specific skill definition.

Each route entry specifies:

- **Label**: A human-readable description of the route
- **Skill**: The path to the markdown file containing the skill documentation
- **Keywords**: An array of matching rules with `must` patterns (required matches) and optional `exclude` patterns (disqualifiers)

The `priority` array within the JSON determines which route takes precedence when multiple keyword rules match a single task. Additionally, the `fallbackId` field specifies which route to use when no patterns match, ensuring the system always returns a valid skill file.

## How Entry Point Scripts Load the Configuration

Both PowerShell and Bash master-route scripts reference the same JSON file using relative path resolution from their script locations. This design ensures the routing configuration loads correctly regardless of the current working directory.

### PowerShell Implementation

In `skills/scripts/master-route.ps1`, the routing table is loaded using:

```powershell
$routingPath = Join-Path $PSScriptRoot '..\skills\config\routing.json'
$routing = Get-Content $routingPath -Raw | ConvertFrom-Json

```

### Bash Implementation

Similarly, [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) resolves the path dynamically:

```bash
routing_path="$(dirname "$0")/../skills/config/routing.json"
routing=$(cat "$routing_path")

# jq can be used to parse the JSON

```

## Routing Logic and Conflict Resolution

When processing a task, the framework evaluates the `routes` object against the input text. The matching algorithm checks each route's keywords for required patterns while respecting exclusion rules.

Here is a reference implementation showing how the routing decision works:

```python
import json, re
with open('skills/config/routing.json') as f:
    cfg = json.load(f)

def route(task):
    candidates = []
    for rid, data in cfg['routes'].items():
        for kw in data['keywords']:
            if re.search(kw['must'], task, re.I):
                if 'exclude' not in kw or not re.search(kw['exclude'], task, re.I):
                    candidates.append((rid, data))
                    break
    # apply priority ordering

    for pid in cfg['priority']:
        for cid, info in candidates:
            if cid == pid:
                return info['skill']
    return cfg['routes'][cfg['fallbackId']]['skill']

```

The priority system resolves conflicts by iterating through the `priority` array and returning the skill associated with the first matching route ID. If no routes match, the system falls back to the route specified by `fallbackId`.

## Validation and Generation Tools

Several utility scripts depend exclusively on [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to maintain system integrity:

- **`skills/scripts/verify-routing-coherence.ps1`**: Validates that markdown documentation and script implementations remain synchronized with the JSON routing rules
- **`skills/scripts/test-routing.ps1`** and **[`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh)**: Execute test cases against the routing configuration to verify correct task-to-skill mapping
- **`skills/scripts/extract-summaries.ps1`**: Generates markdown routing tables by parsing the JSON structure, ensuring documentation always reflects the current routing state

## Summary

- The **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** file is the single source of truth for all routing decisions in the reverse-skill framework.
- Every script—including `master-route.ps1`, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh), and `verify-routing-coherence.ps1`—reads routing data directly from this file.
- The JSON structure defines routes with keyword matching rules, a `priority` array for conflict resolution, and a `fallbackId` for default handling.
- Updates to routing logic should be made **only** in this configuration file; surrounding scripts validate or generate artifacts based on its contents.

## Frequently Asked Questions

### What happens if I edit the routing JSON incorrectly?

If [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) contains syntax errors or invalid route definitions, the verification script `verify-routing-coherence.ps1` will fail during execution. The test harnesses (`test-routing.ps1` and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh)) will also catch logical errors by attempting to route sample tasks and comparing results against expected skill files. Always run these validation tools after modifying the configuration.

### Can I add new routes without restarting services?

Yes. Because `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) read [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) at execution time rather than caching it, new routes take effect immediately on the next task invocation. No daemon restart or service reload is required since the framework operates as discrete script executions rather than a persistent service.

### How does the priority array resolve routing conflicts?

When a task matches keywords from multiple routes, the framework consults the `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). It returns the skill associated with the route ID that appears earliest in this array. For example, if both `R1` and `R3` match a task, but the priority array lists `["R1", "R2", "R3"]`, the system selects `R1`'s skill.

### Where should I place new skill markdown files when adding routes?

New skill files should be referenced relative to the repository root within the `skill` field of your route entry in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). The `extract-summaries.ps1` script will automatically locate these files when generating documentation tables, provided the paths correctly resolve from the repository root directory.