What Is the Purpose of the `tool-index.md` File in Reverse-Skill?

tool-index.md is a machine-specific, auto-generated index that catalogs every security tool available on the host where Reverse-Skill runs, enabling safe skill routing and automated capability detection.

The [tool-index.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md.template) file sits at the heart of Reverse-Skill's capability-discovery subsystem. Unlike static documentation, this file is generated on-demand by platform-specific scripts and serves as the single source of truth for which reverse-engineering tools are installed, their versions, and whether required Micro-Capability Protocol (MCP) services are online.

How tool-index.md Is Generated

Reverse-Skill provides two generation scripts that scan the host environment and produce the index:

• Windows: skills/scripts/refresh-tool-index.ps1
• Linux/macOS (including Kali): [kali/scripts/refresh-tool-index.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh)

These scripts populate a markdown table with the following columns:

Windows Column	Linux/macOS Column	Purpose
工具 / Tool	Tool	Binary or service name (jadx, frida, nmap, etc.)
归属 skill / Skill	Skill	Which Reverse-Skill capability requires this tool
作用 / Purpose	Purpose	Human-readable description of the tool's function
可用 / Available	Available	Boolean: Yes if detected, No if missing
路径 / Path	Path	Absolute path to the binary or service endpoint
版本 / Version	Version	Detected version string
来源 / Source	Install hint	Installation command or source (apt, pip, winget, GitHub release)
脚本引用 / Script reference	—	Windows-specific invocation snippet
能力状态视图 / Capability Status	Capability Status	MCP registration status, TCP health check, auto-install flags

The generation process leverages helper libraries like [kali/scripts/lib/tool-discovery.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) for low-level binary detection and version parsing.

Why tool-index.md Is Gitignored

The file does not ship with the repository. It is intentionally excluded via .gitignore because:

• Tool availability varies by workstation
• Version strings differ across environments
• MCP service endpoints are host-specific

Instead, the repository contains a template at skills/tool-index.md.template that documents the expected schema and generation workflow.

Runtime Uses of tool-index.md

The generated index drives four critical runtime behaviors in Reverse-Skill.

1. Pre-Execution Tool Validation

Before invoking a skill, the routing engine checks whether required tools are present. This prevents mid-execution failures.

# Example: Verify nmap availability before network scan

$toolIndex = Get-Content -Path ".\tool-index.md" -Raw
if ($toolIndex -match '\| nmap \|.*\| Yes \|') {
    Write-Host "nmap detected — proceeding with scan..."
} else {
    Write-Error "nmap missing — aborting skill execution."
}

2. MCP Service Health Verification

MCP-based capabilities (idapro, burpsuite-mcp, anything-analyzer) require both registration and network reachability. The Capability Status sub-table provides this data.

# Check if IDA Pro MCP is registered and responsive

$capabilityMatch = $toolIndex -match '\| idapro \|.*\| (?<mcp>Yes|No) \|.*\| (?<online>Online|Offline) \|'
if ($Matches.mcp -eq 'Yes' -and $Matches.online -eq 'Online') {
    Invoke-IDAProAnalysis
}

3. Automatic Installation Guidance

When tools are missing, the Source / Install hint column provides actionable commands.

# Extract install hint for frida

if grep -q '| frida |.*| No |' tool-index.md; then
    install_cmd=$(grep '| frida |' tool-index.md | awk -F'|' '{print $8}' | xargs)
    echo "Install with: $install_cmd"
    # Output: pip install frida-tools

fi

4. Routing Decisions in routing.json

The [skills/config/routing.json](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) configuration references tool-index.md to determine which skill implementation to execute based on available capabilities.

Architecture: From Template to Runtime Index

┌─────────────────────────┐     ┌─────────────────────────────┐
│ tool-index.md.template  │────→│ Platform-specific generator │
│  (schema documentation) │     │  (PowerShell or Bash)       │
└─────────────────────────┘     └─────────────────────────────┘
                                          │
                                          ▼
                              ┌─────────────────────────────┐
                              │   tool-discovery.sh/.ps1    │
                              │   (binary/version/MCP scan) │
                              └─────────────────────────────┘
                                          │
                                          ▼
                              ┌─────────────────────────────┐
                              │     ./tool-index.md         │
                              │   (host-specific, ignored)  │
                              └─────────────────────────────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
              skill scripts         routing.json           operator dashboard
           (pre-flight checks)    (capability-based      (human-readable
                                    routing logic)          status view)

Generating and Refreshing the Index

Windows (PowerShell)

# Execute generation script with bypassed execution policy

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

Linux/macOS (Bash)

# Run on Kali or other Linux distributions

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

Regenerate the index whenever you:

• Install new security tools
• Upgrade existing tool versions
• Deploy or restart MCP services

Summary

• tool-index.md is an auto-generated, host-specific catalog of available security tools and MCP services.
• Generation scripts: refresh-tool-index.ps1 (Windows) and [refresh-tool-index.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) (Linux/macOS) create the file from a template.
• Runtime functions: tool validation, MCP health checks, installation hints, and routing decisions.
• File status: .gitignored; never committed to version control.

Frequently Asked Questions

What happens if tool-index.md is missing when a skill runs?

Reverse-Skill will fail safe. Skills check the index before execution; if the file or a required tool entry is absent, the skill aborts with an error directing the operator to run the appropriate refresh script.

Can I manually edit tool-index.md?

Manual edits are discouraged. The file is overwritten on each generation run. To customize tool detection logic, modify [kali/scripts/lib/tool-discovery.sh](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) or the equivalent Windows discovery functions.

How does Reverse-Skill detect MCP service health?

The generation scripts perform TCP ping and HTTP handshake against configured MCP endpoints (e.g., http://localhost:8080/health for burpsuite-mcp). Results populate the Capability Status column as Online or Offline.

Why are the Windows and Linux column names different?

The Windows script targets Chinese-speaking operators with bilingual headers (工具/Tool, 归属 skill/Skill), while the Linux script uses English-only headers. Both schemas encode identical semantic information for consumption by the routing engine.

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