# How tool-index.md Auto-Generation Works Across Different Platforms

> Discover how tool-index.md auto-generation works. Learn how scripts scan repositories for SKILL.md files, extract metadata, and create markdown indexes and JSON manifests across platforms.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-28

---

**The [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) file is auto-generated by platform-specific scripts that recursively scan the repository for [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files, extract metadata, and output both a markdown index and a JSON manifest.**

The reverse-skill repository maintains a dynamic catalogue of penetration testing skills through automated indexing. The [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) auto-generation system ensures the documentation stays synchronized with the actual skill definitions by parsing structured metadata from individual skill files and compiling them into cross-platform compatible indices.

## Core Architecture of the Index Generation

All platform implementations share a three-phase pipeline for consolidating skill definitions.

### Discovery Phase

The scripts locate candidate skill definitions by recursively walking the `skills/` directory structure. In [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh), the search targets files named exactly [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) using native filesystem traversal utilities. This recursive scan ensures that skills organized in nested subdirectories are automatically included without manual registration.

### Metadata Extraction

Each discovered [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) follows a strict formatting convention. The scripts parse the raw text to extract:
- **Tool name** – derived from the first markdown heading
- **Description** – extracted from block comments or introductory paragraphs
- **Supported platforms** – identified through platform tags
- **Entry-point script** – the executable path for invoking the skill

The extraction uses platform-appropriate text processing: POSIX utilities like `grep` and `sed` in the Bash implementations, and regex-based parsing via PowerShell in the Windows version.

### Output Generation

The pipeline produces two synchronized artifacts:
1. **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** – A human-readable markdown table with columns for Tool, Description, Platform, and Entry Script
2. **[`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json)** – A machine-readable JSON structure for programmatic consumption by [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)

According to the source in [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) lines 15–16, the script accepts optional arguments to override default output locations:

```bash
OUTPUT_MD="${1:-${SKILL_ROOT}/tool-index.md}"
OUTPUT_JSON="${2:-${SKILL_ROOT}/tool-index.json}"

```

## Platform-Specific Script Implementations

### Linux and macOS

The primary implementation resides in [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh). This Bash script determines the repository root, sets default output paths using parameter expansion, and executes the discovery-extraction-aggregation pipeline. Line 151 emits a verification log entry confirming the script execution path, ensuring auditability in automated CI/CD environments.

### Windows PowerShell

Windows environments use `skills/scripts/refresh-tool-index.ps1`, referenced at line 228 of the Linux script for parity checking. This PowerShell implementation mirrors the Bash logic using `Get-ChildItem -Recurse` to locate [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files and generates identical markdown table and JSON structures, ensuring functional equivalence across operating systems.

### Kali Linux Wrapper

Kali-specific deployments utilize [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh), which functions as a thin wrapper around the generic Linux script. At line 24, this wrapper injects a localized Chinese-language header (`- 说明: 本表由 'kali/scripts/refresh-tool-index.sh' 自动生成`) into the generated output before delegating to the core generation logic. This maintains consistency with the main codebase while providing locale-specific documentation.

## Running the Generation Scripts

Regenerate the indices manually when adding new skills to ensure immediate availability.

**Linux/macOS:**

```bash

# From repository root with defaults

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

# With custom output paths

bash skills/scripts/refresh-tool-index.sh custom-index.md custom-index.json

```

**Windows:**

```powershell

# From repository root in PowerShell

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

```

**Kali Linux:**

```bash

# From repository root

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

```

The generation process is fully idempotent—re-running any script overwrites existing index files with fresh data parsed directly from the current [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files, ensuring [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) and the routing configuration always reflect the actual repository state.

## Summary

- **Scanning logic**: Scripts recursively discover [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files across `skills/` subdirectories using platform-native filesystem APIs.
- **Dual output**: Every execution generates both [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) (human-readable tables) and [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) (machine-readable data for [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)).
- **Cross-platform parity**: Bash implementations handle Linux, macOS, and Kali, while a dedicated PowerShell script serves Windows environments with identical functionality.
- **Configurable destinations**: The Linux script accepts positional arguments to override default output paths, enabling custom integration workflows.
- **Zero manual maintenance**: Adding a properly formatted [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file automatically exposes the tool in the index upon the next script execution.

## Frequently Asked Questions

### What triggers the tool-index.md regeneration?

The index does not update automatically on file changes. You must manually execute the appropriate platform script ([`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) or `refresh-tool-index.ps1`) or configure a git hook or CI pipeline to run the script after commits. The scripts are designed to be idempotent and safe to run repeatedly.

### Can I customize the output location for the generated indices?

Yes. The Linux and macOS script in [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) accepts two optional positional arguments. The first specifies the markdown output path and the second specifies the JSON output path. If omitted, the script defaults to `${SKILL_ROOT}/tool-index.md` and `${SKILL_ROOT}/tool-index.json` respectively.

### How does the Kali version differ from the standard Linux script?

The Kali-specific wrapper at [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh) is functionally identical to the generic Linux version but prepends a Chinese-language explanatory header to the generated output. It ultimately delegates the actual indexing work to the shared core logic, ensuring consistency while supporting localized documentation requirements.

### Why are both markdown and JSON outputs generated?

The markdown table serves human readers browsing the repository documentation, while the JSON structure is consumed programmatically by [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and other automation tools to route tasks to appropriate skill entry points without parsing markdown tables. This dual-format approach supports both manual inspection and machine integration.