How to Configure the Tool-Index for Local Security Tools in Reverse-Skill

The tool-index is auto-generated by running platform-specific refresh scripts that detect installed security utilities, extract versions, and produce both human-readable markdown and machine-readable JSON catalogs.

The tool-index serves as the central catalogue for the reverse-skill framework, telling the system which security utilities are present on a workstation, how to invoke them, and whether a corresponding MCP (Model-Controlled-Process) service is registered. Unlike static configuration files, the index is generated dynamically through a pipeline that probes the host environment. This article explains how to configure and extend this index according to the zhaoxuya520/reverse-skill source code.

Understanding the Tool-Index Architecture

The generation pipeline relies on three coordinated components that transform raw system state into structured documentation.

Core Components

Template (skills/tool-index.md.template)
Provides the human-readable markdown skeleton that explains the layout, the "首次使用" (first-time use) block, and the capability status view. This file serves as the header for the generated index.

Refresh Script (skills/scripts/refresh-tool-index.sh and refresh-tool-index.ps1)
Detects the host OS via uname -s, probes for each tool using command -v, gathers version strings, builds the markdown table, and appends a capability-status sub-table. The Bash script handles Linux/macOS (lines 21-25), while the PowerShell variant covers Windows.

Bootstrap Manifest (kali/scripts/bootstrap-manifest.json)
Lists every capability that can be auto-installed, the package source (apt, brew, pip, GitHub release), and optional MCP registration data. This manifest drives the "能力状态视图" (capability status view) and supplies per-tool install hints.

How the Index Generation Works

The refresh-tool-index.sh script executes a six-stage pipeline to build the catalogue.

Platform Detection
The script calls uname -s to distinguish between linux, macos, and unknown systems (lines 21-25).

Command Existence Checks
The has_cmd function verifies availability using command -v. The TOOLS array (lines 106-140) defines each entry with:

• name: The label shown in the index
• skill: The containing skill folder
• purpose: Short description
• commands: Comma-separated executable names
• version command: Invocation like java -version
• path probes: Fallback locations like $HOME/tools/jadx/bin/jadx

Version Extraction
run_version executes the version command, strips newlines, and preserves the first line only (lines 30-37).

Install Hint Mapping
The install_hint function maps <platform>:<tool> pairs to installation instructions (lines 56-102), yielding outputs like "apt: apt install nmap" or "brew: brew install jadx".

Markdown Assembly
For every detected tool, the script writes a row to skills/tool-index.md (lines 53-55, 101-102). After the main table, it parses bootstrap-manifest.json alongside the local MCP config ($HOME/.claude/mcp.json by default) to generate a capability status table showing whether tools are available, ready, MCP-registered, or auto-installable (lines 26-73, 78-89).

Artifact Generation
The final outputs are skills/tool-index.md for human operators and skills/tool-index.json for programmatic consumption.

Step-by-Step Configuration Guide

Generating the Initial Index

Run the platform-appropriate script from the repository root to create the initial catalogue.

On Linux or macOS:

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

On Windows:

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

The script outputs the paths to the generated files:

✅ Tool index refreshed
  markdown=skills/tool-index.md
  json=skills/tool-index.json

Adding Custom Security Tools

To register a new tool like zsteg, edit the TOOLS array in skills/scripts/refresh-tool-index.sh. Append an entry following the pipe-delimited format:

# Existing entries around lines 106-140

TOOLS=(
  # ... existing tools ...

  "zsteg|stego|Steganography scanner|zsteg|zsteg -V|$HOME/tools/zsteg/bin/zsteg"
)

Then update the install_hint function to provide installation guidance:

install_hint() {
  case "$1:$2" in
    # ... existing cases ...

    linux:zsteg) echo "GitHub release: download zsteg tarball to ~/tools/zsteg" ;;
    macos:zsteg) echo "brew: brew install zsteg" ;;
  esac
}

Re-run the refresh script to regenerate both the markdown and JSON indices.

Defining Capabilities and MCP Registration

For tools requiring MCP integration or complex installation logic, define a capability object in kali/scripts/bootstrap-manifest.json. The jadx entry (lines 27-38) demonstrates a GitHub-release-based installer with MCP registration data:

{
  "name": "jadx",
  "install_source": "github-release",
  "repository": "skylot/jadx",
  "mcp_service": "jadx-decompiler",
  "verify_command": "jadx --version"
}

The refresh script cross-references this manifest against your local MCP configuration to populate the capability status view in the generated index.

Consuming the Tool-Index

Skill modules reference skills/tool-index.md to determine whether required binaries exist before offering commands. For example, skills/ida-reverse/SKILL.md checks the index to conditionally display decompilation workflows.

The MCP bridge (burp-mcp-full/mcp-bridge.js) reads skills/tool-index.json to auto-expose tools as MCP services when the Ready column is marked available. This allows AI agents to discover and invoke security tools via the MCP protocol without manual configuration.

Keeping the index updated ensures human users see accurate availability information while enabling automated tooling discovery.

Summary

• The tool-index is auto-generated, not hand-written, via refresh-tool-index.sh or refresh-tool-index.ps1.
• Three components drive generation: the markdown template, the refresh script with its TOOLS array, and the bootstrap manifest.
• Add new tools by extending the TOOLS array and updating the install_hint function with platform-specific instructions.
• Enable MCP integration by defining capabilities in bootstrap-manifest.json and ensuring the tool is registered in $HOME/.claude/mcp.json.
• Refresh regularly to keep tool-index.md and tool-index.json synchronized with your actual workstation state.

Frequently Asked Questions

Where is the tool-index configuration stored?

The configuration is distributed across three locations: the template at skills/tool-index.md.template, the detection logic in skills/scripts/refresh-tool-index.sh (or .ps1 for Windows), and the capability definitions in kali/scripts/bootstrap-manifest.json. The generated artefacts live at skills/tool-index.md and skills/tool-index.json.

How do I add a tool that is not in the default TOOLS array?

Edit skills/scripts/refresh-tool-index.sh and append a new entry to the TOOLS array following the format name|skill|purpose|commands|version_cmd|fallback_path. Then add corresponding install hints to the install_hint function. Re-run the script to update the index.

What is the difference between the markdown and JSON index files?

skills/tool-index.md provides a human-readable catalogue with tables showing tool availability and capability status. skills/tool-index.json contains the same data in machine-readable format for scripts and the MCP bridge to consume programmatically.

How does the tool-index interact with MCP services?

The refresh script checks $HOME/.claude/mcp.json to determine if a tool is registered as an MCP service. It cross-references this with bootstrap-manifest.json to generate the capability status view, indicating whether a tool is ready for AI agent invocation via the Model-Controlled-Process protocol.

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