# How tool-index.md Is Generated and What Happens When Tools Are Missing

> Discover how tool-index.md is generated by scripts that check for installed security tools. Learn what happens when tools are missing, with explicit indicators for easy resolution.

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

---

**[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is machine-generated by platform-specific scripts that probe for installed security and reverse-engineering tools, and missing tools are explicitly marked with ✗, empty paths, and actionable install hints rather than causing silent failures.**

The *reverse-skill* repository maintains [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) as a **local, auto-generated inventory** of every supported tool. Because absolute paths differ across machines, this file is **git-ignored** and must be created on first use by running a refresh script. The process is deterministic, reproducible, and designed to prevent downstream failures by clearly surfacing tool availability.

## Generation Workflow by Platform

The repository provides three entry points for generating [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md):

| Platform | Command |
|----------|---------|
| **Windows** | `powershell -NoProfile -ExecutionPolicy Bypass -File "skills/scripts/refresh-tool-index.ps1"` |
| **Linux / macOS** | `bash skills/scripts/refresh-tool-index.sh` |
| **Kali Linux** | `bash kali/scripts/refresh-tool-index.sh` |

### What the Scripts Actually Do

Both the **PowerShell** and **Bash** implementations follow an identical six-step flow:

1. **Determine platform** — `macos`, `linux`, or `unknown` (Bash uses `uname -s`).
2. **Define helper functions** — `has_cmd`, `cmd_path`, `run_version`, and `install_hint`.
3. **Declare the tool catalogue** — an array where each entry contains `name|skill|purpose|command-list|version-spec|path-probes`.
4. **Iterate and probe** — check `command -v` (Bash) or `Get-Command` (PowerShell); fall back to optional path probes like `$HOME/tools/jadx/bin/jadx`.
5. **Run version commands** — capture readable version strings when available.
6. **Write outputs** — produce both [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) (markdown table) and [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) (machine-readable).

A **Python sub-process** appends a *Capability Status* section that cross-references the bootstrap manifest, local MCP config, and tool-availability table for richer reporting on MCP registration and service health.

## Structure of the Generated File

The resulting [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) contains a markdown table with these columns:

| Column | Purpose |
|--------|---------|
| **Tool** | Canonical tool name |
| **Skill** | Which reverse-skill category uses it |
| **Purpose** | Short description (e.g., "APK Java/Kotlin decompiler") |
| **Available** | `✓` or `✗` |
| **Path** | Absolute path to binary, or `—` if missing |
| **Version** | Detected version string, or `—` if missing |
| **Install hint** | Concrete command to obtain the tool |

Example excerpt from a generated file:

```markdown
| Tool   | Skill               | Purpose                    | Available | Path                        | Version | Install hint                   |
|--------|---------------------|----------------------------|-----------|-----------------------------|---------|--------------------------------|
| jadx   | apk-reverse         | APK Java/Kotlin decompiler | ✗         | —                           | —       | brew: brew install jadx        |
| frida  | reverse-engineering | Dynamic instrumentation    | ✓         | /home/user/.local/bin/frida | 15.2.2  | pipx: pipx install frida-tools |
| idapro | ida-reverse         | IDA Pro commercial         | ✗         | —                           | —       | manual licensed install: https://… |

```

## What Happens When Tools Are Missing

When the **tool-index.md generation process** encounters a missing tool, it applies a consistent failure-handling pattern:

- **Available** is set to `✗` (JSON: `"available": false`).
- **Path** and **Version** display `—` (JSON: `null` or empty string).
- **Install hint** contains a platform-appropriate command: `brew install …`, `apt install …`, `pipx install …`, or a manual download URL.

This design prevents silent failures. As specified in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), **when a task needs a tool marked "✗", the operator must install the tool before proceeding**. The system never guesses paths or assumes defaults—it always relies on the refreshed index.

## Working with tool-index.md

### Refresh the Index on First Run

The template file `skills/tool-index.md.template` (lines 10–20) instructs new users to generate their local index immediately:

```bash

# Linux / macOS

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

# Windows

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

```

### Check a Specific Tool's Status

```bash

# Query the generated markdown for frida

grep -i '^| frida ' skills/tool-index.md

```

Expected output:

```text
| frida | reverse-engineering | Dynamic instrumentation CLI | ✓ | /home/user/.local/bin/frida | 15.2.2 | pipx: pipx install frida-tools |

```

### Programmatically Handle Missing Tools

Parse [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) to automate installation workflows:

```python
import json
import pathlib

data = json.loads(pathlib.Path("skills/tool-index.json").read_text())

for tool in data["tools"]:
    if not tool["available"]:
        print(f"⚠️ {tool['name']} is missing – install via: {tool['install_hint']}")

```

This snippet lists every missing tool with its suggested install command, enabling scripted environment setup.

## Key Implementation Files

| File | Purpose |
|------|---------|
| `skills/tool-index.md.template` | Human-readable template explaining first-run commands and table layout. |
| `skills/scripts/refresh-tool-index.ps1` | Windows PowerShell implementation with hard-coded tool hash table. |
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Core Bash logic for Linux/macOS; also invoked by Kali wrapper. |
| [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) | Thin wrapper calling the generic Bash script. |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Policy enforcing index generation and describing missing-tool handling. |
| [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) / `.ps1` | Full environment bootstrap that includes `refresh-tool-index`. |

## Summary

- **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is machine-local and git-ignored**, generated by `refresh-tool-index` scripts on Windows, Linux, macOS, and Kali.
- **Generation probes command existence**, optional fallback paths, and version strings, outputting both markdown and JSON.
- **Missing tools are clearly flagged** with ✗, `—` placeholders, and concrete `install_hint` suggestions—never silent defaults.
- **Downstream skills depend on this index** to verify availability before execution, as enforced by [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md).

## Frequently Asked Questions

### How do I generate tool-index.md for the first time?

Run the platform-appropriate refresh script: `bash skills/scripts/refresh-tool-index.sh` on Linux/macOS/Kali, or the PowerShell equivalent on Windows. The template file `skills/tool-index.md.template` reminds you of this command because the actual [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) cannot be committed to git.

### What happens if I run a skill without a required tool installed?

The skill will fail explicitly. Per [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the system never guesses paths or assumes tool availability. You must install the missing tool—using the `install_hint` from your local [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)—then regenerate the index.

### Why is tool-index.md git-ignored instead of tracked in the repository?

The file contains absolute paths like `/home/user/.local/bin/frida` that differ across every machine. Tracking it would cause constant merge conflicts and non-portable configurations. The tracked `tool-index.md.template` documents the schema while the actual file is generated locally.

### Can I automate tool installation based on the generated index?

Yes. Parse [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) programmatically—each tool entry includes `available` (boolean) and `install_hint` (string). A simple Python script can filter for `available: false` and execute the suggested install commands or queue them for manual review.