RULES.md vs routing.json in the Reverse‑Skill Routing Workflow: Key Differences Explained

RULES.md defines the mandatory execution pipeline and safety guardrails that AI clients must follow, while routing.json provides the machine-readable keyword-to-skill mapping that determines which module handles a specific request.

The zhaoxuya520/reverse-skill repository implements a two-layered routing architecture that separates process control from data-driven decision making. Understanding how these files interact is essential for customizing the workflow or adding new reverse-engineering capabilities.

Architectural Separation: Policy vs. Routing Data

The repository deliberately splits workflow governance from route selection logic:

• RULES.md acts as the single source of truth for process control. Located at the repository root, this markdown file contains narrative instructions, security boundaries, self-audit checks, and the strict execution sequence that every AI client must observe. It mandates when to read supplementary files like MASTER-ROUTING.md and how to initialize the case scope before any action.

• routing.json serves as the data-driven routing table. Stored at skills/config/routing.json, this JSON file contains a map of route IDs to skill entry points, each defined by keyword regex patterns and file paths. The master-route.ps1 and verify-routing-coherence.ps1 scripts consume this file to match incoming tasks against predefined capabilities.

Inside RULES.md: The Workflow Orchestrator

According to the reverse-skill source code, RULES.md establishes the policy layer that prevents unsafe short-cuts or incorrect tool usage. It defines a mandatory execution chain that includes authorization validation, tool indexing via tool-index.md, case initialization through case-init.ps1, role mapping, and evidence workflow management.

Modification of this file is restricted to process updates—such as adding new self-audit steps or altering the initialization sequence. The document references operational markdown files including skills/ops/scope-contract.md to enforce that the environment is properly configured before any routing decision occurs. Scripts like case-init.ps1 materialize the requirements described here, ensuring the AI cannot proceed without satisfying the declared prerequisites.

Inside routing.json: The Skill Selection Engine

The routing.json file structures the keyword-based route selection mechanism that directs requests to appropriate skill modules. Each entry in the routes object specifies:

• label: Human-readable description of the route
• skill: Path to the corresponding SKILL.md file (e.g., apk-reverse/SKILL.md)
• keywords: Array of regex patterns used to match user queries
• priority: Ranking array that resolves conflicts when multiple routes match

When master-route.ps1 executes, it loads skills/config/routing.json and iterates through the routes to calculate match scores. If multiple routes satisfy the query, the script consults the priority list to select the deterministic "PRIMARY" route. This architecture ensures that routing behavior can be modified by editing only the JSON file, without touching the procedural logic encoded in PowerShell scripts.

Practical Implementation: How the Layers Interact

In practice, the AI client first consults RULES.md to establish the execution environment, then queries routing.json to select the specific skill module.

Example 1: Loading the routing table (master-route.ps1)

# Load routing definition

$routingPath = Join-Path $env:SKILL_ROOT 'skills/config/routing.json'
$routing = Get-Content $routingPath -Raw | ConvertFrom-Json

# Find matching routes for a given user query

$matches = @()
foreach ($id in $routing.routes.Keys) {
    foreach ($kw in $routing.routes[$id].keywords) {
        if ($query -match $kw.must) {
            $matches += [pscustomobject]@{
                Id       = $id
                Label    = $routing.routes[$id].label
                SkillMd  = $routing.routes[$id].skill
                Score    = 1
            }
        }
    }
}

# Resolve by priority

$primary = $routing.priority | Where-Object { $matches.Id -contains $_ } | Select-Object -First 1

Example 2: Enforcing RULES.md workflow steps

Before executing the selected skill, the system validates that RULES.md prerequisites are satisfied:

# RULES.md mandates case scope before ACT

$scopeFile = Join-Path $env:SKILL_ROOT 'skills/ops/scope-contract.md'
if (-Not (Test-Path $scopeFile)) {
    Write-Error "Scope not initialized – run skills/scripts/case-init.ps1 first (see RULES.md)."
    exit 1
}

# After scope is confirmed, proceed with the selected skill

. (Join-Path $env:SKILL_ROOT $primarySkill)

These snippets demonstrate the two-layered approach: RULES.md governs the procedural guardrails, while routing.json drives the keyword-based decision of which skill to execute.

Summary

• RULES.md provides the high-level workflow and safety rules that define how the AI must operate, including initialization sequences and audit requirements.
• routing.json supplies the mechanical routing data that maps keywords to skill modules via regex matching and priority resolution.
• Scripts reference both: master-route.ps1 reads the JSON for routing decisions while respecting constraints defined in the markdown policy file.
• Related files include skills/MASTER-ROUTING.md (human-readable priority table) and skills/routing.md (full capability matrix), which expose the same routing information at different abstraction levels.

Frequently Asked Questions

Can I modify routing behavior by editing RULES.md?

No. To change which skill handles a specific task, you must edit routing.json in skills/config/. The RULES.md file controls the execution workflow, not the routing table itself. Changes to routing logic should never involve altering the policy documentation, as this maintains the separation between process control and data configuration.

What happens if multiple routes match a query in routing.json?

The priority array in routing.json resolves conflicts deterministically. When master-route.ps1 identifies multiple matching routes, it filters the matches against the priority list and selects the first match as the "PRIMARY" route. This ensures predictable behavior even when keyword patterns overlap between different skill modules.

How does the system ensure RULES.md is actually followed?

Scripts like case-init.ps1 and verify-routing-coherence.ps1 encode the procedural requirements from RULES.md into executable checks. For example, the system validates that skills/ops/scope-contract.md exists before proceeding, enforcing the initialization requirements declared in the policy file. This creates a hard dependency between the documented workflow and the actual execution path.

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