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

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 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 (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, 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 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 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. 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 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, and executes the skill script with PROJECT_ROOT and HINT pre-configured.

Windows PowerShell Execution

Run the PowerShell version to perform memory analysis:

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:

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 – The Bash implementation handling Linux/macOS execution flows.
• skills/scripts/master-route.ps1 – The PowerShell implementation providing Windows compatibility.
• 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 – 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 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, 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 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 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. The master-route script dynamically reads this configuration at runtime, requiring no changes to master-route.sh or master-route.ps1 themselves.

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