# Where Is the Primary Routing Configuration Stored in reverse-skill? A Complete Guide to Task Routing

> Find the primary routing configuration in reverse-skill at skills/config/routing.json. This guide reveals the single source of truth for all task routing rules.

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

---

**The primary routing configuration in reverse-skill is stored 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 task-routing rules across the entire system.**

The `reverse-skill` repository by `zhaoxuya520` centralizes its routing logic in one JSON file that powers both Windows and Unix-based execution paths. Understanding where this **primary routing configuration** lives and how it's structured is essential for anyone modifying routing behavior or debugging task dispatch issues.

## Location and Structure of the Routing Configuration

The definitive routing configuration resides at:

```

skills/config/routing.json

```

This file contains a complete routing matrix with four top-level keys:

- **`schemaVersion`** — Tracks the version of the routing schema for forward compatibility
- **`meta`** — Includes description, fallback route (`R0`), scoring strategy, and maintainer information
- **`routes`** — A mapping of route identifiers (`R1`, `R2`, …) to route definitions containing:
  - **label**: Human-readable description
  - **skill**: Path to the target skill markdown file
  - **keywords**: Array of regular-expression rules that trigger route matching
- **`priority`** — Ordered list used by the router to resolve ties when multiple routes match

## How Routing Scripts Consume the Configuration

All task-routing entry points in the repository read directly from this JSON file. Modifying [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) automatically propagates to every dependent system.

### Windows: master-route.ps1

The PowerShell entry point at `skills/scripts/master-route.ps1` loads and processes the routing configuration:

```powershell

# Load the routing configuration

$routerPath = "$PSScriptRoot/../config/routing.json"
$router = Get-Content $routerPath -Raw | ConvertFrom-Json

# Find the route that matches a user hint (example: "apk reverse")

$hint = "apk reverse"
$matched = $router.routes.GetEnumerator() | Where-Object {
    $_.Value.keywords -match $hint
}
if ($matched) {
    Write-Host "Selected route:" $matched.Name
    Write-Host "Skill file:" $matched.Value.skill
}

```

### Linux/macOS: master-route.sh

The Bash equivalent at [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) performs identical logic using `jq`:

```bash
#!/usr/bin/env bash
router_file="skills/config/routing.json"
hint="apk reverse"

# Use jq to search the JSON

route=$(jq -r --arg h "$hint" '
  .routes | to_entries[]
  | select( .value.keywords[]?.must | test($h; "i") )
  | .key' "$router_file" | head -n1)

if [[ -n $route ]]; then
  skill=$(jq -r ".routes[\"$route\"].skill" "$router_file")
  echo "Route: $route → $skill"
fi

```

## Validation and Testing Against the Primary Configuration

The repository includes dedicated scripts that verify the integrity of [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and ensure derived artifacts remain synchronized.

### Coherence Verification

`skills/scripts/verify-routing-coherence.ps1` validates that the priority list in the JSON matches the priority table in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md). This prevents documentation drift:

```powershell

# Verify that all route IDs in 'priority' exist in 'routes'

$missing = $router.priority | Where-Object { -not $router.routes.ContainsKey($_) }
if ($missing) { Write-Error "Missing routes: $missing" }
else { Write-Host "Priority list is consistent." }

```

### Functional Testing

Both `test-routing.ps1` and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) in `skills/scripts/` use the same JSON configuration to validate that routing behaves as expected across different input hints.

## Why This Centralization Matters

The **primary routing configuration** in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) follows a single-source-of-truth design pattern with concrete benefits:

1. **Consistency changes** — One file modification updates all routing behavior
2. **Cross-platform parity** — Windows and Unix scripts reference identical rules
3. **Documentation sync** — Derivative files like [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) regenerate automatically
4. **Test coverage** — All validation logic points to one verifiable location

Any modification to routing rules **must be made only in this file**. The generated documentation, verification scripts, and platform-specific entry points remain synchronized without manual intervention.

## Related Files in the Routing System

| File | Purpose |
|------|---------|
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central routing definition (primary configuration) |
| `skills/scripts/master-route.ps1` | Windows entry point that loads the routing JSON |
| [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) | Linux/macOS entry point with identical logic |
| `skills/scripts/verify-routing-coherence.ps1` | Validates JSON priority against markdown documentation |
| `skills/scripts/test-routing.ps1` / [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) | Test harnesses validating routing behavior |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable summary (generated from the JSON) |

## Summary

- The **primary routing configuration** in `reverse-skill` is [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
- This JSON file contains the complete routing matrix including schema version, metadata, route definitions with regex keywords, and priority ordering
- All platform-specific scripts (`master-route.ps1`, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)) read this file directly for task dispatch
- Validation scripts ensure the configuration remains internally consistent and synchronized with documentation
- Changes should only be made to this central file; derived artifacts update automatically

## Frequently Asked Questions

### What happens if I edit MASTER-ROUTING.md instead of routing.json?

Direct edits to [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) will be overwritten. This file is generated from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). As implemented in `verify-routing-coherence.ps1`, the system detects when the markdown priority table diverges from the JSON priority list. Always modify the JSON source to make persistent routing changes.

### Does reverse-skill support multiple routing configurations?

No. The codebase is designed around a single **primary routing configuration** at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Both `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) hardcode this path relative to their script location. There is no environment variable or parameter to specify an alternative routing file.

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

When multiple routes match a user hint, the `priority` array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) determines precedence. The router iterates through this ordered list and selects the first matching route. This design allows explicit control over tie-breaking without complex scoring logic. Verify your intended priority with `test-routing.ps1` or [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh).

### Can I add custom fields to the routing.json schema?

Additional fields in `routes` object values will not break existing scripts, since `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) access specific known properties (`label`, `skill`, `keywords`). However, `schemaVersion` should be incremented if you introduce structural changes that validation scripts need to recognize.