Why `refresh-tool-index` Is Necessary After Tool Installation in reverse-skill

Running refresh-tool-index updates the machine-local tool registry so the reverse-skill CLI can locate newly installed binaries without guessing paths or failing to find them.

The reverse-skill repository maintains a machine-local tool index that maps capability names to absolute filesystem paths. When you install new reverse engineering tools like radare2 or burpsuite, the CLI cannot locate these binaries until the index is regenerated. This article explains why executing the platform-specific refresh script is mandatory after every installation.

What refresh-tool-index Does to the Tool Registry

The reverse-skill system relies on skills/tool-index.md (and its JSON counterpart) as the single source of truth for tool locations. This generated registry stores resolved absolute paths for every capability, from debuggers to MCP clients.

When refresh-tool-index runs, it scans the system for known tools and populates the index with their current locations. Without this step, the CLI references stale or missing path entries that do not reflect the newly installed software.

Three Failure Modes When You Skip the Refresh

Omitting the refresh step after installation creates immediate operational problems across the reverse-skill environment.

Tools Become Unlocatable

The CLI queries tool-index.md to resolve tool paths for commands like master-route and case-init. If the index lacks the new entry, the system fails to find the tool entirely, halting execution with path resolution errors.

Unsafe Path Guessing

As documented in RULES.md at line 110, a missing or stale index triggers a fallback behavior where the system attempts to "guess" the binary location. This heuristic approach is explicitly marked as unsafe and complicates debugging across different environments.

Cross-Platform Inconsistency

Many scripts and LLM agents read the index to obtain consistent references across Windows, Linux/macOS, and Kali distributions. A stale index causes these clients to exhibit inconsistent behavior, where the same command succeeds on one platform but fails on another due to differing path conventions.

How to Run refresh-tool-index on Each Platform

The repository provides platform-specific scripts to regenerate the index. Execute the appropriate command immediately after installing any new package.

On Windows:

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

On Linux or macOS:

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

On Kali Linux:

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

Complete workflow example after installing radare2:

# Install the tool

sudo apt-get install radare2

# Refresh the index so reverse-skill recognizes the binary

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

# Verify the entry exists

grep -i r2 skills/tool-index.md

Repository Policy and Source Files

The requirement to run refresh-tool-index is enforced through repository documentation and implementation.

RULES.md (line 110) mandates: "After ANY new tool installation, MUST run the platform-appropriate refresh script to update paths in tool-index.md."

README.md (lines 119-121) lists the specific refresh commands for each supported platform.

The implementation resides in:

• skills/scripts/refresh-tool-index.ps1 – PowerShell wrapper for Windows environments
• skills/scripts/refresh-tool-index.sh – Bash implementation for Unix-like systems
• kali/scripts/refresh-tool-index.sh – Kali-specific variant for penetration testing distributions

Summary

• refresh-tool-index synchronizes the local environment with the reverse-skill tool registry by scanning for binaries and writing paths to skills/tool-index.md.
• Skipping the refresh causes tool lookup failures, unsafe path guessing, and inconsistent behavior across Windows, Linux, and Kali platforms.
• Repository rules in RULES.md explicitly require running the refresh script after every new tool installation to maintain operational safety.
• Platform-specific scripts in skills/scripts/ and kali/scripts/ handle the regeneration process without modifying system-wide configurations.

Frequently Asked Questions

What happens if I run reverse-skill commands without refreshing the index?

The CLI will either fail to locate the newly installed tool or fall back to guessing its path, which RULES.md identifies as an unsafe operation that increases debugging difficulty and breaks script reliability.

Does refresh-tool-index modify system-wide configurations?

No. The script only writes to the machine-local files skills/tool-index.md and tool-index.json within the reverse-skill directory. It does not alter system PATH variables or global package manager settings.

How often should I run refresh-tool-index?

You must run it after every new tool installation, regardless of whether you used apt, pipx, npm, or manual binary placement. This ensures the index remains accurate as your tooling environment evolves.

Can I manually edit tool-index.md instead of running the script?

Manual edits are discouraged. The refresh scripts perform systematic scans and validation to ensure paths are absolute and correctly formatted. Manual modifications risk introducing path errors that break cross-platform compatibility for master-route, case-init, and other dependent scripts.

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