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

> Learn how to auto-route using the master-route.ps1 script with this comprehensive guide. Automate your reverse engineering workflow efficiently.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)**: The architectural documentation referenced within generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.