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

MASTER-ROUTING.md serves as the primary routing gateway for fast keyword matching, while 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, 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 (line 95):

未命中 → PRIMARY=R0，并提示打开 routing.md.

This Chinese notation translates to: "If no match → PRIMARY=R0, and prompt to open routing.md."

routing.md: The Detailed Fallback Matrix

Located at 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 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 for global policy context
2. Attempt primary match via MASTER-ROUTING.md (quick keyword scan, lines 5-15)
3. On success: open corresponding SKILL.md and execute
4. On failure: invoke routing.md for granular three-axis resolution
5. From 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:

# 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	Primary routing contract with fast-match rules and fallback trigger	skills/MASTER-ROUTING.md
routing.md	Full routing matrix with three-axis granular mapping	skills/routing.md
RULES.md	Global policy preamble for both routing stages	RULES.md
master-route.ps1	PowerShell implementation of the two-stage routing logic	skills/scripts/master-route.ps1

Summary

• MASTER-ROUTING.md is consulted first for rapid primary skill identification through keyword matching
• 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 per the execution protocol defined in 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. 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 document itself instructs users to "start from 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 yields no match and routing.md cannot resolve the target-intent-toolchain combination, the protocol requires proposing a new skill matrix entry. The 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 and the three-axis table in routing.md—while humans reference the surrounding explanatory prose.

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