How to Refresh the Tool Index in reverse-skill: Complete Guide

You can refresh the tool index in reverse-skill by running the platform-specific refresh script that scans the skills/ directory for SKILL.md files and regenerates skills/INDEX.md along with the routing cache.

The reverse-skill repository by zhaoxuya520 maintains a centralized tool index that catalogs every available skill definition. To refresh the tool index in reverse-skill after adding, removing, or modifying capabilities, you execute a maintenance script that rebuilds the metadata catalogue without touching external systems or secrets.

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 canonical registry of all skills in the repository. According to the reverse-skill source code, the index is constructed by recursively scanning the skills/ directory for files named SKILL.md, extracting their titles, descriptions, tags, and routing information, and compiling them into a structured reference document.

How the Refresh Scripts Work

When you refresh the tool index in reverse-skill, the automation performs four discrete operations:

1. Discover skills – The script recursively walks the skills/ tree and locates every SKILL.md definition.
2. Parse metadata – It extracts the skill’s title, description, tags, and routing configuration from each discovered file.
3. Generate index – The script writes a formatted markdown table or list to skills/INDEX.md, replacing the previous version.
4. Update routing cache – It regenerates skills/config/routing.json so the routing engine immediately recognizes new or changed entries.

This process is read-only with respect to external resources and only writes to the two output files mentioned above.

Step-by-Step Instructions to Refresh the Tool Index

Choose the command that matches your operating system and run it from the repository root.

Linux and macOS

Execute the Bash implementation that ships with the repository:

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

Windows PowerShell

For Windows environments, use the PowerShell implementation with bypassed execution policy:

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

Kali Linux

Kali users can invoke the distribution-specific wrapper that delegates to the main Bash logic:

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

After execution, the terminal displays a brief log indicating how many skill files were processed and confirming that skills/INDEX.md was updated.

Key Files Involved in the Refresh Process

Understanding the file layout helps troubleshoot issues when you refresh the tool index in reverse-skill manually or via CI/CD.

• skills/scripts/refresh-tool-index.sh – The Bash implementation of the refresh logic.
• skills/scripts/refresh-tool-index.ps1 – The PowerShell implementation for Windows hosts.
• kali/scripts/refresh-tool-index.sh – A Kali-specific wrapper that calls the main Bash script.
• skills/INDEX.md – The generated tool index consumed by the routing engine.
• skills/config/routing.json – The cached routing configuration regenerated during the refresh.

Summary

• The tool index is stored in skills/INDEX.md and lists every SKILL.md discovered in the skills/ directory.
• 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 to rebuild it.
• The process updates skills/config/routing.json automatically so the routing engine stays synchronized.
• The operation is safe and idempotent; it only reads repository files and writes the index and cache.

Frequently Asked Questions

What happens if I modify a skill but don't refresh the tool index?

The routing engine continues to use stale metadata from the last generated skills/INDEX.md and skills/config/routing.json. Your changes will not be visible or accessible until you run the refresh script to rebuild the tool index in reverse-skill.

Is it safe to run the refresh script multiple times?

Yes. According to the reverse-skill source code, the refresh scripts are idempotent and only perform read operations on the skills/ directory followed by writes to skills/INDEX.md and skills/config/routing.json. No external commands or secrets are accessed.

Do I need special permissions to refresh the tool index?

You only need standard filesystem read access to the skills/ directory and write access to skills/INDEX.md and skills/config/routing.json. No administrative privileges or API keys are required to execute the refresh scripts.

Can I refresh the tool index manually without the scripts?

While possible, manual editing is discouraged because skills/INDEX.md must maintain strict formatting consistency with the routing expectations in skills/config/routing.json. The scripts ensure that both files remain synchronized by parsing the actual SKILL.md sources rather than relying on hand-edited entries.

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