# MASTER-ROUTING.md vs routing.md in reverse-skill: Understanding the Routing Architecture

> Explore the routing architecture in reverse-skill. Understand how MASTER-ROUTING.md and routing.md work together for efficient keyword matching and fallback routing.

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

---

**[`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) serves as the primary routing gateway for fast keyword matching, while [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) acts as a detailed fallback matrix consulted only when the primary routing is ambiguous or fails to produce a match.**

The **reverse-skill** repository uses a two-tier routing system to deterministically route tasks to appropriate skill modules. These two markdown files work in sequence to balance speed against coverage: one provides rapid primary selection, the other exhaustive secondary resolution.

## Primary vs. Secondary Routing Documents

The relationship between these files is hierarchical and conditional. Understanding when each applies prevents routing loops and ensures predictable skill selection.

### MASTER-ROUTING.md: The Entry Gate

Located at [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), this document establishes the **primary routing contract**. It contains:

- A concise **priority list** (R1-R39) mapping common keywords to primary skills
- **Eight execution protocol rules** governing contract enforcement
- An explicit **fallback clause** triggering when no match occurs

The documented read order enforced by this contract is:

```

RULES.md → MASTER-ROUTING.md → PRIMARY SKILL.md → (optional) routing.md

```

Key clause from [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) (line 95):

> 未命中 → PRIMARY=`R0`，并提示打开 [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md).

This Chinese notation translates to: *"If no match → PRIMARY=`R0`, and prompt to open [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)."*

### routing.md: The Detailed Fallback Matrix

Located at [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), this document contains the **full routing matrix** with:

- **Three-axis mapping**: target type × user intent × toolchain
- Normalization rules for ambiguous user language
- CTF-specific entries and edge-case coverage
- Protocol for proposing new skill matrix entries

The document references back to its parent in the "CRITICAL: Routing Execution Protocol" section (step 2):

> start from [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) or `scripts/master-route.ps1` for PRIMARY; use this full matrix when ambiguous.

## The Routing Pipeline in Practice

The reverse-skill framework executes this deterministic sequence:

1. **Initialize** with [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) for global policy context
2. **Attempt primary match** via [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) (quick keyword scan, lines 5-15)
3. **On success**: open corresponding [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and execute
4. **On failure**: invoke [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) for granular three-axis resolution
5. **From [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)**: either select existing skill or define new matrix entry

This architecture ensures **fast-path optimization** for common tasks without sacrificing coverage for complex scenarios.

## Implementation Example

The repository's PowerShell implementation mirrors this logic in `skills/scripts/master-route.ps1`:

```powershell

# Load the primary routing contract

$masterRoute = Get-Content "$PSScriptRoot\skills\MASTER-ROUTING.md"

# Attempt quick primary match (simplified from actual implementation)

$primarySkill = if ($Hint -match 'apk') { 'apk-reverse' }
               elseif ($Hint -match 'ios') { 'mobile-reverse' }
               elseif ($Hint -match 'elf|linux|binary') { 'linux-reverse' }
               else { $null }

if ($primarySkill) {
    Write-Host "Primary skill identified: $primarySkill"
    Invoke-Item "$PSScriptRoot\skills\$primarySkill\SKILL.md"
}
else {
    Write-Host "No primary match – consulting full routing matrix."
    # Load the detailed fallback matrix

    $routingMatrix = Get-Content "$PSScriptRoot\skills\routing.md"
    # Parse three-axis table for target+intent+toolchain match

}

```

## Key Architectural Files

| File | Role | GitHub Path |
|------|------|-------------|
| [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) | Primary routing contract with fast-match rules and fallback trigger | [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) |
| [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) | Full routing matrix with three-axis granular mapping | [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Global policy preamble for both routing stages | [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) |
| `master-route.ps1` | PowerShell implementation of the two-stage routing logic | `skills/scripts/master-route.ps1` |

## Summary

- **[`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)** is consulted **first** for rapid primary skill identification through keyword matching
- **[`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)** is consulted **second** only when primary routing returns ambiguous or null results
- The **bidirectional references** between documents ensure no routing state is orphaned
- Both documents are **markdown-based contracts** parsed by `master-route.ps1` and similar tooling
- This two-tier design optimizes for **common-case speed** while maintaining **complete-case coverage**

## Frequently Asked Questions

### How does reverse-skill decide which routing document to use?

The framework always starts with [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) per the execution protocol defined in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md). Only when the primary match fails—specifically when reaching step 8 of the eight-rule protocol—does the system fall back to [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md). This is implemented in `skills/scripts/master-route.ps1` through conditional logic that checks for null primary results.

### Can I use routing.md without first consulting MASTER-ROUTING.md?

While technically possible, the [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) document itself instructs users to "start from [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) or `scripts/master-route.ps1` for PRIMARY" before using the full matrix. Bypassing the primary stage violates the documented contract and may cause inconsistent routing behavior across different implementations.

### What happens if neither routing document produces a match?

If [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) yields no match and [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) cannot resolve the target-intent-toolchain combination, the protocol requires proposing a new skill matrix entry. The [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) file contains specific formatting rules for contributing new rows to its three-axis table, ensuring the routing system can evolve coverage organically.

### Are these files human-readable or machine-parsed?

Both. The markdown format serves dual purposes: human-readable documentation for manual consultation, and structured content for programmatic parsing. The `master-route.ps1` script parses specific sections—particularly the priority list in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) and the three-axis table in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)—while humans reference the surrounding explanatory prose.