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

> Learn to set up and refresh tool-index.md for security tool detection. Use scripts to scan your host, detect tools, and generate markdown and JSON indexes for dynamic path resolution.

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

---

**Run the platform-specific generator script—`refresh-tool-index.ps1` on Windows or [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), the router explicitly checks [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) and [`kali/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](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-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
   powershell -NoProfile -ExecutionPolicy Bypass -File "skills/scripts/refresh-tool-index.ps1"
   ```

   
   **Linux / macOS / Kali (Bash):**
   ```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:
   ```bash
   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:
   ```bash
   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
bash skills/scripts/refresh-tool-index.sh

```

This creates two files:
- [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) – The markdown table for human review
- [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) – The JSON index for programmatic consumption

### Sample Output Structure

A generated [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) on Linux resembles this excerpt:

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

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

```powershell
$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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.