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

reverse-skill isolates OS differences at the entry-point level by providing native shell wrappers—master-route.ps1 for Windows and 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 (lines 13 and 86) and 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 (line 19) and 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. This Bash implementation mirrors the PowerShell entry point's CLI parsing logic and argument validation. According to the source analysis of 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 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 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 (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 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:

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

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

# 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: Linux/macOS/Kali entry point written in Bash that implements the same CLI contract
• 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 and case-guard.ps1: Security gate scripts that enforce auth.status=granted validation before allowing workflow continuation
• config/routing.json: Central routing contract that maps hints to primary skills, shared across all platforms
• 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 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 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. 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 (lines 13 and 86) and 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 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 (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.

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