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

The primary routing configuration in reverse-skill is stored in 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 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:

# 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 performs identical logic using jq:

#!/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 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. This prevents documentation drift:

# 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 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 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 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	Central routing definition (primary configuration)
skills/scripts/master-route.ps1	Windows entry point that loads the routing JSON
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	Test harnesses validating routing behavior
skills/MASTER-ROUTING.md	Human-readable summary (generated from the JSON)

Summary

• The primary routing configuration in reverse-skill is 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) 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 will be overwritten. This file is generated from 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. Both master-route.ps1 and 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 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.

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 access specific known properties (label, skill, keywords). However, schemaVersion should be incremented if you introduce structural changes that validation scripts need to recognize.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}