# How the master-route Script Functions in reverse-skill: A Deep Dive

> Discover how the master-route script in reverse-skill acts as the unified entry point. It parses hints and routes execution to security modules using a JSON routing table.

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

---

**The master-route script serves as the unified entry point for the reverse-skill repository, parsing user hints and dynamically routing execution to specialized security or reverse-engineering skill modules by reading a central JSON routing table and sourcing the appropriate skill script.**

The `master-route` script is the central dispatcher in the open-source reverse-skill project, orchestrating how user requests flow through various reverse-engineering and security analysis workflows. Available as both [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) and `master-route.ps1`, this tool provides a consistent, cross-platform interface for skill discovery and execution while maintaining strict environment isolation through configurable working directories.

## What Is the master-route Script?

The master-route script functions as the primary command-line interface and execution router for the reverse-skill ecosystem. It accepts a natural language **hint** describing the desired reverse-engineering task, resolves the appropriate skill module using a JSON-based routing configuration, and executes the target skill with properly isolated environment variables. Both Bash and PowerShell implementations share identical logical flow, enabling seamless operation across Linux, macOS, and Windows environments.

## Core Architecture and Execution Flow

The script operates through five distinct phases, from argument intake to post-execution cleanup.

### Argument Parsing and Validation

The script strictly validates required inputs before proceeding. In [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) (lines 16‑28), the parser extracts `--hint`, `--out-dir`, and `--project-root` flags, exiting with usage instructions if the hint is absent. The PowerShell counterpart in `skills/scripts/master-route.ps1` (lines 12‑25) performs equivalent parameter binding using `param()` declarations, ensuring cross-platform consistency in input handling.

### Environment Setup and Directory Structure

Once arguments are validated, the script establishes the execution environment. It resolves the absolute **PROJECT_ROOT**—defaulting to the script's parent directory—and creates a timestamped working directory under `work/master-route-<timestamp>` unless the user specifies an alternative via `--out-dir`. The Bash implementation (lines 31‑50) exports `PROJECT_ROOT`, `OUT_DIR`, and `HINT` as environment variables, while the PowerShell version (lines 27‑45) achieves similar isolation using script-scope variables and leverages `skills/scripts/lib/WorkRoot.ps1` for path resolution utilities.

### Routing Decision Engine

