How to Auto-Route Using the master-route.ps1 Script: A Complete Guide

The master-route.ps1 script in the reverse-skill framework analyzes user hints via regex pattern matching to select the optimal skill module, generates a confidence-rated routing decision, and produces a route-scope.md file that drives the entire reverse engineering workflow.

The master-route.ps1 script serves as the central router for the zhaoxuya520/reverse-skill repository, automating the selection of appropriate skill modules based on natural language task descriptions. By mapping user hints to 39 predefined route IDs (R0 through R38) using ordered dictionaries and regex pattern detection, the script eliminates manual browsing through the skill library. Understanding how to auto-route using the master-route.ps1 script enables analysts to instantly match tasks—whether APK analysis, firmware extraction, or cloud container escapes—with the specialized knowledge bases stored in individual SKILL.md files.

How the Auto-Routing Engine Works

The script operates through a deterministic nine-step pipeline implemented in skills/scripts/master-route.ps1. Each stage transforms user input into a structured routing decision that the rest of the framework consumes.

Input Handling and Parameter Parsing

The script accepts two optional parameters via a [param] block: -Hint (the task description) and -OutDir (custom output directory). When provided, the hint is normalized to lowercase using $Hint.ToLowerInvariant() and stored in variable $t to ensure case-insensitive matching against keyword patterns.

# From master-route.ps1 param block

param(
    [string]$Hint,
    [string]$OutDir
)

$t = if ($Hint) { $Hint.ToLowerInvariant() } else { '' }

If invoked without parameters, the script proceeds with an empty string, eventually defaulting to the generic reverse-engineering route.

Pattern Detection and Keyword Mapping

The core routing logic relies on two parallel ordered dictionaries defined early in the script: $map (linking route IDs like R0, R1, etc., to relative paths of SKILL.md files) and $labels (containing human-readable descriptions). Between lines 100-149, a series of regex checks (if ($t -match …)) scan the lowercase hint for domain-specific terminology covering both English and Chinese keywords—such as apk, ios, radare, firmware, malware, k8s, and cloud.

Matching route IDs accumulate in a temporary list $sel. After pattern evaluation, the script deduplicates these into $uniq to prevent duplicate entries when multiple keywords match.

Primary Route Selection and Priority Logic

Route resolution follows a hard-coded priority list ($priority) that the script traverses from highest to lowest precedence. The first ID found in both $priority and $uniq becomes the PRIMARY route. If no patterns match, the script falls back to R0, which maps to the generic reverse-engineering skill.

This priority-based approach ensures that specific technical terms (e.g., "APK") take precedence over general ones (e.g., "binary") when both match.

Confidence Rating and Output Generation

The script assigns confidence levels based on match cardinality:

• High: Only one route ID detected in $uniq
• Medium: Multiple potential routes found
• Low: No patterns matched (using fallback R0)

For the output stage, the script constructs the destination path. If -OutDir is omitted, it creates a timestamped folder under work\ (when running from the repository root) or falls back to the system temp directory. The script then builds a markdown document (route-scope.md) using a StringBuilder ($sb), embedding metadata including timestamp, original hint, primary route, confidence level, and secondary route candidates. The file is written with UTF-8 BOM encoding for Windows compatibility.

Running the Auto-Routing Script

Execute master-route.ps1 from the skills/scripts/ directory using PowerShell. Provide a descriptive hint to enable pattern matching, or run without parameters to receive the default generic route.

# Basic usage with task hint

.\master-route.ps1 -Hint "apk reverse engineering with jadx"

# Custom output directory

.\master-route.ps1 -Hint "cloud k8s container escape" -OutDir "C:\temp\my-route"

# Run without hint (defaults to generic reverse engineering)

.\master-route.ps1

Upon completion, the console displays the routing decision:

PRIMARY -> skills/apk-reverse/SKILL.md
Label: APK reverse | confidence: high
Wrote C:\path\to\work\master-route-20260801-143210\route-scope.md
ACTION: Open PRIMARY SKILL.md now and execute ACTION REQUIRED.

Understanding the Generated route-scope.md

The route-scope.md file serves as the workflow manifest. It contains structured metadata that downstream scripts and analysts consume to initialize the correct working context. The document includes the timestamp of creation, the original hint provided, the selected PRIMARY route path (e.g., skills/apk-reverse/SKILL.md), the confidence rating, and a list of secondary routes that also matched but were deprioritized.

Analysts should open this file immediately after generation to review the checklist, then navigate to the primary skill's SKILL.md to execute the ACTION REQUIRED section specific to that domain.

Integration with the Reverse-Skill Workflow

The auto-routing system connects to broader framework utilities:

• case-init.ps1: A wrapper script that can invoke master-route.ps1 during new case initialization, streamlining the setup of investigation environments.
• verify-routing-coherence.ps1: Validates that the routing matrix remains consistent across the repository, ensuring that all 39 route IDs in $map correspond to existing skill directories.
• MASTER-ROUTING.md: The architectural documentation referenced within generated route-scope.md files, explaining the routing philosophy and priority structure.

Summary

• master-route.ps1 is located at skills/scripts/master-route.ps1 and functions as the central router for the reverse-skill framework.
• The script uses regex pattern matching (lines 100-149) against 39 predefined routes (R0-R38) to detect appropriate skill modules from user hints.
• Primary route selection follows a hard-coded priority list, with R0 (generic reverse-engineering) serving as the fallback when no patterns match.
• The script generates a route-scope.md file with UTF-8 BOM encoding, containing metadata, confidence ratings (high/medium/low), and routing instructions.
• Output directories default to timestamped folders under work\ or system temp, but can be overridden via the -OutDir parameter.

Frequently Asked Questions

What happens if my hint matches multiple skill domains?

When multiple regex patterns match, the script collects all route IDs in $uniq and assigns a medium confidence rating. It then consults the internal $priority list and selects the highest-precedence matching ID as the PRIMARY route. You can review secondary matches in the generated route-scope.md file to determine if the priority selection requires manual override.

Can I use master-route.ps1 without providing a hint?

Yes. Running .\master-route.ps1 without the -Hint parameter proceeds with an empty string input. The pattern detection stage finds no matches, triggering the fallback to R0 (generic reverse-engineering) with a low confidence rating. The script still generates a route-scope.md file directing you to the generic skill documentation.

How does the script handle special characters or mixed languages in hints?

The script normalizes input using $Hint.ToLowerInvariant() before regex evaluation, ensuring consistent matching regardless of casing. The regex patterns (lines 100-149) include support for both English and Chinese terminology, allowing hints like "apk分析" or "kubernetes逃逸" to match correctly. However, the script does not perform language translation—it relies on the pre-defined keyword dictionary covering domain-specific terms.

Where should I look if the generated route seems incorrect?

First, check the confidence rating in route-scope.md. A low confidence indicates fallback to R0. If the confidence is medium or high but the skill seems mismatched, review the MASTER-ROUTING.md file to understand the priority rankings. You can also run verify-routing-coherence.ps1 to ensure the routing matrix is intact, or manually inspect the $map and $labels dictionaries in master-route.ps1 to verify that your keywords are defined in the pattern detection block.

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