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

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 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:

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 (markdown table) and 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 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:

| 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, 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:

# 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

# Query the generated markdown for frida

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

Expected output:

| 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 to automate installation workflows:

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	Core Bash logic for Linux/macOS; also invoked by Kali wrapper.
kali/scripts/refresh-tool-index.sh	Thin wrapper calling the generic Bash script.
RULES.md	Policy enforcing index generation and describing missing-tool handling.
skills/scripts/bootstrap-reverse.sh / .ps1	Full environment bootstrap that includes refresh-tool-index.

Summary

• 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.

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 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, 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—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 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.

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