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

> Learn how to set up tool-index.md for local environment validation in reverse-skill. Run refresh scripts to scan your filesystem and populate the manifest automatically.

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

---

**Create a local [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```powershell

# 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.

```bash

# 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.

```bash

# From repository root

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

```

The script at [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) contains the expected tool entries.

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

```markdown
| 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) in place, skill definitions can resolve tool paths dynamically using helper functions.

**PowerShell resolution:**

```powershell
$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:**

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (macOS/Linux), or [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.