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

The tool-index.md file is auto-generated by platform-specific scripts that recursively scan the repository for 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 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, the search targets files named exactly 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 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 – A human-readable markdown table with columns for Tool, Description, Platform, and Entry Script
2. tool-index.json – A machine-readable JSON structure for programmatic consumption by skills/config/routing.json

According to the source in skills/scripts/refresh-tool-index.sh lines 15–16, the script accepts optional arguments to override default output locations:

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. 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 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, 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:

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

# From repository root in PowerShell

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

Kali Linux:

# 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 files, ensuring skills/INDEX.md and the routing configuration always reflect the actual repository state.

Summary

• Scanning logic: Scripts recursively discover SKILL.md files across skills/ subdirectories using platform-native filesystem APIs.
• Dual output: Every execution generates both tool-index.md (human-readable tables) and tool-index.json (machine-readable data for 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 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 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 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 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 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.

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