What Is the Role of `skills/config/routing.json` in the reverse-skill Repository?

skills/config/routing.json serves as the single source of truth for all routing rules in the reverse-skill project, driving the primary decision-making process that determines which skill module handles a given task.

The reverse-skill repository orchestrates specialized security and reverse engineering workflows through modular skill components. At the heart of this architecture lies skills/config/routing.json, a centralized configuration file that eliminates hard-coded routing logic and ensures consistent task-to-skill mapping across both Windows and Unix-based execution environments.

Centralized Routing Authority

Unlike monolithic applications that embed routing tables directly within executable code, reverse-skill externalizes all route definitions into this JSON configuration. This separation of concerns allows the platform to map task hints to skill modules dynamically without modifying the underlying router implementations.

Primary Routing Engine

Both the Windows PowerShell router (skills/scripts/master-route.ps1) and the Linux/macOS Bash router (skills/scripts/master-route.sh) depend exclusively on this JSON file to select the PRIMARY skill based on task hints. The scripts contain no hard-coded routing tables; instead, they defer all matching logic to the configuration defined in skills/config/routing.json.

When you invoke the router with a task hint, the script internally loads the JSON file, matches the hint against defined keywords, and launches the corresponding skill module:

# Run the router with a task hint; the script reads routing.json internally

.\skills\scripts\master-route.ps1 -Hint "android reverse engineering"

This design ensures that routing behavior remains consistent across operating systems while requiring updates to only one authoritative file.

Truth Source for Documentation

The JSON file functions as the definitive reference for all routing-related documentation. The MASTER-ROUTING.md priority table, the advisory routing.md appendix, and the benchmark file (routing-benchmark.json) must all align with the definitions in skills/config/routing.json.

Any change to routing logic originates in this JSON file alone. After modification, related documentation undergoes regeneration or manual synchronization to maintain parity. This workflow prevents documentation drift and guarantees that human-readable guides reflect the actual runtime behavior.

Integrity and Validation

To maintain system reliability, the repository implements automated verification that validates the JSON structure against strict integrity rules.

Coherence Verification

The skills/scripts/verify-routing-coherence.ps1 script parses skills/config/routing.json to enforce several critical constraints:

• Every route must contain required fields: label, skill, and keywords
• All referenced skill files must exist in the expected locations
• The priority array must provide 1-to-1 coverage of every defined route
• The priority order must match the sequence documented in MASTER-ROUTING.md

Run the verification script to validate your configuration:

.\skills\scripts\verify-routing-coherence.ps1

This validation acts as a gatekeeper, ensuring that malformed entries or missing references cannot propagate into production workflows.

Contribution Guardrails

The project enforces strict governance around routing modifications to prevent fragmentation. According to skills/CONTRIBUTING.md, contributors must perform all routing changes by editing only skills/config/routing.json—specifically the routes and priority sections.

The continuous integration pipeline will fail builds if any other file diverges from the JSON source of truth. This policy mandates that the JSON configuration remains the focal point for all routing-related updates, eliminating the risk of scripts and documentation falling out of sync with the actual routing logic.

Adding and Modifying Routes

When extending the platform with new capabilities, you modify the JSON structure directly. Each route entry requires a unique identifier containing the skill metadata and matching keywords:

{
  "routes": {
    "R45": {
      "label": "New Threat Intel",
      "skill": "threat-intel",
      "keywords": ["intel", "threat", "OSINT"]
    }
  },
  "priority": ["R0","R1","...","R45"]
}

After editing the file, execute either master-route.ps1 or verify-routing-coherence.ps1 to confirm the new route is recognized and properly integrated into the priority sequence.

Summary

• skills/config/routing.json functions as the authoritative configuration mapping task hints to skill modules in the reverse-skill repository.
• Both Windows (master-route.ps1) and Unix (master-route.sh) routers read this file exclusively to determine the PRIMARY skill for execution.
• The file serves as the foundation for documentation in MASTER-ROUTING.md, routing.md, and routing-benchmark.json.
• The verify-routing-coherence.ps1 script enforces structural integrity, verifying required fields, file existence, and priority alignment.
• Contribution guidelines require all routing changes to originate in this JSON file alone, with CI failing if other files diverge.

Frequently Asked Questions

What fields are required for each route in routing.json?

Every route entry must include three mandatory fields: label (human-readable description), skill (module identifier), and keywords (array of matching terms). The verify-routing-coherence.ps1 script validates that no routes lack these essential attributes.

Can I modify routing logic directly in master-route.ps1 instead?

No. The architecture explicitly forbids hard-coded routing tables in the scripts. Both master-route.ps1 and master-route.sh must defer to skills/config/routing.json for all routing decisions. Changes made directly to the router scripts will cause CI failures according to the contribution guidelines.

How does the verification script ensure documentation stays synchronized?

The verify-routing-coherence.ps1 script parses skills/config/routing.json and confirms that the priority array order matches the sequence defined in MASTER-ROUTING.md. This check ensures that human-readable documentation reflects the actual runtime routing priority enforced by the JSON configuration.

What happens if I add a route but forget to update the priority array?

The coherence verification will fail. The script checks that the priority array provides complete 1-to-1 coverage of all defined routes. Missing entries or orphaned routes trigger validation errors, preventing incomplete configurations from entering the codebase.

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