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

> Explore the reverse-skill routing hierarchy. Understand its deterministic 3-layer architecture, route validation, and ambiguity resolution for efficient security skill module selection.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](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), [`ida-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) file documents the **execution contract** that platform-specific scripts (`master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash
#!/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) configuration, ensuring identical routing decisions regardless of operating system.

## Summary

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)** establishes the execution contract, mapping route IDs to filesystem paths and defining mandatory post-routing procedures.
- **[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) for Bash (Linux/macOS). Both scripts read from the same [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file and follow the execution contract defined in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), ensuring deterministic routing decisions regardless of platform.