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

> Discover the crucial role of tool-index.md in the reverse-skill repository. This file ensures deterministic execution by mapping binaries, acting as your single source of truth for tool availability and paths.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-27

---

**The [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) for easy parsing by skill scripts. While [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) to resolve tool paths before execution.

### Routing Logic Dependencies

According to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), all routing logic must reference [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) before invoking any external tool. The [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) diagram positions [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash

# Linux/macOS example

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

```

This generates two files:
- [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) – Human-readable markdown table
- [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) – Machine-readable JSON version

### Querying Tool Paths Programmatically

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

```python
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) and [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) files explicitly instruct users to generate [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md), the routing layer defined in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) triggers the platform-specific refresh script to attempt installation or registration. After the script completes, [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.