# How the Tool Index is Maintained in reverse-skill: A Complete Technical Guide

> Discover how reverse-skill maintains its tool index using platform-specific scripts. Learn about auto-generated tool-index.md and tool-index.json files for security utility documentation.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-09-02

---

**The reverse-skill repository maintains a machine-local tool index through platform-specific refresh scripts that auto-generate [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) and [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) files, documenting the availability, absolute paths, and versions of all external security utilities without installing them.**

The reverse-skill project relies on a dynamic indexing system to track external reverse-engineering and security tools across different operating systems. This tool index serves as the single source of truth for tool availability, preventing path-guessing errors and ensuring reproducible workflows when executing skills.

## How the Tool Index is Generated

The index is **auto-generated** by platform-specific refresh scripts located in `skills/scripts/`. These scripts probe the local environment to discover installed tools but explicitly **never install** anything. They check for command existence using `command -v`, scan known binary locations, and fall back to common installation paths.

### Platform-Specific Refresh Scripts

Two scripts handle index generation across operating systems:

- **Linux/macOS**: [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) performs detection by querying the system PATH and known directories, then writes the results to both Markdown and JSON formats.
- **Windows**: `skills/scripts/refresh-tool-index.ps1` (referenced in `skills/tool-index.md.template`) provides equivalent functionality for PowerShell environments.

According to the source in [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (lines 46-55), each detected tool entry records:

- **Tool**: The command identifier
- **Skill**: Associated skill directory
- **Purpose**: Functional description
- **Available**: Yes/no status
- **Path**: Resolved absolute path or empty
- **Version**: Tool version string
- **Source**: Detection method (command, path, etc.)
- **Install hint**: Platform-specific installation guidance (e.g., `apt install …`, `brew install …`)

### Template and Git-Ignored Output

The `skills/tool-index.md.template` file contains a warning that the real [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is **git-ignored** because it contains machine-specific absolute paths. When you first clone the repository, neither [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) nor [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) exists. You must run the appropriate refresh script for your platform to generate these files in the `skills/` directory.

## Structure and Format of the Index

The reverse-skill tool index is maintained in two parallel formats to support both human readability and programmatic consumption.

### Markdown Documentation

The generated [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) begins with a header describing the generation timestamp, platform, and script source. The core content is a markdown table with the columns defined in the refresh script: Tool, Skill, Purpose, Available, Path, Version, Source, and Install hint.

When a [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) is present, the script appends a "Capability status view" section that ties tool availability to MCP registration status.

### JSON Machine Consumption

The accompanying [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) provides structured data for automated tools and AI agents. Each entry follows this schema:

```json
{
  "name": "r2",
  "skill": "radare2",
  "purpose": "radare2 CLI analysis",
  "available": true,
  "path": "/usr/local/bin/r2",
  "version": "radare2 5.8.0",
  "source": "command",
  "install_hint": "linux:radare2 → GitHub/source preferred; apt if available"
}

```

## Integration with Skill Execution

Every component in the reverse-skill ecosystem references the tool index before executing external commands, ensuring consistent behavior across different environments.

### Pre-Execution Verification

Individual skill files (such as [`skills/radare2/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/radare2/SKILL.md), lines 15-16) include a "NEXT" step that reads [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) to verify required tools exist before proceeding. Skills check for utilities like radare2, Ghidra, Frida, and other reverse-engineering frameworks by querying the index rather than assuming standard locations.

You can verify tool availability programmatically using shell commands:

```bash
if grep -q '^r2[[:space:]]|.*|yes|' skills/tool-index.md; then
  echo "radare2 is ready"
else
  echo "radare2 missing – run refresh-tool-index.sh"
fi

```

### Routing Policy Enforcement

The [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) file (lines 30-31) explicitly mandates the "never guess a path; always read tool-index.md" policy. This rule prevents agents and scripts from assuming tool locations, which could lead to execution errors or security risks. The [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) entry point reinforces this by listing the tool index as a required generated artifact before any skill execution.

## Refresh Workflow and Maintenance

Maintaining an accurate tool index requires specific workflow steps when setting up or modifying your environment.

**First-time setup**: After cloning the repository, run the platform-appropriate script before executing any skills:

```bash

# Linux/macOS

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

```

This generates both [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json).

**After installing new tools**: Re-run the refresh script to update the index with new binary locations and version strings. The scripts overwrite the existing files completely, ensuring no stale entries persist.

**Continuous validation**: Skills should check the index at runtime rather than caching tool paths, as the JSON file may update independently of skill execution.

## Summary

- The reverse-skill tool index is maintained through platform-specific scripts ([`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) and `refresh-tool-index.ps1`) that detect but do not install tools.
- Generated files ([`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) and [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json)) are machine-specific and git-ignored, created anew for each environment.
- The index captures absolute paths, version strings, availability status, and installation hints for every external dependency.
- All skills must verify tool availability against the index before execution, as enforced by [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md).
- Run the refresh script after initial clone and whenever installing new security tools to maintain accurate path resolution.

## Frequently Asked Questions

### How do I regenerate the tool index after installing new software?

Run the platform-specific refresh script located in `skills/scripts/`. On Linux or macOS, execute `bash skills/scripts/refresh-tool-index.sh`. On Windows, run `skills/scripts/refresh-tool-index.ps1` in PowerShell. These scripts will overwrite [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) with current detection results, including newly installed binaries and their absolute paths.

### Why is the tool-index.md file git-ignored?

The [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) file contains machine-specific absolute paths that vary between development environments, containers, and host systems. The `skills/tool-index.md.template` explicitly warns that this file must not be committed to version control. Each machine generates its own index locally to reflect its unique filesystem layout and installed tool versions.

### Can the refresh scripts install missing tools for me?

No. The refresh scripts in `skills/scripts/` are designed solely for discovery and documentation. They probe for existing binaries using `command -v` and known path fallbacks, then record availability status and installation hints. They never execute package managers or modify the system. You must install tools manually using the provided hints (e.g., `apt install`, `brew install`, or manual downloads) before refreshing the index.

### How do skills actually use the tool index during execution?

Skills reference the index to verify tool availability before attempting execution. For example, [`skills/radare2/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/radare2/SKILL.md) (lines 15-16) checks [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) to confirm radare2 is available and to retrieve its absolute path. This prevents "command not found" errors and eliminates the need for hardcoded paths. The [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) mandates this check, ensuring all agents read from the index rather than guessing tool locations.