How to Refresh the Tool Index in reverse-skill After Installing New Tools

To refresh the tool index in reverse-skill after installing new tools, run the platform-specific refresh script located in skills/scripts/ or kali/scripts/ to regenerate skills/INDEX.md and update the routing cache.

The reverse-skill repository maintains a centralized tool index that catalogs all available security testing skills. When you add, remove, or modify tools in the skills/ directory, you must refresh the tool index to ensure the routing engine recognizes the changes. This process rebuilds the metadata cache and updates the navigation structure used by the application.

What Is the Tool Index in reverse-skill?

The tool index is a generated markdown file located at skills/INDEX.md that serves as the master catalog for all available skills. According to the reverse-skill source code, this index is constructed by scanning the skills/ directory recursively for SKILL.md definition files. Each discovered skill contributes its metadata—including title, description, tags, and routing information—to the consolidated index.

The index file acts as the single source of truth for the routing engine. Without refreshing it after installation, newly added tools remain invisible to the system even if their files exist in the directory structure.

How the Refresh Tool Index Scripts Work

The refresh process follows a deterministic four-step pipeline implemented in the platform-specific scripts. Understanding this flow helps diagnose issues when the index fails to update correctly.

Step 1: Discover Skills

The script recursively walks the skills/ directory tree and identifies every SKILL.md file. This discovery phase ensures that nested skill directories and newly created tool folders are included in the scan regardless of their depth in the hierarchy.

Step 2: Parse Metadata

For each discovered SKILL.md, the script extracts structured metadata including the skill title, description, category tags, and routing endpoints. This parsing phase validates that each skill definition contains the required fields before inclusion in the index.

Step 3: Generate Index

The script writes a structured markdown table or list to skills/INDEX.md, organizing skills by category and including hyperlinks to their respective documentation. This regenerated file replaces the previous index completely, ensuring no stale entries remain.

Step 4: Update Routing Cache

Finally, the script regenerates skills/config/routing.json, which serves as the cached routing configuration consumed by the reverse-skill engine. This cache update makes the new tools immediately accessible through the application's command interface without requiring a restart.

Refreshing the Tool Index on Linux and macOS

For Unix-based systems including Linux distributions and macOS, use the Bash implementation located in the standard scripts directory.

# From the repository root

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

The script outputs a processing log indicating how many SKILL.md files were discovered and confirms when skills/INDEX.md has been updated. It requires only read permissions for the skills/ directory and write permissions for skills/INDEX.md and skills/config/routing.json.

Refreshing the Tool Index on Windows

Windows users should use the PowerShell implementation with bypassed execution policies to avoid signature restrictions.

# From the repository root

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

This script performs identical logic to the Bash version, parsing the same skills/ directory structure and generating the same output files. Ensure you run PowerShell from the repository root so relative paths resolve correctly.

Refreshing the Tool Index on Kali Linux

Kali Linux deployments include a specific wrapper script in the dedicated kali/ directory. This wrapper calls the main Bash script but may include environment-specific configurations for penetration testing workflows.

# From the repository root

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

Use this variant when working within the Kali-specific branch of the repository, as it ensures compatibility with the Kali Linux file structure and pre-installed dependencies.

Summary

• The tool index is stored at skills/INDEX.md and catalogs all available skills by scanning for SKILL.md files.
• Run skills/scripts/refresh-tool-index.sh on Linux/macOS, skills/scripts/refresh-tool-index.ps1 on Windows, or kali/scripts/refresh-tool-index.sh on Kali Linux to refresh the index.
• The refresh process updates both skills/INDEX.md and skills/config/routing.json to reflect current tool availability.
• The scripts are read-only regarding external systems and safe to execute multiple times without side effects.

Frequently Asked Questions

Where is the tool index file located in reverse-skill?

The generated tool index is written to skills/INDEX.md in the repository root. This file serves as the master catalog that the routing engine consults to locate available skills and their metadata.

What file does the refresh script update besides INDEX.md?

The refresh script also regenerates skills/config/routing.json, which acts as a cached routing configuration. This JSON cache provides the routing engine with fast access to endpoint mappings without requiring repeated markdown parsing during runtime.

Is it safe to run the refresh tool index script multiple times?

Yes, running the refresh script is idempotent and safe. It only reads files within the skills/ directory and writes to skills/INDEX.md and skills/config/routing.json. No external commands are executed, and no sensitive credentials or system configurations are modified during the process.

Do I need to restart the application after refreshing the tool index?

No, you do not need to restart the application. Because the refresh script updates skills/config/routing.json, the routing engine picks up the new configuration immediately on the next request, making newly installed tools available instantly.

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