# What Is the Purpose of the `tool-index.md` File in Reverse-Skill?

> Discover the purpose of the tool-index.md file in Reverse-Skill. Learn how this auto-generated index catalogs security tools for safe skill routing and automated capability detection.

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

---

**[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is a machine-specific, auto-generated index that catalogs every security tool available on the host where Reverse-Skill runs, enabling safe skill routing and automated capability detection.**

The [[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md.template) file sits at the heart of Reverse-Skill's **capability-discovery subsystem**. Unlike static documentation, this file is generated on-demand by platform-specific scripts and serves as the single source of truth for which reverse-engineering tools are installed, their versions, and whether required Micro-Capability Protocol (MCP) services are online.

## How [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) Is Generated

Reverse-Skill provides two generation scripts that scan the host environment and produce the index:

- **Windows**: [`skills/scripts/refresh-tool-index.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.ps1)
- **Linux/macOS (including Kali)**: [[`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh)

These scripts populate a markdown table with the following columns:

| Windows Column | Linux/macOS Column | Purpose |
|----------------|-------------------|---------|
| **工具 / Tool** | **Tool** | Binary or service name (`jadx`, `frida`, `nmap`, etc.) |
| **归属 skill / Skill** | **Skill** | Which Reverse-Skill capability requires this tool |
| **作用 / Purpose** | **Purpose** | Human-readable description of the tool's function |
| **可用 / Available** | **Available** | Boolean: `Yes` if detected, `No` if missing |
| **路径 / Path** | **Path** | Absolute path to the binary or service endpoint |
| **版本 / Version** | **Version** | Detected version string |
| **来源 / Source** | **Install hint** | Installation command or source (apt, pip, winget, GitHub release) |
| **脚本引用 / Script reference** | — | Windows-specific invocation snippet |
| **能力状态视图 / Capability Status** | **Capability Status** | MCP registration status, TCP health check, auto-install flags |

The generation process leverages helper libraries like [[`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) for low-level binary detection and version parsing.

## Why [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) Is Gitignored

The file **does not ship with the repository**. It is intentionally excluded via `.gitignore` because:

- Tool availability varies by workstation
- Version strings differ across environments
- MCP service endpoints are host-specific

Instead, the repository contains a **template** at [`skills/tool-index.md.template`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md.template) that documents the expected schema and generation workflow.

## Runtime Uses of [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)

The generated index drives four critical runtime behaviors in Reverse-Skill.

### 1. Pre-Execution Tool Validation

Before invoking a skill, the routing engine checks whether required tools are present. This prevents mid-execution failures.

```powershell

# Example: Verify nmap availability before network scan

$toolIndex = Get-Content -Path ".\tool-index.md" -Raw
if ($toolIndex -match '\| nmap \|.*\| Yes \|') {
    Write-Host "nmap detected — proceeding with scan..."
} else {
    Write-Error "nmap missing — aborting skill execution."
}

```

### 2. MCP Service Health Verification

MCP-based capabilities (`idapro`, `burpsuite-mcp`, `anything-analyzer`) require both registration and network reachability. The **Capability Status** sub-table provides this data.

```powershell

# Check if IDA Pro MCP is registered and responsive

$capabilityMatch = $toolIndex -match '\| idapro \|.*\| (?<mcp>Yes|No) \|.*\| (?<online>Online|Offline) \|'
if ($Matches.mcp -eq 'Yes' -and $Matches.online -eq 'Online') {
    Invoke-IDAProAnalysis
}

```

### 3. Automatic Installation Guidance

When tools are missing, the **Source / Install hint** column provides actionable commands.

```bash

# Extract install hint for frida

if grep -q '| frida |.*| No |' tool-index.md; then
    install_cmd=$(grep '| frida |' tool-index.md | awk -F'|' '{print $8}' | xargs)
    echo "Install with: $install_cmd"
    # Output: pip install frida-tools

fi

```

### 4. Routing Decisions in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)

The [[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) configuration references [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) to determine which skill implementation to execute based on available capabilities.

## Architecture: From Template to Runtime Index

```

┌─────────────────────────┐     ┌─────────────────────────────┐
│ tool-index.md.template  │────→│ Platform-specific generator │
│  (schema documentation) │     │  (PowerShell or Bash)       │
└─────────────────────────┘     └─────────────────────────────┘
                                          │
                                          ▼
                              ┌─────────────────────────────┐
                              │   tool-discovery.sh/.ps1    │
                              │   (binary/version/MCP scan) │
                              └─────────────────────────────┘
                                          │
                                          ▼
                              ┌─────────────────────────────┐
                              │     ./tool-index.md         │
                              │   (host-specific, ignored)  │
                              └─────────────────────────────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
              skill scripts         routing.json           operator dashboard
           (pre-flight checks)    (capability-based      (human-readable
                                    routing logic)          status view)

```

## Generating and Refreshing the Index

### Windows (PowerShell)

```powershell

# Execute generation script with bypassed execution policy

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

```

### Linux/macOS (Bash)

```bash

# Run on Kali or other Linux distributions

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

```

Regenerate the index whenever you:
- Install new security tools
- Upgrade existing tool versions
- Deploy or restart MCP services

## Summary

- **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** is an auto-generated, host-specific catalog of available security tools and MCP services.
- **Generation scripts**: [`refresh-tool-index.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.ps1) (Windows) and [[`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) (Linux/macOS) create the file from a [template](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md.template).
- **Runtime functions**: tool validation, MCP health checks, installation hints, and routing decisions.
- **File status**: `.gitignore`d; never committed to version control.

## Frequently Asked Questions

### What happens if [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is missing when a skill runs?

Reverse-Skill will fail safe. Skills check the index before execution; if the file or a required tool entry is absent, the skill aborts with an error directing the operator to run the appropriate refresh script.

### Can I manually edit [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)?

Manual edits are discouraged. The file is **overwritten** on each generation run. To customize tool detection logic, modify [[`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) or the equivalent Windows discovery functions.

### How does Reverse-Skill detect MCP service health?

The generation scripts perform **TCP ping and HTTP handshake** against configured MCP endpoints (e.g., `http://localhost:8080/health` for `burpsuite-mcp`). Results populate the **Capability Status** column as `Online` or `Offline`.

### Why are the Windows and Linux column names different?

The Windows script targets Chinese-speaking operators with bilingual headers (工具/Tool, 归属 skill/Skill), while the Linux script uses English-only headers. Both schemas encode identical semantic information for consumption by the routing engine.