How to Set Up and Refresh tool-index.md for Security Tool Detection

Run the platform-specific generator script—refresh-tool-index.ps1 on Windows or refresh-tool-index.sh on Linux/macOS—to scan your host, detect installed security tools, and emit both a human-readable markdown table and a machine-readable JSON index that skills consume to resolve tool paths dynamically.

The reverse-skill repository uses a machine-specific inventory file called tool-index.md to avoid hard-coded paths and enable portable security workflows. This file records which reverse-engineering and pentest tools are installed, their absolute paths, versions, and installation commands. Keeping this index accurate is essential because every skill in the repository consults it before invoking external binaries, ensuring scripts fail gracefully when dependencies are missing.

What is tool-index.md and Why It Matters

tool-index.md serves as the single source of truth for capability detection across the zhaoxuya520/reverse-skill ecosystem. Rather than embedding absolute paths like /usr/bin/nmap or C:\Program Files\Wireshark\ directly into automation scripts, skills reference the index to look up the actual location of each tool on the current workstation.

According to the source code in skills/routing.md, the router explicitly checks tool-index.md for "actual tool availability, paths, and versions" before executing any command. If a tool is marked unavailable or the recorded path differs from the detected binary location, the skill aborts and prompts you to refresh the index. This design makes the repository portable across Windows, macOS, and Kali Linux installations without manual configuration edits.

Architecture and Generator Components

The detection system consists of a template, platform-specific generators, and optional bootstrap hooks.

Template File

The skills/tool-index.md.template defines the markdown layout and column headers. It documents the schema—such as the Available, Path, Version, and Install hint columns—but never contains real host data. Because tool-index.md contains absolute paths that vary per machine, the generated files are git-ignored; only the template is committed to the repository.

PowerShell Generator for Windows

On Windows hosts, skills/scripts/refresh-tool-index.ps1 performs the detection. It builds an 8-column markdown table and a corresponding JSON file (skills/tool-index.json). The script handles Windows-specific path conventions and can be invoked non-interactively during automated deployments.

Bash Generator for Linux and macOS

For Linux, macOS, and Kali systems, skills/scripts/refresh-tool-index.sh performs equivalent detection. It emits a 7-column markdown table and JSON index. A variant exists at kali/scripts/refresh-tool-index.sh for Kali-specific path layouts, though both scripts share the same core logic.

Bootstrap Integration

The generators can be triggered automatically during environment setup. Both skills/scripts/bootstrap-reverse.sh and kali/scripts/bootstrap-reverse.sh call the appropriate refresh script as part of the full installation workflow, ensuring the index exists before any skills are executed.

How the Generator Works

When you execute a refresh script, it performs the following detection pipeline as implemented in the Bash and PowerShell sources:

1. Platform detection – Uses uname -s (Bash) or $env:OS (PowerShell) to determine if the host is Windows, Linux, or macOS.
2. Command discovery – The has_cmd helper checks if a binary exists in $PATH; cmd_path records its absolute location.
3. Version extraction – The run_version function executes tool --version (or equivalent flags) and parses the first line of output.
4. Installation mapping – install_hint maps each missing tool to the correct package manager command, such as sudo apt install, brew install, pipx install, or direct GitHub release downloads.
5. Capability status reporting – Generates a sub-table indicating MCP registration status, service health checks, and auto-install eligibility.
6. Atomic output writing – Writes skills/tool-index.md (human-readable) and skills/tool-index.json (machine-readable) simultaneously.

Step-by-Step Setup and Refresh Workflow

Follow this workflow to initialize and maintain your tool inventory.

1. Generate the initial index

   Windows (PowerShell):

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

   Linux / macOS / Kali (Bash):

   bash skills/scripts/refresh-tool-index.sh
   # For Kali-specific paths:
   
   bash kali/scripts/refresh-tool-index.sh

2. Verify the output

   Inspect the generated markdown to confirm detection accuracy:

   cat skills/tool-index.md

   Confirm that the Available column shows ✓ for installed tools and that Install hint entries exist for missing dependencies.

3. Install missing tools

   Use the hints provided in the index to add new capabilities. For example:

   sudo apt install binwalk
   pipx install frida-tools
   brew install ghidra

