# Difference Between master-route.ps1 and master-route.sh in reverse-skill

> Discover the core differences between master-route.ps1 and master-route.sh in reverse-skill. Understand platform targeting and script functionality for Windows and Unix-like systems.

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

---

**The primary distinction is platform targeting:** `master-route.ps1` is a native PowerShell implementation for Windows systems, while [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) is a Bash wrapper that delegates routing logic to embedded Python for Unix-like environments. Both scripts consume the same [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) configuration and produce identical output, but differ fundamentally in language, dependencies, and runtime architecture.

The `reverse-skill` repository maintains dual entry points to ensure cross-platform compatibility for its routing engine. Understanding these differences helps operators choose the appropriate script for their environment and troubleshoot execution failures. This analysis examines the source code of both scripts to reveal their architectural decisions, dependency requirements, and behavioral nuances.

## Target Platforms and Runtime Requirements

**`master-route.ps1`** targets Windows PowerShell 5.1 and PowerShell Core (pwsh) on any platform. It requires no external interpreters—only a functioning PowerShell environment.

**[`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)** targets Unix-like shells on Linux, macOS, and Kali systems. It requires both Bash and Python 3, with runtime detection in [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) lines 31-40:

```bash
if ! command -v python3 &> /dev/null; then
    echo "Error: python3 is required but not installed." >&2
    exit 2
fi

```

## Language Architecture and Implementation Strategy

The most significant architectural divergence lies in how each script implements the routing algorithm.

### PowerShell: Pure Native Implementation

In `skills/scripts/master-route.ps1`, all functionality is implemented in PowerShell. The script uses:

- **`param()` block** for argument parsing with named parameters (`-Hint`, `-OutDir`, `-ProjectRoot`)
- **Regex matching** via PowerShell's `-match` operator for `must`, `mustAll`, and `exclude` rules (lines 35-52)
- **`System.Collections.Generic.List[string]`** for score accumulation and priority ordering (lines 54-88)

### Bash: Python Delegation Pattern

In [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh), Bash serves only as a wrapper. The core routing logic resides in an embedded Python heredoc structure (lines 85-100), which:

- Parses command-line arguments through a `while`–`case` loop (`--hint`, `--out-dir`, `--project-root`)
- Loads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) using `json.loads()` with UTF-8-SIG encoding (lines 66-70)
- Performs regex matching via Python's `re.search` module
- Stores scores in a Python `dict` with priority-ordered selection (lines 11-16)

## Configuration Loading: Same Source, Different Parsers

Both scripts consume the identical [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file but use platform-appropriate parsing methods.

**PowerShell approach (master-route.ps1 lines 20-33):**

```powershell
$configPath = Join-Path $scriptPath ".." ".." "skills" "config" "routing.json"
$configJson = Get-Content $configPath -Raw -Encoding UTF8
$routingConfig = ConvertFrom-Json $configJson

```

**Python approach (master-route.sh lines 66-70):**

```python
config_path = (pathlib.Path(__file__).resolve().parent.parent.parent / "skills" / "config" / "routing.json")
config = json.loads(pathlib.Path(config_path).read_text(encoding="utf-8-sig"))

```

The UTF-8-SIG handling in the Python version explicitly handles BOM-encoded files, while the PowerShell version relies on PowerShell's native UTF8 encoding detection.

## Output Generation and Encoding

Output formatting differs in implementation but produces functionally equivalent results.

| Aspect | PowerShell (master-route.ps1) | Bash/Python (master-route.sh) |
|--------|-------------------------------|-------------------------------|
| String building | `System.Text.StringBuilder` | Python list append operations |
| File encoding | UTF-8 with BOM (Windows compatibility) | Pure UTF-8 (no BOM) |
| Output lines | Lines 39-70 | Lines 36-61 in embedded Python |

The BOM in the PowerShell output ensures correct display in Windows Notepad and legacy Windows tools, while the Unix version omits it for standard POSIX compliance.

## Argument Handling Comparison

The command interfaces are similar but use platform-appropriate conventions:

```powershell

# Windows - PowerShell style with dashes

powershell -File skills/scripts/master-route.ps1 -Hint "enumerate open ports" -OutDir "C:\temp\output" -ProjectRoot "C:\projects\reverse-skill"

```

```bash

# Linux/macOS - GNU long-option style

bash skills/scripts/master-route.sh --hint "enumerate open ports" --out-dir /tmp/output --project-root /home/user/reverse-skill

```

Note the single-dash PowerShell convention versus double-dash GNU style, and the case sensitivity (`-OutDir` vs `--out-dir`).

## Error Handling and Exit Codes

Both scripts use identical exit code semantics for cross-platform consistency:

- `0` — Successful routing and file generation
- `2` — Configuration file missing, skill file not found, or runtime dependency failure

The PowerShell script implements explicit `exit 2` statements for configuration errors, while the Bash script propagates Python's exit code through `exit $?`.

## Cross-Platform Considerations

**PowerShell Core fallback:** `master-route.ps1` can execute on Linux and macOS through PowerShell Core (pwsh), though this requires intentional installation of the PowerShell runtime.

**Bash+Python ubiquity:** [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) leverages the near-universal presence of Python 3 on penetration testing distributions (Kali, Parrot) and modern Unix workstations, avoiding PowerShell as a dependency.

## Usage Examples by Platform

### Windows Native Execution

```powershell

# From Command Prompt (cmd.exe)

powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\master-route.ps1 -Hint "sql injection detection" -OutDir "C:\Users\analyst\routes"

# From PowerShell directly

.\skills\scripts\master-route.ps1 -Hint "buffer overflow analysis" -ProjectRoot "D:\work\reverse-skill"

```

### Linux/macOS Execution

```bash

# Direct execution with explicit bash

bash skills/scripts/master-route.sh --hint "firmware extraction" --out-dir ~/analysis/route-output

# With execution bit set

chmod +x skills/scripts/master-route.sh
./skills/scripts/master-route.sh --hint "protocol reverse engineering"

```

## Key File Reference

| File | Purpose |
|------|---------|
| `skills/scripts/master-route.ps1` | Windows routing entry point (PowerShell native) |
| [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) | Unix routing entry point (Bash wrapper + Python) |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Shared routing rule definitions |
| `skills/scripts/lib/WorkRoot.ps1` | PowerShell helper for path resolution |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable routing documentation |

## Summary

- **`master-route.ps1`** provides a **pure PowerShell implementation** optimized for Windows environments with native .NET integration and BOM-encoded output for legacy Windows tool compatibility.

- **[`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)** implements a **hybrid Bash/Python architecture** that prioritizes Unix compatibility through Python's portable standard library, requiring an external interpreter but maximizing cross-distribution reliability.

