What Is `tool-index.md` and How Does It Work in the reverse-skill Repository

The tool-index.md file is an auto-generated, machine-specific catalogue that serves as the single source of truth for all security and reverse-engineering tools available on the host, enabling safe tool discovery, path verification, and capability gating across the reverse-skill workflow.

In the zhaoxuya520/reverse-skill repository, tool-index.md eliminates hard-coded assumptions about tool locations by dynamically inventorying the host environment. This markdown file is referenced by skill modules and routing logic to verify that external binaries—such as IDA Pro, radare2, Ghidra, and Frida—are present and accessible before execution begins.

Auto-Generated Tool Discovery and Registration

Unlike static documentation, tool-index.md is git-ignored and produced on-demand by helper scripts that scan the host system. The repository only ships a template file, skills/tool-index.md.template, which defines the schema for the generated output.

How the Index Is Built

Two platform-specific scripts handle the generation:

• Linux/macOS: skills/scripts/refresh-tool-index.sh
• Windows: skills/scripts/refresh-tool-index.ps1

These scripts probe the host for installed utilities, capture absolute executable paths, detect versions, and record installation sources. They output both a human-readable markdown file and a machine-parseable JSON companion (tool-index.json).

What the Index Contains

The generated skills/tool-index.md contains a master table with the following columns:

• Tool: The binary name (e.g., r2, idapro, nmap)
• Skill Module: The owning skill directory (e.g., reverse-engineering, radare2)
• Purpose: Brief description of the tool's function
• Available: Availability indicator (✓, ✗, or —)
• Path: Absolute path to the executable (e.g., /usr/local/bin/r2)
• Version: Detected version string (e.g., 5.9.0)
• Source: Installation origin (e.g., github-release-zip, apt, brew)
• Script Reference: The wrapper script that invokes the tool

Additionally, a secondary Capability Status sub-table tracks MCP (module-control-plane) registration and service-online detection status for tools that expose network interfaces or daemon processes.

Core Functions in the reverse-skill Workflow

The tool-index.md file acts as a centralized gatekeeper that prevents execution failures due to missing dependencies. Throughout the repository, skill modules explicitly defer to this index before invoking any external binary.

Path Verification and Availability Checking

Every skill module that depends on external tooling includes a mandatory verification step. In files such as skills/radare2/SKILL.md and skills/reverse-engineering/SKILL.md, the workflow directs users to:

NEXT: 读取 `../tool-index.md`，校验工具可用性和实际路径

This instruction ensures that automation scripts and human operators check the Available column and Path field rather than guessing binary locations. For example, instead of assuming /usr/bin/r2, a script consults the index to confirm the actual location is /opt/radare2/bin/r2 and that the binary reports version 5.9.0.

Capability Gating for Skill Routing

The skills/routing.md file implements conditional logic based on the index contents. Routing scripts parse the markdown to determine whether a skill branch can execute or must be skipped. This prevents workflow failures in environments where specific commercial tools (e.g., IDA Pro) are unavailable but open-source alternatives (e.g., Ghidra) are present.

Working with tool-index.md in Practice

Generating and consuming the index follows a straightforward pattern that integrates into CI/CD pipelines and local development workflows.

Generating the Index on First Run

Windows PowerShell:

# Run the refresh script to create skills/tool-index.md and skills/tool-index.json

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

Linux/macOS Bash:

# Generate the index on Unix-like systems

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

Querying Tool Availability

After generation, inspect specific entries using standard shell tools:

# Check whether radare2 is available and view its metadata

grep -i "r2" skills/tool-index.md

Example output excerpt:

| r2 | reverse-engineering | CLI analysis | ✓ | /usr/local/bin/r2 | 5.9.0 | github-release-zip |

Consuming the Index in Automation Scripts

Skill wrappers parse the index to load tool paths into variables before execution:

# Load tool-index into a hashtable (PowerShell)

$toolIndex = Import-Csv "$PSScriptRoot\..\tool-index.md" -Delimiter '|'

# Locate IDA Pro entry

$ida = $toolIndex | Where-Object { $_.Tool -eq 'idapro' }

if ($ida.Available -eq '✓') {
    & $ida.Path /path/to/binary
} else {
    Write-Warning "IDA Pro not installed – aborting skill branch."
}

For Bash-based skills, conditional routing uses pattern matching:

# Verify nmap presence before network scanning

if grep -q "| nmap | pentest-tools | network scanner | ✓ |" skills/tool-index.md; then
    echo "Nmap is present – continuing with network scan"
else
    echo "Nmap missing – skipping network reconnaissance branch"
fi

Summary

• tool-index.md is auto-generated by refresh-tool-index.sh and refresh-tool-index.ps1, rendering it a dynamic, host-specific asset rather than static documentation.
• It provides discovery and verification by listing absolute executable paths, versions, and availability statuses for every tool in the reverse-engineering arsenal.
• It serves as a capability gate, enabling routing logic in skills/routing.md and individual SKILL files to skip branches where required binaries are absent.
• The file acts as an audit trail, creating a reproducible record of the tool environment for evidence gathering and compliance review.

Frequently Asked Questions

Why is tool-index.md excluded from version control?

Because tool-index.md contains absolute paths and version strings specific to the host where the repository is executed, it is listed in .gitignore. The repository instead tracks skills/tool-index.md.template, which defines the schema and instructions for generating the actual index on each machine.

How do skill modules reference the index during execution?

Skill modules include a mandatory "NEXT" step in their markdown files (e.g., skills/radare2/SKILL.md) that instructs the user or automation script to read ../tool-index.md and verify the tool's availability and path before proceeding. This ensures no hard-coded assumptions about binary locations exist in the workflow logic.

What information does the Capability Status sub-table track?

The Capability Status section records MCP (module-control-plane) registration states and service-online detection results. This allows the reverse-skill system to determine not only whether a tool binary exists, but whether network-exposed components or daemon processes associated with that tool are currently operational.

Can tool-index.md be used in automated CI/CD pipelines?

Yes. The refresh-tool-index scripts generate both the markdown file and a corresponding tool-index.json, which can be parsed by CI/CD systems to verify that required security tools are present before running tests or deployment scripts, ensuring reproducible build environments.

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