# Purpose of skills/tool-index.md in the reverse-skill Repository

> Discover the purpose of skills/tool-index.md in the reverse-skill repository. Learn how this auto-generated inventory ensures reproducible security tool execution across workstations.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-16

---

**[`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) is a machine-specific, auto-generated inventory that maps installed security tools to their exact paths and versions, enabling reproducible execution across different analyst workstations.**

The `reverse-skill` repository by zhaoxuya520 implements a dynamic capability discovery system centered on this file. Rather than hardcoding tool locations or assuming standard installations, the codebase uses [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) as a **canonical source of truth** that adapts to each host environment. This design prevents path-guessing errors and ensures automation scripts only invoke tools that are actually available.

## How tool-index.md Is Generated

The file is **not version-controlled**. Instead, two platform-specific scripts regenerate it on demand:

- `skills/scripts/refresh-tool-index.ps1` — PowerShell implementation for Windows environments
- [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) — Bash implementation for Linux and macOS

Both scripts scan the host system for security tools, then write results to [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) (human-readable) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) (machine-parseable). The template file at `skills/tool-index.md.template` explicitly documents this auto-generation behavior and instructs users to run the refresh scripts before use.

```powershell

# Regenerate the index on Windows

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

```

```bash

# Regenerate the index on Linux/macOS

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

```

## What Information tool-index.md Contains

The index captures three critical data points for each discovered tool:

- **Tool availability** — Confirms whether a required binary (e.g., `ida`, `radare2`, `bloodhound`) is installed
- **Exact executable paths** — Records the actual filesystem location, which varies across environments
- **Version information** — Ensures the correct tool version is being used for compatibility

This structured data enables both human inspection and programmatic consumption throughout the skill system.

## How Skills Use tool-index.md

The routing documentation at [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) establishes a strict operational rule: *"Check [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) for actual tool availability, paths, and versions. NEVER guess paths."* This principle appears consistently across skill implementations.

Skills reference the index before tool invocation to validate prerequisites:

```powershell

# Example pattern from skill implementations

if ((Get-Content ../tool-index.md) -match 'IDA Pro') {
    # Proceed with IDA-based analysis

} else {
    Write-Warning "IDA not found – run refresh-tool-index first."
}

```

For automated parsing, skills prefer the JSON variant:

```bash

# Extract radare2 details programmatically

jq '.tools[] | select(.name=="radare2")' skills/tool-index.json

```

## Integration with Claude Routing System

Beyond individual skills, the **Claude routing system** consumes [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) to determine capability availability during automated runs. As implemented in `skills/scripts/refresh-tool-index.ps1` at line 80, this enables dynamic decision-making about which analysis paths are viable without human intervention.

This integration transforms static skill definitions into **adaptive workflows** that automatically adjust to the host's installed toolchain.

## Key Files in the Tool Index System

| File | Purpose |
|------|---------|
| `skills/tool-index.md.template` | Documents auto-generation and git-ignore status |
| `skills/scripts/refresh-tool-index.ps1` | Windows scanning and index generation |
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Unix scanning and index generation |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Operational documentation mandating index consultation |
| [`skills/ida-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ida-reverse/SKILL.md) | Concrete skill example showing index usage |

## Summary

- **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is auto-generated and git-ignored** — never edit manually or commit to version control
- **Two refresh scripts maintain cross-platform parity** — PowerShell for Windows, Bash for macOS/Linux
- **Skills depend on it for safe execution** — checking availability, paths, and versions before tool invocation
- **The Claude routing system uses it for dynamic capability mapping** — enabling adaptive automation
- **JSON output supports programmatic consumption** — while Markdown serves human readability

## Frequently Asked Questions

### What happens if tool-index.md is missing?

Skills will typically fail safe with warnings. Run the appropriate refresh script for your platform to generate the index before executing any analysis workflows.

### Why not just use standard PATH resolution?

Security tools install to unpredictable locations across different distributions, package managers, and manual installations. Hardcoded paths break portability; PATH resolution misses version requirements. The index captures both location and version explicitly.

### Can I edit tool-index.md manually?

No — changes will be overwritten on the next refresh. Modify the template at `skills/tool-index.md.template` if documentation needs updates, or adjust the refresh scripts if scanning logic requires changes.

### Does tool-index.md work in CI/CD environments?

Yes, provided the refresh script runs during environment setup. The generated index then ensures subsequent steps use correct tool paths without environment-specific assumptions.