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

> Learn to use extract-summaries.ps1 with the -Check flag to regenerate INDEX.md without drift. Keep your project synchronized and prevent CI failures.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Running `extract-summaries.ps1` with the `-Check` flag ensures [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) stays synchronized with your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file to build a fresh markdown table from their YAML front-matter. This workflow guarantees that [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md).

When invoked with `-Check`, the script generates the content in memory, strips CRLF sequences from the existing [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) after editing skill descriptions or adding new modules, run the script from the repository root:

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

```

This command rewrites [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) with the latest front-matter extracted from all [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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:

```yaml
- 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

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

2. Run the regeneration command to update [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md).
3. Commit both the new [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and the updated [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) manually** – always use `extract-summaries.ps1` to regenerate it from [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files.