What Is the Purpose of skills/routing.md in Reverse-Skill? A Complete Guide to the Routing Matrix

The skills/routing.md file in reverse-skill is a human-readable 3-axis routing matrix that maps user requests to appropriate skill modules based on target type, user intent, and toolchain.

This markdown file serves as the single source of truth for human-level decision-making in the zhaoxuya520/reverse-skill framework. It transforms vague user requests into precise skill invocations while working alongside machine-driven configuration files to ensure consistent, auditable routing across the entire reverse-engineering ecosystem.

How Routing.md Fits Into the Routing Architecture

The reverse-skill repository implements a tiered routing system where skills/routing.md occupies a specific fallback position. Understanding this hierarchy is essential for contributing to or extending the framework.

The Three-Tier Routing Stack

1. Primary route — config/routing.json provides machine-readable routing definitions
2. Human fallback — skills/routing.md offers advisory guidance when JSON routes are ambiguous
3. Skill execution — Individual SKILL.md files contain detailed implementation guidance

According to the source code, the JSON definition always takes precedence when conflicts occur between the machine-readable config and the human-readable matrix (source L3-L4).

The Master Routing Script Entry Point

All routing flows through skills/scripts/master-route.ps1, which orchestrates the decision process. The script first attempts resolution via config/routing.json, then falls back to parsing routing.md when the primary route reports ambiguity.

# Invoke the master routing script with a natural language hint

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "analyze Android APK"

The Three-Axis Disambiguation System

The core innovation of skills/routing.md is its three-dimensional matching protocol that eliminates ambiguity in skill selection. Every routing decision evaluates three mandatory dimensions.

Dimension 1: Target Type

The target type identifies what artifact or system requires reverse engineering. Common values include:

• APK / Android app
• ELF / Linux binary
• PE / Windows executable
• Firmware image
• iOS IPA

Dimension 2: User Intent

The user intent captures what the user wants to accomplish. Examples from the matrix include:

• Decompile / static analysis
• Dynamic analysis / runtime instrumentation
• Vulnerability research / exploit development
• Protocol reconstruction

Dimension 3: Toolchain

The toolchain specifies the preferred or available tooling ecosystem:

• IDA Pro + Hex-Rays
• Ghidra
• Radare2 / Cutter
• Frida
• Custom scripts

A complete routing entry matches all three dimensions to a concrete skill directory. The matrix format enforces this triple matching at source L18-L33.

Standardized Execution Protocol

skills/routing.md mandates strict behavioral rules through capitalized protocol statements. These constraints govern how routing must occur.

The "MUST" Directives

Directive	Requirement	Source
MUST complete routing BEFORE executing	No skill action until routing resolution	L7-L13
MUST match dimensions	All three axes require alignment	L18-L33
If route not matched → propose new skill	Escalation path for uncovered scenarios	L11-L13

These directives ensure that routing happens before any action — the matrix is consulted either after primary JSON resolution or during fallback, and resolution must complete before any skill module executes.

Cross-Module and Path-Crossing Guidance

Complex reverse-engineering workflows often span multiple skill domains. The skills/routing.md file addresses this through dedicated "Path Crossing" sections.

Multi-Stage Routing Example

Consider an Android security assessment that requires:

1. APK decompilation (initial skill)
2. Native library analysis (SO skill)
3. Runtime hooking (Frida skill)

The matrix at source L91-L100 defines how to combine skills sequentially rather than treating stages as independent routings.

# Pseudo-implementation of path-crossing handling

import pathlib, re

matrix = pathlib.Path("skills/routing.md").read_text()

# Detect multi-stage indicator in matrix

if "Path Crossing" in matrix:
    # Extract ordered skill chain for APK → SO → Frida

    chain_pattern = r"Path Crossing.*APK.*SO.*Frida.*?\n(.*?)(?:\n\n|\Z)"
    match = re.search(chain_pattern, matrix, re.DOTALL)
    if match:
        stages = ["apk-reverse/", "so-reverse/", "frida-scripts/"]
        for stage in stages:
            skill_doc = pathlib.Path(f"{stage}/SKILL.md").read_text()
            # Execute stage with context from previous stages

            print(f"Executing {stage}...")

