How to Migrate the reverse-skill Workflow to a New Machine and Refresh the Tool Index

Clone the repository on the new machine, run the platform-specific refresh-tool-index script to rebuild the local tool index, then verify with a smoke test.

Migrating the reverse-skill workflow requires rebuilding the tool index—a machine-local cache that maps available utilities to their system paths. This index is intentionally git-ignored and must be regenerated on each host. This guide covers the complete migration process using scripts from zhaoxuya520/reverse-skill.

Understanding the Tool Index System

The tool index serves as the workflow's discovery layer. It scans for installed capabilities—including MCP servers, reverse-engineering binaries, and platform-specific utilities—and writes a structured status table to skills/tool-index.md plus a JSON cache for programmatic access.

Because paths and availability differ across machines, the index is not portable. The repository provides three platform-specific refresh scripts that share identical detection logic:

Platform	Refresh Script	Bootstrap Script
Generic Linux / macOS	skills/scripts/refresh-tool-index.sh	skills/scripts/bootstrap-reverse.sh
Windows PowerShell	skills/scripts/refresh-tool-index.ps1	skills/scripts/bootstrap-reverse.ps1
Kali Linux	kali/scripts/refresh-tool-index.sh	kali/scripts/bootstrap-reverse.sh

The shell scripts are thin wrappers around the PowerShell implementation, ensuring behavior parity across operating systems.

Step-by-Step Migration Process

1. Clone the Repository

Download the workflow to your new machine:

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

2. Run the Refresh-Tool-Index Script

Execute the script matching your platform to generate skills/tool-index.md:

# Linux or macOS

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

# Windows (PowerShell)

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

# Kali Linux

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

Each script probes the system for supported tools, checks version compatibility, and updates the index with checkmarks (✓) and paths.

3. Bootstrap Additional Capabilities (Optional)

If your task requires tools not yet installed, run the platform bootstrap script:

# Linux/macOS example

bash skills/scripts/bootstrap-reverse.sh --install ghidra radare2

After installing any new capability, re-run the refresh script to update the index:

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

4. Verify the Workflow

Confirm routing and index consistency with the smoke test suite:

# Linux/macOS

bash skills/scripts/smoke.ps1

# Windows

powershell -File skills/scripts/smoke.ps1

For full routing validation, run:

bash skills/scripts/test-routing.ps1  # or .ps1 variant on Windows

Successful completion indicates the tool index is synchronized and the workflow is operational.

Keeping the Index Current

Any change to system tools—installation, upgrade, or removal—requires index refresh. The detection logic in skills/scripts/refresh-tool-index.ps1 (and its shell wrappers) re-evaluates:

• MCP server availability and response schemas
• Binary utilities in $PATH (e.g., objdump, gdb, lldb)
• Platform extensions documented in docs/platforms/linux.md and docs/platforms/macos.md

Run the refresh script after every environment modification to maintain accurate routing.

Key Source Files

The following files implement the migration and refresh workflow in zhaoxuya520/reverse-skill:

Path	Function
skills/scripts/refresh-tool-index.sh	POSIX wrapper invoking PowerShell detection core
skills/scripts/refresh-tool-index.ps1	Primary detection engine; writes Markdown and JSON index
kali/scripts/refresh-tool-index.sh	Kali-specific path adjustments before delegation
skills/scripts/bootstrap-reverse.sh	Capability installer for Linux/macOS
skills/scripts/bootstrap-reverse.ps1	Capability installer for Windows
kali/scripts/bootstrap-reverse.sh	Kali-optimized bootstrap with pre-installed tool awareness
docs/platforms/linux.md	Linux-specific tool path conventions
docs/platforms/macos.md	macOS-specific considerations (e.g., Xcode CLI tools)
README.md	Quick-start matrix and troubleshooting entry points

Summary

• Tool index is machine-local—regenerate it on every new host via platform-specific scripts
• Three refresh entry points cover Windows, generic Unix, and Kali Linux with unified detection logic
• Bootstrap scripts install missing capabilities; refresh again to capture changes
• Smoke tests validate that routing and index are synchronized before production use

Frequently Asked Questions

What happens if I skip the refresh-tool-index step?

The workflow will fail to locate tools or route requests correctly. The index provides the mapping layer between abstract capability names and concrete system paths. Without it, scripts error with "capability not found" or invoke incorrect binaries.

Can I copy the tool-index.md file from another machine?

No. The index contains absolute paths and version strings specific to the source machine. Copying it produces broken references. Always regenerate using the native refresh script.

How do I add a custom tool to the index?

Install the tool to a directory in $PATH (Linux/macOS) or $env:PATH (Windows), then re-run the refresh script. The detection engine scans standard locations and updates the index automatically. For non-standard paths, modify the AdditionalPaths array in skills/scripts/refresh-tool-index.ps1 before execution.

Does the refresh script modify system packages?

No. The refresh scripts are read-only inspectors. They query existing tools without installation or removal. Use the separate bootstrap-reverse scripts to alter system state.

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