# How to Properly Update `tool-index.md` After Manually Installing a New Security Tool

> Learn how to properly update tool-index.md after manual security tool installation. Run the platform specific refresh script to regenerate your machine inventory.

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

---

**Run the platform-specific refresh script after installing your tool—`skills/scripts/refresh-tool-index.ps1` on Windows or [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) on Linux/macOS/Kali—to regenerate the machine-specific inventory.**

The `reverse-skill` repository relies on [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) as the central registry that maps every security tool to its absolute path, version, and owning skill. This file is **automatically generated** and **git-ignored** to keep local system paths private. When you manually install a tool—whether via package manager, binary download, or source compilation—you must trigger the refresh routine to bring the index into sync.

## Why tool-index.md Is Auto-Generated

The file [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) is deliberately excluded from version control. Each analyst's workstation has unique installation paths, so the repository ships only a **template** at `skills/tool-index.md.template` that documents the expected format with placeholder rows.

Actual runtime behavior depends on the generated files:
- [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) — human-readable markdown table of all discovered tools
- [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) — machine-readable companion used by scripts and routing logic

Downstream components read this index to resolve tool locations. As noted in the [reverse-engineering SKILL.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/reverse-engineering/SKILL.md), skills explicitly reference [`../tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/../tool-index.md) to locate binaries rather than guessing paths.

## Step-by-Step Workflow for Updating tool-index.md

### 1. Install the Tool on Your Host

Use the appropriate method for your platform and tool:

- **Windows** — `winget`, `choco`, manual MSI installer, or portable binary
- **Linux** — `apt`, `dnf`, `pacman`, `pipx`, or source compilation
- **macOS** — `brew`, MacPorts, or manual installation

Ensure the binary is on your `PATH` or note its absolute installation directory.

### 2. Run the Refresh Script

The repository provides platform-specific scripts that scan your system and rebuild both the markdown and JSON indexes.

**Windows:**

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

```

**Linux/macOS/Kali:**

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

```

Both scripts perform identical discovery logic:
- Detect known tools by checking common installation directories and `PATH` entries
- Execute version commands (typically `--version`) to extract version strings
- Write the updated inventory to [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json)
- Append a "Capability Status" sub-table showing MCP registration state

### 3. Verify the Generated Entry

Open [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and confirm your new tool appears with complete metadata:

| Tool | Skill | Purpose | Available | Path | Version | Install hint |
|------|-------|---------|:--------:|------|---------|--------------|
| nmap | pentest-tools | Network scanner | ✓ | `C:\Program Files\Nmap\nmap.exe` | 7.94 | winget-package |

Required fields include:
- **Tool** — canonical tool name used throughout the repository
- **Skill** — which skill module owns or primarily uses this tool
- **Path** — absolute path to the executable (no environment variable expansion)
- **Version** — exact version string for reproducible audits

Absent or malformed entries will cause routing coherence checks to fail.

### 4. (Optional) Register MCP-Capable Tools

Tools that expose an MCP service require additional registration in [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json). This enables other agents to discover the service endpoint automatically.

The manifest uses a `manualInstallHint` field for tools needing post-installation registration. Example from the repository's JEB Pro entry:

```json
{
  "tool": "jeb-pro",
  "mcpService": true,
  "manualInstallHint": "Run JEB once with license to activate MCP bridge"
}

```

Without this registration, the tool will appear in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) but MCP-dependent workflows will fail to locate the service.

## How the Refresh Scripts Work

The discovery logic in `skills/scripts/refresh-tool-index.ps1` and [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) maintains a curated list of tools grouped by skill domain. For each candidate:

1. **Path resolution** — checks predefined locations and `PATH` environment
2. **Version extraction** — executes `--version` or equivalent flag
3. **Metadata assembly** — builds the markdown table row and JSON object
4. **Capability checking** — tests MCP endpoint reachability where applicable

The scripts are idempotent. Running them repeatedly produces consistent results based on current system state.

## Enforcement and Safety Mechanisms

| Mechanism | Purpose | Location |
|-----------|---------|----------|
| **Path validation** | Prevents execution of unindexed binaries | [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) references tool-index for availability checks |
| **Routing coherence** | Fails CI/tests when tools are missing from index | `skills/scripts/verify-routing-coherence.ps1` |
| **Version pinning** | Enables reproducible security audits | Embedded in generated [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) |

The routing coherence test explicitly validates that every tool referenced in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) exists in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) with `Available: ✓`. A missing entry halts execution rather than risking invocation of an unknown binary.

## Common Mistakes to Avoid

- **Editing [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) manually** — your changes will be overwritten on next refresh and never committed
- **Committing the generated file** — the `.gitignore` entry exists precisely to prevent this
- **Forgetting the JSON companion** — some automation reads [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) exclusively; refresh both formats with the official scripts
- **Ignoring MCP registration** — tools like JEB Pro or custom MCP bridges require the manifest update step for full functionality

## Summary

- [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is machine-specific and auto-generated—never edit or commit it directly
- Run `skills/scripts/refresh-tool-index.ps1` (Windows) or [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (Linux/macOS/Kali) after any manual tool installation
- Verify the generated entry includes tool name, skill ownership, absolute path, and version
- Add MCP registration hints in [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) for service-capable tools
- The routing system enforces index consistency; missing tools block execution rather than fail silently

## Frequently Asked Questions

### What happens if I manually edit tool-index.md instead of running the refresh script?

Your changes will be lost when the refresh script runs again, and downstream routing checks may fail if your manual edits deviate from expected format. The refresh scripts are the single source of truth for index generation.

### How do I add a tool that the refresh script doesn't detect automatically?

Extend the discovery logic in your platform's refresh script, or ensure the tool is on your `PATH` with a recognizable executable name. For one-off tools, you can temporarily add an entry to `tool-index.md.template` to document the expected format, then run the refresh script to generate the actual index.

### Why is tool-index.md.gitignored but tool-index.md.template is versioned?

The template provides documentation and format guidance that applies to all users. The actual index contains absolute paths like `C:\Users\alice\Tools\` or `/home/bob/bin/` that vary by workstation and would cause merge conflicts if committed.

### Do I need to restart anything after running the refresh script?

No restart required. The markdown and JSON files are read at runtime by skills and routing logic. However, if you added MCP registration hints in [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json), agents may need to re-read that manifest depending on their startup behavior.