# How to Set Up Reverse-Skill for Linux: Complete Installation Guide

> Learn how to set up reverse-skill for Linux with this complete installation guide. Clone the repo, install dependencies, and configure your environment for effective tool discovery.

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

---

**To set up reverse-skill for Linux, clone the repository from `zhaoxuya520/reverse-skill`, install system prerequisites via your package manager, run `bash skills/scripts/refresh-tool-index.sh` to discover local tools, then execute `bash skills/scripts/bootstrap-reverse.sh` with the target tools as arguments, and finally validate the environment with `bash skills/scripts/test-routing.sh`.**

Reverse-skill is an open-source security-skill router that maps user task hints to concrete skill modules through a central routing engine. The core architecture relies on a JSON-based routing configuration, a tool-discovery index, and platform-agnostic bootstrap scripts — all of which work seamlessly on Linux. This guide walks through every step to set up reverse-skill for Linux, from system prerequisites to regression validation, using the exact scripts and commands from the source repository.

## Understanding the Reverse-Skill Architecture on Linux

The reverse-skill project, hosted at `https://github.com/zhaoxuya520/reverse-skill`, is built around four core components that are platform-neutral by design:

- **Routing core** — a single source of truth in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) that maps a user-task hint to a concrete skill module.
- **Tool index** — [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) scans the host for installed binaries and writes results to `skills/tool-index.{md,json}`.
- **Bootstrap layer** — [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) installs missing tools (via `apt`, `pipx`, `curl`, or source builds) and registers MCP endpoints for AI clients.
- **Case workflow** — `skills/scripts/case-init.*` creates per-case directories with [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md), enforcing an **auth gate** before active operations.

The Linux-specific scripts only adapt the package manager, path layout, and optional MCP registration. Everything else is platform-neutral.

### Prerequisites Before You Begin

Before installing anything, ensure your Linux system can run Java, Node, Python, and common security utilities. On apt-based distributions (Ubuntu, Debian), the full package list is available in the official distribution documentation at [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md).

## Step 1: Install System Prerequisites on Linux

Run the following commands to install all required system packages. This covers the core runtimes plus standard reverse-engineering and security tools:

```bash
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

```

These packages provide the base environment needed by the bootstrap script and the routing engine. If you're on a non-apt distribution, simply adapt the package names to your package manager.

## Step 2: Clone the Repository

Navigate to your workspace and clone the full source tree:

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

```

This gives you direct access to all folders including `skills/config/`, which contains [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) (the central 43-entry routing rules file), and `docs/` where the Linux-specific platform guide lives.

## Step 3: Refresh the Tool Index

The tool index is a machine-generated inventory of all discoverable tools on your host. Run the dedicated scanning script to populate it:

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

```

This script writes the index to [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) and [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) after scanning your system for installed binaries. The tool index drives conditional execution of scripts, so keeping it fresh is critical for correct routing behavior.

## Step 4: Bootstrap Required Capabilities

Use the bootstrap script to install or register tools that are missing on your host. The script accepts tool names as arguments and knows how to fetch each one via `apt`, `pipx`, or source builds.

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

```

Replace these tool names with whatever your workflow requires. The repository officially supports tools like `jadx`, `apktool`, and `frida`, but the bootstrap script is extensible — you can add capabilities such as `ida-pro` or `burpsuite` for more advanced security workflows.

### Registering MCP Servers (Optional)

If you need to connect reverse-skill to a specific AI client, you can register a ready-to-use model endpoint through the same bootstrap script:

```bash
bash skills/scripts/bootstrap-reverse.sh jshookmcp --mcp-host=codex

```

This optional step is only relevant when you want the router to talk to an AI assistant directly.

## Step 5: Validate Your Environment

After bootstrapping, verify the critical runtime versions. Use the one-liner below, which includes safety checks with `|| true` so the summary doesn't fail if a particular tool isn't installed:

```bash
java -version
python3 --version
node -v
jadx --version || true
frida --version || true
r2 -v || true

```

Whether the output matches your expectations, re-run the tool index to capture any new tools installed by the bootstrap step:

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

```

## Step 6: Run the Routing Regression Suite

The final gate is running the 173-step routing validation suite. On Linux, call the appropriate shell script:

```bash
bash skills/scripts/test-routing.sh

```

This verifies that every routing rule in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) still resolves to the expected primary skill. If any rule fails, re-check your tool index and bootstrap coverage.

## Key Files Reference

The Linux setup relies on these files in the repository:

| File | Purpose |
|------|---------|
| [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) | Overview and quick-start instructions |
| [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) | Detailed Linux setup, package list, validation checklist |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central 43-entry routing rules |
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Detects local tools, rewrites `tool-index.*` |
| [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) | Installs missing utilities, registers MCP endpoints |
| [`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh) | Runs the 173-case routing regression suite |
| [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) | Repository-wide, platform-neutral usage instructions |

## Complete Setup Script

Here's a single bash script that runs the entire setup end-to-end on a fresh Linux machine:

```bash
#!/usr/bin/env bash
set -euo pipefail

# 1. Install system packages

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

# 2. Clone and enter the repo

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

# 3. Discover existing tools

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

# 4. Bootstrap common reverse-engineering tools

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

# 5. Verify versions

java -version
python3 --version
node -v
jadx --version || echo "jadx not installed"
frida --version || echo "frida not installed"
r2 -v || echo "radare2 not installed"

# 6. Run the routing regression

bash skills/scripts/test-routing.sh

echo "reverse-skill setup complete on Linux"

```

## Summary

- **Set up reverse-skill for Linux** by installing system packages, cloning the repo, and refreshing the tool index with [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh).
- **The bootstrap script** ([`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh)) handles tool installation and MCP registration — no manual configuration needed for most workflows.
- **Validation is mandatory**: run the version checks and the 173-case [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) to confirm routing resolves correctly.
- **The architecture is platform-neutral**, so the same core [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), scripts, and case workflow work across Windows, macOS, and Linux.

## Frequently Asked Questions

### What is the reverse-skill routing engine?

Reverse-skill's routing engine is a configuration-driven module in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) that maps a user-task hint to a concrete skill module, offloading installation logic to a per-platform bootstrap context. The mapping happens through a set of internal rules that resolve it to a specific tool, tool index entry, or workflow markdown file.

### Which Linux distributions are supported?

Any modern Linux distribution that supports `bash`, `curl`, and the Java/Node/Python runtimes can work. The primary tested targets are apt-based distributions like Ubuntu and Debian — the official docs ([`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md)) provide the exact package lists for those systems.

### How do I add a custom tool that isn't in the bootstrap list?

You can extend [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) by adding the tool name to bootstrap logic or bundling its installation command. The script is designed to be extended — the routing and index layers will pick up any new tools as soon as they're installed on your system.

### Is reverse-skill Linux-only?

No — reverse-skill is **platform-neutral**. The same [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), tool index, and bootstrap logic work on Windows, macOS, and Linux. Only the package manager, path layout, and optional MCP registration differ between platforms, which is why the repository ships per-platform documentation.