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

The single source of truth for reverse-skill's routing configuration is the 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 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:

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

Bash Implementation

Similarly, skills/scripts/master-route.sh resolves the path dynamically:

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:

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 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: 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 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, 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 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) 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 read 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. 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. The extract-summaries.ps1 script will automatically locate these files when generating documentation tables, provided the paths correctly resolve from the repository root directory.

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