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

> Migrate the reverse-skill workflow to a new machine. Clone the repo, run the refresh-tool-index script, and perform a smoke test to rebuild your tool index and ensure a smooth transition.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) | [`kali/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md):

```bash

# Linux or macOS

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

```

```powershell

# Windows (PowerShell)

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

```

```bash

# 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:

```bash

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

```

### 4. Verify the Workflow

Confirm routing and index consistency with the smoke test suite:

```bash

# Linux/macOS

bash skills/scripts/smoke.ps1

```

```powershell

# Windows

powershell -File skills/scripts/smoke.ps1

```

For full routing validation, run:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) and [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) | Kali-specific path adjustments before delegation |
| [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) | Capability installer for Linux/macOS |
| `skills/scripts/bootstrap-reverse.ps1` | Capability installer for Windows |
| [`kali/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-reverse.sh) | Kali-optimized bootstrap with pre-installed tool awareness |
| [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) | Linux-specific tool path conventions |
| [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) | macOS-specific considerations (e.g., Xcode CLI tools) |
| [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.