- Both scripts produce **identical routing decisions** from the same [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) source, ensuring consistent skill selection regardless of platform.

- **Exit codes and core behavior are unified** (`0` for success, `2` for errors) to support portable automation and CI/CD pipelines.

- Choose `master-route.ps1` for Windows-native operations or environments with PowerShell Core; choose [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) for standard Unix penetration testing workflows where Python 3 is guaranteed.

## Frequently Asked Questions

### Can I run master-route.ps1 on Linux or macOS?

Yes, through PowerShell Core (pwsh). Install PowerShell Core from Microsoft repositories or Homebrew, then execute `pwsh skills/scripts/master-route.ps1 -Hint "your query"`. The script's .NET dependencies function identically on all PowerShell-supported platforms.

### Why does master-route.sh require Python instead of pure Bash?

The embedded Python in [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) lines 85-100 provides portable JSON parsing, regex operations, and dictionary-based scoring that would require external dependencies or complex text processing in pure Bash. Python 3 is standard on security-focused distributions, making this dependency acceptable for the target audience.

### Do both scripts produce identical route-scope.md files?

Functionally yes—the same routing rules applied to identical hints yield the same primary skill selection. Minor differences exist in output encoding (UTF-8-BOM versus pure UTF-8) and timestamp formatting, but the markdown structure and skill content are equivalent.

### What happens if routing.json is malformed?

Both scripts exit with code `2`. The PowerShell version throws a descriptive `ConvertFrom-Json` exception pointing to the syntax error location. The Python version raises a `json.JSONDecodeError` with line and column information. Neither script continues with partial or default routing in this failure mode.