The core routing logic consults [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), which maps target types and intents to concrete skill file paths. The Bash script invokes the routing helper around line 55, while the PowerShell version imports `skills/scripts/lib/RouteScope.ps1` and calls `Resolve-Route` to translate the natural language hint into a specific skill file path (e.g., [`skills/pe-reverse/skill.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pe-reverse/skill.sh) or `skills/ida-reverse/skill.ps1`). This decoupling allows new skills to be added solely by updating the JSON configuration without modifying the master script.

### Skill Execution

After resolving the skill path, the master-route script transfers control to the target module. In [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) line 68, the script uses `source "$SKILL_PATH"` to execute the skill within the same shell context, preserving all exported environment variables. The PowerShell implementation (line 63) uses the call operator `& $SkillPath` to achieve equivalent behavior. The skill script then performs its specialized logic—such as binary analysis, sandbox preparation, or proof-of-concept generation—writing outputs to the designated `OUT_DIR`.

### Post-Processing and Evidence Collection

Following skill completion, the master-route script handles cleanup and documentation. Optional post-run helpers such as `skills/scripts/append-evidence.ps1` record generated artefacts to a central evidence log, while `verify-routing-coherence.ps1` validates that the routing decision aligns with the entries in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). The script ultimately exits with the skill's native exit code, propagating success or failure states to the calling process (Bash lines 71‑78; PowerShell lines 70‑77).

## Cross-Platform Implementation Details

Both implementations maintain architectural parity while respecting platform idioms. The Bash version relies on standard POSIX utilities and `source` for script inclusion, whereas the PowerShell version utilizes `Import-Module` for library loading and strict mode enforcement. This dual implementation ensures that reverse-skill workflows function identically whether executed from a Linux terminal, macOS shell, or Windows PowerShell console.

## Practical Usage Examples

### Linux and macOS Execution

Invoke the Bash version from the repository root to analyze a PE file:

```bash
bash skills/scripts/master-route.sh \
  --hint "analyse a PE file for packer detection" \
  --out-dir /tmp/pe-analysis

```

This command creates the output directory, resolves the hint to the appropriate PE reverse-engineering skill via [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), and executes the skill script with `PROJECT_ROOT` and `HINT` pre-configured.

### Windows PowerShell Execution

Run the PowerShell version to perform memory analysis:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 `
  -Hint "dump credentials from LSASS" `
  -OutDir "C:\Temp\lsass-output"

```

The PowerShell script follows the identical routing logic, ultimately invoking the LSASS-dumping skill module located by the routing engine.

### Programmatic Integration

Embed the master-route logic within larger automation pipelines by exporting the required variables before sourcing:

```bash
export HINT="enumerate AD groups"
export PROJECT_ROOT=$(pwd)
export OUT_DIR=$(mktemp -d)
source skills/scripts/master-route.sh

# Skill executes immediately with inherited environment

```

This pattern allows CI/CD systems or wrapper scripts to leverage the routing engine without spawning separate processes.

## Key Source Files and Dependencies

The master-route script relies on several critical components within the repository structure:

- **[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)** – The Bash implementation handling Linux/macOS execution flows.
- **`skills/scripts/master-route.ps1`** – The PowerShell implementation providing Windows compatibility.
- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The central configuration file mapping hints to skill file paths.
- **`skills/scripts/lib/RouteScope.ps1`** – PowerShell library containing the `Resolve-Route` function for JSON parsing and intent matching.
- **[`skills/scripts/lib/RouteScope.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/lib/RouteScope.sh)** – Bash counterpart for routing resolution, invoked by the shell script.
- **`skills/scripts/lib/WorkRoot.ps1`** – Utility module for project root resolution and directory creation.
- **`skills/scripts/append-evidence.ps1`** – Post-execution helper for logging artefacts and execution metadata.

## Summary

- The master-route script provides a unified entry point for all reverse-skill operations, accepting natural language hints and routing them to appropriate modules.
- It utilizes [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and platform-specific RouteScope libraries to resolve hints to concrete skill file paths without hardcoding module locations.
- Both Bash and PowerShell implementations enforce consistent environment variable isolation (`PROJECT_ROOT`, `OUT_DIR`, `HINT`) and create timestamped working directories for output segregation.
- Skills are executed via `source` (Bash) or the call operator (PowerShell), allowing direct environment inheritance while maintaining modular separation of concerns.
- Post-processing helpers like `append-evidence.ps1` support forensic documentation and routing validation after skill completion.

## Frequently Asked Questions

### How does the master-route script determine which skill to execute?

The script reads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), which defines hierarchies of target types and intents mapped to specific skill file paths. It passes the user-provided hint to the `RouteScope` library (`RouteScope.ps1` on Windows, [`RouteScope.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RouteScope.sh) on Unix), which performs pattern matching or keyword analysis to return the absolute path to the appropriate skill script.

### Can master-route be executed from outside the repository directory?

Yes, provided you specify the `--project-root` flag or ensure the script can resolve its location. The script defaults to determining `PROJECT_ROOT` based on its own file location, but explicitly setting `--project-root` allows invocation from any working directory while maintaining correct path resolution for skills and configuration files.

### What happens if the skill script fails or returns an error code?

The master-route script propagates the exit code from the skill script directly to the parent process. According to the source in [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) lines 71‑78 and `master-route.ps1` lines 70‑77, the master script captures the skill's return value and exits with that same status, ensuring that calling automations or CI pipelines can detect and respond to skill failures appropriately.

### Is it possible to add custom skills without modifying the master-route script?

Absolutely. The architecture intentionally decouples routing from execution. To add a new skill, create a new script file in the `skills/` directory and register its path and associated hint keywords in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). The master-route script dynamically reads this configuration at runtime, requiring no changes to [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) or `master-route.ps1` themselves.