How to Execute reverse-skill on Linux or macOS: Complete Setup Guide

Execute reverse-skill on Linux or macOS by cloning the repository, running the bootstrap script to install dependencies, refreshing the tool index, and invoking the master router with a natural language hint.

The reverse-skill project is a platform-agnostic skills router that automates security workflows like APK analysis and binary reverse engineering. To execute reverse-skill on Linux or macOS, you interact with shell scripts that detect your environment, install required tools, and route tasks to the appropriate skill modules according to the source code in zhaoxuya520/reverse-skill.

Core Architecture Overview

Understanding the architecture helps you execute reverse-skill effectively on Unix-like systems.

Routing Configuration

The single source of truth for task distribution resides in [/skills/config/routing.json](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This JSON file maps 43 distinct routes across 173 benchmark cases, connecting natural language hints to specific skill modules.

Master Router Script

The [/skills/scripts/master-route.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) serves as the fast entry point for Linux and macOS users. It parses your hint, selects the primary skill using the routing rules, and generates a route-scope.md scaffold in a timestamped work directory.

Bootstrap and Environment Setup

The [/skills/scripts/bootstrap-reverse.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) handles capability detection and installation. It searches for existing tools (Jadx, Frida, radare2) and installs missing dependencies via package managers, pipx, or GitHub releases. The script also supports optional MCP (Model-Client-Protocol) server registration for AI agents.

Tool Index Management

The [/skills/scripts/refresh-tool-index.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) scans your system to update [/skills/tool-index.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and its JSON counterpart. This auto-generated inventory tells the router which capabilities are available before executing a task.

Prerequisites and Platform-Specific Setup

Before you execute reverse-skill, ensure your system meets the baseline requirements documented in the platform-specific guides.

Linux Requirements

For Debian-based distributions, the [/docs/platforms/linux.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) specifies packages including git, curl, Java 17, Node.js, Python 3, and security tools like binwalk and hashcat.

macOS Requirements

macOS users should consult [/docs/platforms/macos.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) for Homebrew-based installation commands. The platform supports both Intel and Apple Silicon architectures through universal binaries or Rosetta compatibility layers.

Step-by-Step Execution Guide

Follow these five steps to execute reverse-skill on Linux or macOS.

1. Clone the Repository

Fetch the complete source tree including scripts and routing configuration.

git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill

2. Install System Prerequisites

On Ubuntu or Debian, install the baseline toolchain:

sudo apt update && sudo apt install -y \
  git curl wget ca-certificates unzip tar jq \
  python3 python3-venv python3-pip pipx \
  openjdk-17-jdk nodejs npm \
  graphviz plantuml nmap sqlmap ffuf hashcat binwalk

On macOS, install via Homebrew (refer to the macOS platform docs for the complete brew install list):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git curl wget unzip jq python node openjdk jadx apktool radare2

3. Bootstrap Required Capabilities

Run the bootstrap script to detect and install security tools. This example installs Jadx, apktool, and Frida:

bash skills/scripts/bootstrap-reverse.sh jadx apktool frida

To register an MCP server for a specific AI client, add the --mcp-host flag:

bash skills/scripts/bootstrap-reverse.sh jshookmcp --mcp-host=codex
bash skills/scripts/bootstrap-reverse.sh anything-analyzer --mcp-host=claude

4. Refresh the Tool Index

Update the local inventory so the router recognizes available tools:

bash skills/scripts/refresh-tool-index.sh

This writes the current state to /skills/tool-index.md and /skills/tool-index.json.

5. Execute the Master Router

Invoke the router with a natural language hint describing your reverse engineering task:

bash skills/scripts/master-route.sh --hint "Analyze a suspicious Android APK"

The script creates a working directory like work/master-route-20260824-152300/ containing route-scope.md. Open this file to identify the PRIMARY skill path, then execute the skill-specific script. For example:

bash skills/apk-reverse/scripts/run-apk.sh --apk myapp.apk

Summary

To successfully execute reverse-skill on Linux or macOS, remember these key steps:

• Clone the repository to access /skills/scripts/ and configuration files
• Bootstrap your environment using [bootstrap-reverse.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) to install Jadx, Frida, radare2, and other tools
• Index your tools with [refresh-tool-index.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) so the router knows your capabilities
• Route tasks via [master-route.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) which reads [/skills/config/routing.json](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to select the appropriate skill
• Execute the specific skill script listed in the generated route-scope.md file

Frequently Asked Questions

What are the minimum system requirements to execute reverse-skill on Linux?

You need a Unix-like environment with bash, git, curl, Python 3, and Java 17. The [/docs/platforms/linux.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) file provides distribution-specific package lists for Ubuntu, Debian, and RHEL-based systems. The bootstrap script handles detection of optional security tools like apktool and binwalk.

How does the master router determine which skill module to execute?

The [master-route.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) script parses your hint against [/skills/config/routing.json](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), which contains 43 predefined routes mapping keywords to skill directories. The router creates a route-scope.md file pointing to the PRIMARY skill path, ensuring you run the correct module for tasks like APK analysis or CTF exploitation.

Can I run reverse-skill on macOS with Apple Silicon (M1/M2)?

Yes, the platform supports Apple Silicon. The [/docs/platforms/macos.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) documentation includes Homebrew commands that install universal binaries or x86 versions under Rosetta 2 when necessary. The bootstrap script detects your architecture and adjusts tool installation paths accordingly.

Is it possible to use reverse-skill without registering an MCP server?

Absolutely. MCP registration via [bootstrap-reverse.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) is optional and only required if you want AI agents like Claude Code or Codex to invoke the tools automatically. You can execute reverse-skill manually from the shell without the --mcp-host flag and follow the generated route-scope.md instructions yourself.

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