4. Refresh after changes

   Re-run the same generator command used in step 1. The script updates version strings, path changes, and availability flags automatically. Skills will immediately use the refreshed data on their next invocation.

Code Examples

Generating the Index on macOS

From the repository root, execute the Bash generator:

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

This creates two files:

• skills/tool-index.md – The markdown table for human review
• skills/tool-index.json – The JSON index for programmatic consumption

Sample Output Structure

A generated tool-index.md on Linux resembles this excerpt:

| Tool   | Skill               | Purpose                     | Available | Path                     | Version          | Install hint                                   |
|--------|--------------------|-----------------------------|-----------|--------------------------|------------------|-----------------------------------------------|
| nmap   | pentest-tools      | Network scanning            | ✓         | /usr/bin/nmap            | 7.93             | apt: sudo apt install nmap                    |
| frida  | mobile-reverse     | Instrumentation framework   | ✗         | —                        | —                | pipx: pipx install frida-tools                |
| ghidra | ghidra-reverse     | Decompiler                  | ✓         | ~/tools/ghidra/ghidraRun | 11.4 (20230913)  | brew: brew install ghidra or brew install --cask ghidra |

Refreshing After Installing Frida

After adding a new tool, update the index to reflect the change:

pipx install frida-tools
bash skills/scripts/refresh-tool-index.sh

The script detects the new binary location, captures its version, and flips the Available flag from ✗ to ✓.

Consuming the Index in Skills

Skills read the index before invocation. The following PowerShell pseudo-code demonstrates safe tool execution using the indexed path:

$toolInfo = Import-Csv -Path "$PSScriptRoot\../tool-index.md" | Where-Object { $_.Tool -eq 'frida' }
if ($toolInfo.Available -eq '✓') {
    & $toolInfo.Path frida-ps
} else {
    Write-Host "Frida not installed – run refresh-tool-index.ps1 first."
}

Summary

• tool-index.md is a machine-specific inventory that maps tool names to absolute paths, versions, and installation commands.
• Generators exist for both Windows (refresh-tool-index.ps1) and Unix-like systems (refresh-tool-index.sh), producing both markdown and JSON outputs.
• Git-ignored status means you must run the refresh script on each new workstation; never commit your local index.
• Integration with bootstrap scripts (bootstrap-reverse.sh) ensures the index is built automatically during environment setup.
• Skills depend on this file to resolve tool locations dynamically, making the repository portable across different operating systems and installation methods.

Frequently Asked Questions

Why does tool-index.md need to be refreshed after installing new tools?

The index captures absolute filesystem paths and version strings that change when software is added or updated. Because the reverse-skill repository prohibits hard-coded paths, skills consult this file to locate binaries. If you install a new tool like frida via pipx but do not refresh the index, skills will report the tool as unavailable even though it exists on your system. Running the refresh script updates the Available flags, Path columns, and Version fields atomically.

What is the difference between tool-index.md and tool-index.json?

Both files are generated simultaneously by the same script, but they serve different consumers. tool-index.md is a human-readable markdown table with 7–8 columns (depending on platform) that you can inspect in any text editor to verify your environment setup. tool-index.json is a machine-readable format that skills and automation scripts parse programmatically to extract tool metadata without regex parsing markdown tables. Both files are git-ignored and should be regenerated whenever your toolset changes.

Can I commit my tool-index.md to share my configuration with teammates?

No. The file is explicitly listed in .gitignore because it contains absolute paths (e.g., /home/username/tools/ghidra/ghidraRun or C:\Users\Name\scoop\apps\) that are specific to your workstation. Sharing this file would cause failures on other machines. Instead, commit only the skills/tool-index.md.template, which documents the schema without host-specific data. Teammates should run the appropriate refresh-tool-index script on their own systems to generate valid local indices.

How does the refresh script detect tool versions without hard-coded flags?

The generators use a helper function—run_version in the Bash implementation—that attempts common version flags (--version, -v, -V) and parses the first line of output. For tools with non-standard version commands, the script maintains an internal mapping within the install_hint and version detection logic. This ensures that diverse tools ranging from nmap to ghidra report their versions consistently in the index, regardless of their CLI interface quirks.

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