How to Set Up tool-index.md for Local Environment Validation in reverse-skill

Create a local tool-index.md manifest by running the platform-specific refresh script from the repository root, which scans the filesystem and populates the template at skills/tool-index.md.template with discovered tool scripts.

The reverse-skill repository requires a generated manifest file to route commands to the correct platform-specific scripts. Setting up tool-index.md for local environment validation is essential before running workflows, as skills rely on this index to resolve execution paths for tools like Windows AD utilities, IDA reverse engineering scripts, and Kali Linux utilities.

Understanding the tool-index.md Manifest

tool-index.md is a generated Markdown file that acts as the central registry for every tool script shipped with reverse-skill. The manifest maps each tool to its supported platforms and entry script locations, enabling the skill router to execute the correct command for the current host.

The repository provides a template at skills/tool-index.md.template that serves as the blank structure. Helper scripts then copy this template, scan the repository for executable scripts, and populate the table with current filesystem data before writing the final skills/tool-index.md.

Prerequisites for Local Setup

Before generating the index, ensure your environment meets these requirements:

• Git repository cloned locally – The refresh scripts use git ls-files or find to locate scripts under skills/ and kali/
• PowerShell 5.1+ – Required for Windows environments to execute scripts/refresh-tool-index.ps1
• Bash shell – Required for macOS, Linux, and Kali environments to run the .sh refresh scripts
• Write permissions – The script must write to skills/tool-index.md in the repository root

Platform-Specific Setup Steps

Choose the helper script that matches your operating system. Each script performs the same core operations: reading the template, scanning for scripts with supported extensions (.ps1, .sh, .py, etc.), and writing the populated manifest.

Windows PowerShell Setup

Run the PowerShell script from the repository root to generate the index on Windows systems.

# Navigate to repository root and execute

.\scripts\refresh-tool-index.ps1

The script at scripts/refresh-tool-index.ps1 specifically handles Windows-specific tool discovery, including PowerShell modules and Windows-native binaries.

macOS and Linux Setup

For Unix-like systems excluding Kali, use the Bash script located in the skills directory.

# From repository root

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

This script uses find or git ls-files to locate executable scripts and annotates them with supported runtimes (Bash, Python, etc.).

Kali Linux Specific Setup

Kali distributions include additional penetration testing tools. Use the Kali-specific script to include these entries in the index.

# From repository root

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

The script at kali/scripts/refresh-tool-index.sh extends the standard Linux scan by adding Kali-specific tool entries and paths that are unique to the Kali Linux distribution.

Validating the Generated Manifest

After running the refresh script, verify that skills/tool-index.md contains the expected tool entries.

Open the generated file and confirm it contains a Markdown table structured as follows:

| Tool | Platform | Entry Script |
|------|----------|--------------|
| ida-reverse | Windows | scripts/ida-reverse/open.ps1 |
| wifi-wireless | Linux/macOS | scripts/wifi-wireless/start.sh |

If expected tools are missing, confirm the source scripts exist in their respective directories and re-run the platform-specific refresh script.

Using the Index in Skill Workflows

With a valid tool-index.md in place, skill definitions can resolve tool paths dynamically using helper functions.

PowerShell resolution:

$toolPath = Get-ToolPath -ToolName 'ida-reverse' -Platform 'Windows'
if (-not $toolPath) {
    Write-Error "Tool not found in tool-index.md"
    exit 1
}
& $toolPath

Bash resolution:

tool_path=$(lookup_tool "wifi-wireless" "Linux")
if [ -z "$tool_path" ]; then
    echo "Tool not found in tool-index.md"
    exit 1
fi
bash "$tool_path"

These lookups ensure that workflows execute the correct platform-specific script without hardcoding paths, making the skills portable across different environments.

Summary

• tool-index.md is a generated manifest required for the reverse-skill router to locate platform-specific scripts.
• Template source: skills/tool-index.md.template provides the base structure.
• Generation scripts: Run scripts/refresh-tool-index.ps1 (Windows), skills/scripts/refresh-tool-index.sh (macOS/Linux), or kali/scripts/refresh-tool-index.sh (Kali Linux) from the repository root.
• Validation: Check that the generated file contains a Markdown table mapping tools to their entry scripts.
• Integration: Skills use Get-ToolPath (PowerShell) or lookup_tool (Bash) to query the index at runtime.

Frequently Asked Questions

What happens if I don't generate tool-index.md before running skills?

Skills that rely on dynamic tool discovery will fail to execute. Functions like Get-ToolPath and lookup_tool query skills/tool-index.md to resolve execution paths; without this file, the router cannot locate scripts for Windows AD, IDA reverse engineering, or Kali-specific tools, resulting in path resolution errors.

Can I manually edit tool-index.md instead of using the refresh scripts?

Manual editing is possible but not recommended. The refresh scripts at scripts/refresh-tool-index.ps1 and skills/scripts/refresh-tool-index.sh ensure consistency by scanning the actual filesystem for .ps1, .sh, and .py files. Manual entries may become stale if tool locations change or new scripts are added to the repository.

How do I add a new tool to the index?

Place your new script in the appropriate subdirectory under skills/ or kali/, then re-run the refresh script for your platform. The script will automatically discover the new file and append it to the table in tool-index.md with the correct platform annotations and runtime requirements.

Why does Kali Linux have a separate refresh script?

Kali Linux includes specialized penetration testing distributions and tools that do not exist in standard Linux repositories. The script at kali/scripts/refresh-tool-index.sh adds Kali-specific entries to the index while maintaining compatibility with the base template structure, ensuring that Kali-native tools like custom exploitation scripts are properly registered alongside standard tools.

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