Understanding the Role of the tool-index.md File in reverse-skill

The tool-index.md file serves as the single source of truth for tool availability and absolute paths in the reverse-skill repository, enabling deterministic execution across different environments by dynamically mapping installed binaries to their system locations.

The reverse-skill repository implements a robust skill routing system for reverse engineering and penetration testing workflows. At the center of this architecture lies skills/tool-index.md, a machine-local configuration file that eliminates hard-coded paths and ensures every skill module can reliably locate external binaries like radare2, ghidra, and jadx.

Core Responsibilities of tool-index.md

The skills/tool-index.md file fulfills four critical functions that enable portable, reproducible reverse engineering workflows.

Tool Availability Verification

Each entry in tool-index.md records a simple yes or no flag indicating whether the tool was detected on the host machine during the last scan. This prevents skill scripts from attempting to invoke missing binaries and allows the routing layer to make informed decisions about which tools to use for a given task.

Absolute Path Resolution

Rather than relying on environment variables or $PATH guesses, the file stores the absolute path to each executable. For example, it records D:\tools\jadx\bin\jadx.bat on Windows or /usr/local/bin/r2 on Unix systems. This eliminates "command not found" errors caused by shell configuration differences between developer machines and CI runners.

Version and Metadata Tracking

The index captures version strings, installation methods, and verification commands for every registered tool. This metadata ensures reproducibility across environments and allows skills to check for specific feature support based on version numbers before invoking commands.

Automated Bootstrapping Support

When a required tool is marked as unavailable, the routing layer triggers platform-specific refresh scripts to (re)install or register the missing binary. After installation completes, tool-index.md is regenerated to reflect the new state, enabling fully automated environment setup.

How tool-index.md Is Generated

Because tool-index.md is machine-local and git-ignored, every developer and CI runner must generate their own copy using the provided refresh scripts.

Cross-Platform Refresh Scripts

The repository provides platform-specific scripts that scan the host system and populate the index:

• Windows: Run powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1
• Linux/macOS: Run bash skills/scripts/refresh-tool-index.sh
• Kali Linux: Use bash kali/scripts/refresh-tool-index.sh for security-focused distributions

These scripts execute detection logic for supported tools and output both human-readable and machine-readable formats.

The JSON Counterpart for Programmatic Access

Alongside the markdown file, the refresh process generates skills/tool-index.json for easy parsing by skill scripts. While tool-index.md provides a human-readable table view, the JSON version enables direct programmatic access to tool paths and availability flags without markdown parsing overhead.

Integration with Skill Routing

The reverse-skill routing system explicitly depends on tool-index.md to resolve tool paths before execution.

Routing Logic Dependencies

According to RULES.md and MASTER-ROUTING.md, all routing logic must reference tool-index.md before invoking any external tool. The MASTER-ROUTING.md file defines the execution flow that checks the index prior to ACT (Action) steps, ensuring that only verified, available tools are invoked.

Preventing Path Resolution Failures

By centralizing path discovery in tool-index.md, the system prevents "guess-the-path" failures that commonly occur when developers hard-code paths like /usr/bin/r2 or assume tools are in $PATH. The docs/ARCHITECTURE.md diagram positions tool-index.md as a critical participant in the workflow, bridging the gap between the host environment and skill execution.

Working with tool-index.md in Practice

Interacting with the tool index involves generation, programmatic querying, and understanding its structure.

Generating Your Local Index

From the repository root, execute the appropriate refresh script for your platform:

# Linux/macOS example

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

This generates two files:

• skills/tool-index.md – Human-readable markdown table
• skills/tool-index.json – Machine-readable JSON version

Querying Tool Paths Programmatically

Skill scripts read the JSON index to retrieve absolute paths dynamically:

import toml, pathlib, json

# Load the JSON version for easy lookup

with open('skills/tool-index.json') as f:
    tool_index = json.load(f)

# Example: get the path for radare2 (r2)

r2_entry = tool_index.get('r2')
if r2_entry and r2_entry['available'] == 'yes':
    r2_path = r2_entry['path']
    # Use the absolute path to invoke radare2

    subprocess.run([r2_path, '-v'])
else:
    raise RuntimeError('radare2 not installed – run refresh-tool-index')

File Structure and Schema

The generated tool-index.md follows a consistent table schema:

Tool	Available	Version	Path
r2 (radare2)	yes	5.8.0	/usr/local/bin/r2
ghidra	yes	11.4	/opt/ghidra/ghidraRun
jadx	no	–	–

The template source at skills/tool-index.md.template explains that this file is auto-generated and should never be manually edited, directing users to run the refresh scripts instead.

Key Files Supporting the Tool Index

Several files work together to implement the tool index mechanism:

• skills/tool-index.md.template – Template explaining the file is auto-generated
• skills/tool-index.md – Generated index (git-ignored, machine-local)
• skills/tool-index.json – JSON counterpart for programmatic access
• skills/scripts/refresh-tool-index.sh – Linux/macOS generation script
• skills/scripts/refresh-tool-index.ps1 – Windows PowerShell generation script
• RULES.md – Defines tool-index.md as the single source of truth for tool availability
• MASTER-ROUTING.md – Documents routing flow that reads the index before execution
• README.md – Instructions for generating the index before first use

Summary

• tool-index.md acts as the single source of truth for tool availability and absolute paths in the reverse-skill environment.
• The file is machine-local and git-ignored, requiring each user to generate it via platform-specific refresh scripts.
• It stores absolute paths, version strings, and availability flags to eliminate hard-coded dependencies and shell configuration assumptions.
• A JSON counterpart (tool-index.json) enables programmatic access for skill scripts written in Python or other languages.
• The routing system depends on the index to make execution decisions and trigger automated bootstrapping when tools are missing.

Frequently Asked Questions

What happens if tool-index.md is missing?

Skill execution will fail with runtime errors indicating required tools are not found. The README.md and README_AI.md files explicitly instruct users to generate tool-index.md before first use by running the appropriate refresh script for their platform. Without this file, the routing layer cannot resolve absolute paths or verify availability.

Should tool-index.md be committed to git?

No. tool-index.md is git-ignored because it contains absolute paths specific to the local machine (e.g., D:\tools\... on Windows versus /opt/... on Linux). Committing it would cause path resolution failures on other machines. The repository includes skills/tool-index.md.template to document the file's purpose without including machine-specific data.

How does reverse-skill handle missing tools?

When a skill requires a tool marked as unavailable in tool-index.md, the routing layer defined in MASTER-ROUTING.md triggers the platform-specific refresh script to attempt installation or registration. After the script completes, tool-index.md is regenerated. If the tool remains unavailable, the routing layer raises an error before attempting execution, preventing cryptic "command not found" failures.

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

While possible, manual editing is strongly discouraged. The skills/tool-index.md.template explicitly states the file is auto-generated. Manual edits would be overwritten the next time refresh-tool-index.sh or refresh-tool-index.ps1 runs. If you need to register a custom tool location, modify the detection logic in the refresh scripts rather than the generated output files.

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