How to Use extract-summaries.ps1 to Regenerate INDEX.md Without Drift

Running extract-summaries.ps1 with the -Check flag ensures skills/INDEX.md stays synchronized with your SKILL.md files by failing CI when the index drifts from the generated output.

In the zhaoxuya520/reverse-skill repository, the navigation index is never edited by hand. Instead, the PowerShell script skills/scripts/extract-summaries.ps1 acts as the single source of truth, scanning every SKILL.md file to build a fresh markdown table from their YAML front-matter. This workflow guarantees that INDEX.md remains an accurate, deterministic reflection of the codebase.

How the Script Works

According to the source code in skills/scripts/extract-summaries.ps1, the tool performs an idempotent generation workflow:

1. Discovery – It locates all tracked SKILL.md files (or falls back to a filesystem walk) while excluding internal directories such as ops, scripts, and tests.
2. Parsing – For each file, it extracts the name and description fields from YAML front-matter. If name is absent, it falls back to the containing directory name, truncating descriptions that exceed length limits.
3. Normalization – The script converts line endings to LF and writes the output using UTF-8 with BOM for cross-platform consistency.
4. Output – It generates both a markdown table and a directory tree inside skills/INDEX.md.

When invoked with -Check, the script generates the content in memory, strips CRLF sequences from the existing skills/INDEX.md, and performs a string comparison. If the files match, it prints "INDEX.md up to date" and exits with code 0; otherwise, it prints a warning and exits with code 1, signaling drift.

Regenerating the Index Locally

To update INDEX.md after editing skill descriptions or adding new modules, run the script from the repository root:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/extract-summaries.ps1

This command rewrites skills/INDEX.md with the latest front-matter extracted from all SKILL.md files. Because the generation is deterministic, running the script repeatedly produces identical byte-for-byte output.

Validating Without Rewriting (Drift Detection)

For CI pipelines or pre-commit hooks, use the -Check switch to validate that the committed index matches the generated version without modifying the file:

powershell -File skills/scripts/extract-summaries.ps1 -Check

• Exit code 0: The index is current.
• Exit code 1: Drift detected; run the regeneration command above and commit the changes.

GitHub Actions Example

Add this step to your workflow to block merges on stale indices:

- name: Verify INDEX.md is current
  run: |
    powershell -File skills/scripts/extract-summaries.ps1 -Check
  shell: pwsh

If this job fails, developers must run the local regeneration command and push the updated skills/INDEX.md.

Adding a New Skill Without Causing Drift

When creating a new skill module, follow this sequence to keep the index synchronized:

1. Create skills/<module-name>/SKILL.md with a front-matter block containing the required fields:

   ---
   name: Example Skill
   description: |
     A concise one-sentence description of what this skill does.
   ---

2. Run the regeneration command to update skills/INDEX.md.

3. Commit both the new SKILL.md and the updated INDEX.md together.

Skipping step 2 will cause the -Check validation to fail in CI, preventing the drift from entering the main branch.

Summary

• Never edit skills/INDEX.md manually – always use extract-summaries.ps1 to regenerate it from SKILL.md front-matter.
• Use -Check in CI to enforce that the committed index matches the derived output, exiting with code 1 on any discrepancy.
• The script normalizes line endings to LF and uses UTF-8 with BOM, ensuring deterministic output across Windows, macOS, and Linux.
• Add the regenerated INDEX.md to the same commit that introduces new skills or updates descriptions to maintain a drift-free history.

Frequently Asked Questions

What happens if I forget to run the script after editing a SKILL.md file?

The next CI run executing extract-summaries.ps1 -Check will exit with a non-zero status, blocking the merge until you regenerate INDEX.md and commit the changes.

Can I run the script on Linux or macOS?

Yes. The script is compatible with PowerShell Core (pwsh). Line endings are normalized to LF during generation, so the output is deterministic across all platforms.

Why does the script use UTF-8 with BOM instead of plain UTF-8?

The BOM (Byte Order Mark) ensures that Windows-based editors and legacy tools correctly identify the file encoding when reading the generated INDEX.md, while the drift-detection logic strips CRLF to maintain cross-platform consistency.

Which directories does the script ignore during discovery?

The script excludes internal infrastructure folders including ops, scripts, and tests during its filesystem traversal, focusing only on skill directories containing SKILL.md files.

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