# Why `refresh-tool-index` Is Necessary After Tool Installation in reverse-skill > Learn why refresh-tool-index is crucial after installing tools in reverse-skill. It updates the tool registry, ensuring the CLI finds new binaries without errors. Boost your workflow now! - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: how-to-guide - Published: 2026-08-21 --- **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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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 powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1 ``` On Linux or macOS: ```bash bash skills/scripts/refresh-tool-index.sh ``` On Kali Linux: ```bash bash kali/scripts/refresh-tool-index.sh ``` Complete workflow example after installing `radare2`: ```bash # 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** (line 110) mandates: "After ANY new tool installation, **MUST** run the platform-appropriate refresh script to update paths in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)." **[`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) – Bash implementation for Unix-like systems - [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.