Understanding the Routing Hierarchy in Reverse-Skill: A 3-Layer Architecture

The reverse-skill routing hierarchy uses a deterministic three-layer system that evaluates user hints against a prioritized JSON configuration, validates routes through a master contract, and resolves ambiguities via a three-axis matrix to select the appropriate security skill module.

The routing hierarchy in reverse-skill directs every user request to the most specific security analysis skill available across the repository. By combining machine-readable configuration with human-readable documentation, the system ensures consistent behavior across Windows PowerShell and Linux/macOS Bash environments.

Layer 1: Single-Source-of-Truth JSON Configuration

The foundation of the routing system resides in skills/config/routing.json, which contains a centralized dictionary of 41 specialized routes (R1 through R41) plus a fallback route (R0). This file serves as the immutable reference for all routing decisions.

Each route definition contains three critical fields:

• label – A human-readable description of the security scenario (e.g., "APK Reverse Engineering", "IDA Pro Analysis").
• skill – The relative filesystem path to the module's SKILL.md file (e.g., apk-reverse/SKILL.md, ida-reverse/SKILL.md).
• keywords – A collection of regular-expression rules used for pattern matching against user hints.

The matching logic relies on two keyword types: must patterns that must all match the input hint, and exclude patterns that must not match. The priority array at the bottom of the JSON file defines the evaluation order from most specific to most generic, ensuring the routing engine tests high-precision rules before falling back to general categories.

Layer 2: Master Routing Contract

The skills/MASTER-ROUTING.md file documents the execution contract that platform-specific scripts (master-route.ps1 and master-route.sh) must implement. This layer translates the abstract route IDs from the JSON configuration into concrete filesystem operations.

The contract includes:

• A priority table that maps each route ID (e.g., R1, R4, R7) to its corresponding skill directory (e.g., apk-reverse/, reverse-engineering/dsl-vm-reverse/, radare2/).
• Standardized post-routing actions requiring the analyst to open the skill's SKILL.md, enforce operational scope boundaries, and record evidence according to contracts in skills/ops/.
• Fallback behavior specifications for when no patterns match, defaulting to R0 ("General reverse-engineering").

Layer 3: Three-Axis Disambiguation Matrix

When the JSON-based pattern matching yields ambiguous results or multiple potential matches, the system consults skills/routing.md. This document provides a human-readable disambiguation framework organized along three dimensions:

1. Target Type – The artifact under analysis (APK, ELF binary, firmware image, cloud infrastructure).
2. User Intent – The specific action requested (decode, bypass authentication, draw control-flow diagrams, extract strings).
3. Toolchain – The preferred or available analysis tools (IDA Pro, radare2, Frida, Playwright, Ghidra).

The matrix enables the master route script to either confirm the PRIMARY route selection or propose the creation of a new skill module when existing routes prove insufficient.

Execution Flow and Algorithm Implementation

The routing execution follows a deterministic pipeline. When a user submits a hint such as "extract strings from a Windows PE binary", the platform-specific master route script performs the following operations:

#!/usr/bin/env bash
HINT="$1"
JSON=$(cat skills/config/routing.json)

# Load priority order from JSON configuration

PRIO=$(jq -r '.priority[]' <<<"$JSON")

for R in $PRIO; do
  # Extract regex patterns for current route

  MUST=$(jq -r ".routes[\"\($R)\"].keywords[]?.must // empty" <<<"$JSON")
  EXCL=$(jq -r ".routes[\"\($R)\"].keywords[]?.exclude // empty" <<<"$JSON")

  # Verify all mandatory patterns match

  MATCH=1
  while read -r pattern; do
    [[ "$HINT" =~ $pattern ]] || MATCH=0
  done <<<"$MUST"

  # Verify no exclusion patterns match

  while read -r excl; do
    [[ "$HINT" =~ $excl ]] && MATCH=0
  done <<<"$EXCL"

  # Return first valid match

  if (( MATCH )); then
    SKILL=$(jq -r ".routes[\"\($R)\"].skill" <<<"$JSON")
    echo "PRIMARY=$R  →  $SKILL"
    exit 0
  fi
done

# Execute fallback when no routes match

echo "PRIMARY=R0  →  reverse-engineering/"

For cross-platform compatibility, the repository maintains two implementations:

• skills/scripts/master-route.sh – Bash implementation for Linux and macOS environments.
• skills/scripts/master-route.ps1 – PowerShell implementation for Windows environments.

Both scripts consume the same routing.json configuration, ensuring identical routing decisions regardless of operating system.

Summary

• skills/config/routing.json serves as the single source of truth, containing regex-based route definitions (R1–R41) and a priority-ordered evaluation array.
• skills/MASTER-ROUTING.md establishes the execution contract, mapping route IDs to filesystem paths and defining mandatory post-routing procedures.
• skills/routing.md provides the three-axis disambiguation matrix (Target Type, User Intent, Toolchain) for resolving complex routing scenarios.
• The routing engine evaluates routes by priority, applying must and exclude regex patterns until finding the first match, then defaulting to R0 if no patterns satisfy the criteria.
• Cross-platform scripts (master-route.sh and master-route.ps1) implement identical logic to ensure consistent behavior across Windows, Linux, and macOS.

Frequently Asked Questions

How does reverse-skill handle routing when multiple patterns match a user hint?

The system evaluates routes strictly according to the priority array in skills/config/routing.json, testing from highest to lowest specificity. The first route where all must patterns match and no exclude patterns match becomes the PRIMARY route. If the match remains ambiguous, the master route script consults the three-axis matrix in skills/routing.md to disambiguate based on target type, user intent, and toolchain.

What happens if no routes match the provided user hint?

When no routes satisfy the regex criteria, the routing engine automatically selects route R0 ("General reverse-engineering") as the fallback. This behavior is hardcoded in both skills/scripts/master-route.sh and skills/scripts/master-route.ps1 to ensure the analyst always receives a valid skill module rather than an error.

Where are the route definitions and regex patterns stored?

All route definitions, including the label, skill path, and keywords containing must and exclude regex patterns, reside in skills/config/routing.json. This JSON file also contains the priority array that determines evaluation order, making it the single source of truth for the entire routing hierarchy in reverse-skill.

How does the system maintain consistency between Windows and Linux environments?

The repository implements the routing logic in two parallel scripts: skills/scripts/master-route.ps1 for PowerShell (Windows) and skills/scripts/master-route.sh for Bash (Linux/macOS). Both scripts read from the same skills/config/routing.json file and follow the execution contract defined in skills/MASTER-ROUTING.md, ensuring deterministic routing decisions regardless of platform.

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