# How reverse-skill Handles Platform-Specific Execution: Architecture and Implementation

> Discover how reverse-skill manages platform-specific execution using native shell wrappers for Windows and Unix-like systems, ensuring consistent CLI contracts and routing logic.

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

---

**reverse-skill isolates OS differences at the entry-point level by providing native shell wrappers—`master-route.ps1` for Windows and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) for Unix-like systems—that share an identical CLI contract and delegate to platform-agnostic routing logic.**

The reverse-skill repository implements a sophisticated **platform-specific execution** strategy that allows reverse engineering workflows to run identically across Windows, Linux, macOS, and Kali systems. By abstracting operating system differences into thin shell-specific entry scripts, the project ensures consistent routing semantics while respecting native PowerShell and Bash conventions. This design enables analysts to execute complex reverse-engineering tasks using familiar shell syntax while the underlying framework maintains behavioral parity across environments.

## The Dual Entry-Point Architecture

The repository ships two native routing scripts located in `skills/scripts/` that serve as the sole platform-specific components. Both scripts implement the `master-route.*` contract documented in [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) (lines 13 and 86) and [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) (line 3), ensuring that differences between Windows and Unix-like systems are contained entirely within these entry points.

### Windows PowerShell Entry Point

For Windows environments, reverse-skill provides `skills/scripts/master-route.ps1`. This PowerShell script handles Windows-specific path conventions, execution policy requirements, and PowerShell parameter binding while exposing the same interface as its Bash counterpart. As documented in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) (line 19) and [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) (line 40), Windows users invoke the framework using standard PowerShell execution syntax.

### Linux, macOS, and Kali Bash Entry Point

Unix-like systems—including Linux distributions, macOS, and Kali—use [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh). This Bash implementation mirrors the PowerShell entry point's CLI parsing logic and argument validation. According to the source analysis of [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) (line 16), both scripts validate identical argument signatures (`--hint`, `--out-dir`, `--project-root`) before proceeding to platform-neutral logic.

## Unified Execution Flow Beyond the Entry Point

Once the entry script initializes, **platform-specific execution** concerns disappear. Both `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) delegate to a shared pipeline that operates identically regardless of the host operating system.

### CLI Contract and Argument Parsing

Both entry scripts parse the same standardized options:
- `--hint`: Specifies the reverse-engineering task or target skill
- `--out-dir`: Defines the output directory for artifacts  
- `--project-root`: Locates the project base path

This contract enforcement ensures that a command string valid in Bash remains semantically identical when translated to PowerShell, with only the shell invocation syntax changing.

### Case Initialization and Security Gating

After argument validation, the entry scripts invoke their respective `case-init.*` counterparts ([`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) for Bash, `case-init.ps1` for PowerShell). These initialization scripts create temporary case directories and invoke `case-guard.*` scripts to enforce security barriers. According to [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) (line 11), the `case-guard.*` scripts enforce an `auth.status=granted` barrier that prevents unauthorized actions (ACT) regardless of the underlying platform. This ensures that **security gating** remains consistent whether the analysis runs on Windows or Linux.

### Centralized Routing Configuration

Following successful initialization and guard checks, both entry scripts read from [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) to resolve the primary skill matching the provided hint. This JSON file serves as the central routing contract, mapping task hints to specific skill definitions. Because the routing configuration is platform-neutral, the same skill definitions execute identically across all supported operating systems, with secondary suggestions presented to the analyst in the same format.

## Cross-Platform Command Examples

The following examples demonstrate how reverse-skill achieves **platform-specific execution** while maintaining workflow consistency:

```bash

# Linux / macOS / Kali – run a reverse-engineering task

bash skills/scripts/master-route.sh --hint "apk reverse" --out-dir out

```

```powershell

# Windows – run a Windows AD enumeration task

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 `
    --hint "bloodhound enumeration" --out-dir out

```

Both commands ultimately execute the same routing logic, create identical directory structures (temporary case folders, evidence folders), and produce comparable output artifacts.

## Key Source Files and Their Roles

Understanding the **platform-specific execution** model requires familiarity with these critical components:

- **`skills/scripts/master-route.ps1`**: Windows entry point written in PowerShell that handles Windows-specific invocation requirements
- **[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)**: Linux/macOS/Kali entry point written in Bash that implements the same CLI contract
- **[`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh)** and **`case-init.ps1`**: Platform-specific initialization scripts that create temporary case directories and prepare the execution environment
- **[`skills/scripts/case-guard.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-guard.sh)** and **`case-guard.ps1`**: Security gate scripts that enforce `auth.status=granted` validation before allowing workflow continuation
- **[`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json)**: Central routing contract that maps hints to primary skills, shared across all platforms
- **[`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md)**: Documentation defining the platform-native routing contract and cross-platform behavior expectations

## Summary

- reverse-skill uses native shell wrappers at `skills/scripts/master-route.ps1` and [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) to handle **platform-specific execution**.
- Both entry scripts enforce an identical CLI contract parsing `--hint`, `--out-dir`, and `--project-root` arguments before delegating to shared logic.
- The architecture maintains platform neutrality beyond initialization through shared [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) definitions and unified skill execution paths.
- Security gating via `case-guard.*` scripts ensures uniform `auth.status=granted` enforcement across Windows, Linux, macOS, and Kali environments.

## Frequently Asked Questions

### What are the specific entry scripts for each platform in reverse-skill?

Windows systems use `skills/scripts/master-route.ps1`, while Linux, macOS, and Kali systems use [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh). Both are located in the `skills/scripts/` directory and implement an identical command-line interface, allowing users to invoke reverse-skill using their native shell syntax.

### How does reverse-skill ensure routing consistency between PowerShell and Bash?

The repository enforces a strict contract documented in [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) (lines 13 and 86) and [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) (line 3) that both shell implementations must follow. Both scripts parse the same arguments (`--hint`, `--out-dir`, `--project-root`) and ultimately read from the same [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) file, ensuring that skill resolution behaves identically regardless of the entry script's language.

### What security measures are applied uniformly across platforms?

All platforms execute `case-guard.*` scripts after initialization, which enforce an `auth.status=granted` barrier as specified in [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) (line 11). This authentication check prevents unauthorized workflow actions and applies consistently whether the entry point is PowerShell or Bash, ensuring security policy uniformity across operating systems.

### Can I add support for additional operating systems to reverse-skill?

Yes, the architecture supports adding new platforms by implementing a thin wrapper script that forwards arguments to the shared logic. Since only the entry points are platform-specific, you can create a new `master-route.*` script for an additional OS (such as zsh or fish) that parses the standard CLI options and delegates to the existing case initialization and routing infrastructure.