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

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 that maps a user-task hint to a concrete skill module.
• Tool index — 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 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, timeline.md, and 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.

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:

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:

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 (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 skills/scripts/refresh-tool-index.sh

This script writes the index to skills/tool-index.json and 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 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 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:

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 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 skills/scripts/test-routing.sh

This verifies that every routing rule in 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	Overview and quick-start instructions
docs/platforms/linux.md	Detailed Linux setup, package list, validation checklist
skills/config/routing.json	Central 43-entry routing rules
skills/scripts/refresh-tool-index.sh	Detects local tools, rewrites tool-index.*
skills/scripts/bootstrap-reverse.sh	Installs missing utilities, registers MCP endpoints
skills/scripts/test-routing.sh	Runs the 173-case routing regression suite
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:

#!/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.
• The bootstrap script (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 to confirm routing resolves correctly.
• The architecture is platform-neutral, so the same core 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 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) 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 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, 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.

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