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

> Understand RULES.md vs routing.json in the Reverse-Skill routing workflow. Discover how RULES.md sets guardrails and routing.json maps requests to modules for efficient AI client operation.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-15

---

**[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) defines the mandatory execution pipeline and safety guardrails that AI clients must follow, while [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) and how to initialize the case scope before any action.

- **[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)** serves as the **data-driven routing table**. Stored at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file (e.g., [`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) to establish the execution environment, then queries [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to select the specific skill module.

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

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) prerequisites are satisfied:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) governs the procedural guardrails**, while **[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) drives the keyword-based decision** of which skill to execute.

## Summary

- **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) (human-readable priority table) and [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)** in `skills/config/`. The [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) into executable checks. For example, the system validates that [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.