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

The reverse-skill repository maintains a machine-local tool index through platform-specific refresh scripts that auto-generate tool-index.md and 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 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 (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 is git-ignored because it contains machine-specific absolute paths. When you first clone the repository, neither tool-index.md nor 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 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 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 provides structured data for automated tools and AI agents. Each entry follows this schema:

{
  "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, lines 15-16) include a "NEXT" step that reads 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:

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

# Linux/macOS

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

This generates both skills/tool-index.md and 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 and refresh-tool-index.ps1) that detect but do not install tools.
• Generated files (tool-index.md and 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 and 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 and 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 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 (lines 15-16) checks 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 mandates this check, ensuring all agents read from the index rather than guessing tool locations.

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