Practical Workflow: From Request to Skill Execution

This complete example demonstrates the three-step process mandated by the routing architecture.

Step 1: Invoke Master Route

# Run with explicit hint

$result = powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "decompile Android APK with IDA"

# $result contains either:

# - "RESOLVED: apk-reverse/" (primary route success)

# - "PRIMARY ambiguous" (fallback to matrix required)

Step 2: Fall Back to Routing Matrix (If Needed)

import json, pathlib, re

# Load primary routing result

with open("skills/config/routing.json") as f:
    primary = json.load(f)

skill_dir = None

if primary.get("status") == "ambiguous":
    # Parse the human-readable matrix

    matrix = pathlib.Path("skills/routing.md").read_text()
    
    # Match target="APK / Android app" AND intent="decompile"

    pattern = r"\|\s*APK / Android app\s*\|\s*[^|]*decompile[^|]*\|\s*[^|]*\|\s*([^|\n]+)"
    match = re.search(pattern, matrix)
    
    if match:
        skill_dir = match.group(1).strip()
        print(f"Matrix routing → {skill_dir}")

Step 3: Load Skill Documentation Before Action

# Mandatory: read SKILL.md before any execution

$skillPath = "apk-reverse/"
$skillDoc = Get-Content "$skillPath/SKILL.md"

# Document contains:

# - Prerequisites and dependencies

# - Step-by-step procedures

# - Expected outputs and validation

Write-Host "Routing complete. Skill documentation loaded from $skillPath/SKILL.md"

Key Files in the Routing Ecosystem

File	Purpose	Relationship to routing.md
skills/routing.md	Human-readable 3-axis matrix	Subject of this article — advisory fallback
skills/config/routing.json	Machine-readable primary routes	Overrides matrix on conflict
skills/scripts/master-route.ps1	Routing orchestration script	Consumes both JSON and markdown
skills/tool-index.md.template	Tool reference generator	Feeds toolchain dimension data
*/SKILL.md	Individual skill documentation	Final destination after routing

Summary

• skills/routing.md provides human-readable, three-axis routing (target type, user intent, toolchain) for the reverse-skill framework.

• It operates as a fallback mechanism when config/routing.json produces ambiguous results, with JSON taking precedence on conflicts.

• The file enforces strict execution protocols including mandatory pre-execution routing and dimension matching requirements.

• Path-crossing sections handle multi-stage workflows that span multiple skill modules.

• All routing flows through skills/scripts/master-route.ps1, which implements the tiered resolution logic.

• Contributors should treat routing.md as the authoritative human reference while maintaining routing.json as the primary machine-readable source.

Frequently Asked Questions

What happens when routing.json and routing.md disagree?

The JSON configuration always wins. According to source L3-L4, skills/routing.md explicitly states it is "advisory only" and the machine-readable config/routing.json takes precedence when conflicts occur. The markdown matrix serves as structured documentation and fallback guidance, not as an override mechanism.

Can I use routing.md without the PowerShell master script?

Yes, though not recommended for production workflows. The file uses standard markdown tables that any tooling can parse. The Python example in this article demonstrates regex-based extraction of routing decisions. However, master-route.ps1 implements additional validation, logging, and integration with the broader ecosystem that custom implementations would need to replicate.

How do I add a new skill to the routing matrix?

First, create your skill directory with a complete SKILL.md file. Then add a row to skills/routing.md specifying all three dimensions (target type, intent, toolchain) and the skill directory path. Finally, register the primary route in config/routing.json for machine consumption. The protocol requires testing that both routing paths resolve to your new skill before deployment.

Why three axes instead of simpler keyword matching?

Three-axis disambiguation prevents false positives in a domain where tool selection has significant consequences. A request for "APK analysis" could mean static decompilation, dynamic instrumentation, or network protocol extraction — each requiring different skills. The target-intent-toolchain decomposition ensures precise matching and provides clear extension points as the ecosystem grows.

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