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

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 on Linux/macOS/Kali—to regenerate the machine-specific inventory.

The reverse-skill repository relies on 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 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 — human-readable markdown table of all discovered tools
• 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, skills explicitly reference ../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 -NoProfile -ExecutionPolicy Bypass -File "skills/scripts/refresh-tool-index.ps1"

Linux/macOS/Kali:

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 and skills/tool-index.json
• Append a "Capability Status" sub-table showing MCP registration state

3. Verify the Generated Entry

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

{
  "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 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 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 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

The routing coherence test explicitly validates that every tool referenced in routing.json exists in 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 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 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 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 (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 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, agents may need to re-read that manifest depending on their startup behavior.

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