# How `extract-summaries.ps1` Generates and Maintains `skills/INDEX.md`

> Learn how extract-summaries.ps1 automatically generates and updates the skills INDEX md file by scanning module metadata. Maintain your repository navigation effortlessly.

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

---

**`extract-summaries.ps1` is a PowerShell utility that automatically builds the repository-wide navigation file [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) by scanning module metadata and regenerating the index on every run.**

The `extract-summaries.ps1` script serves as the single source of truth generator for the [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) navigation index in the `zhaoxuya520/reverse-skill` repository. Rather than maintaining this central index manually, developers edit individual module [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files and rely on this script to propagate changes upstream. This design ensures consistency across dozens of reverse-engineering skill modules without risking human error in cross-referencing.

---

## What `extract-summaries.ps1` Does

The script performs six core functions to keep [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) synchronized with module metadata.

### 1. Scans SKILL.md Front-Matter for Name and Description

At `skills/scripts/extract-summaries.ps1` lines 2-6, the script defines its extraction target: every module's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) must contain YAML front-matter with `name` and `description` fields. These fields become the module's display name and summary in the generated index.

### 2. Regenerates INDEX.md Idempotently

The script produces **bit-for-bit identical output** on repeated runs with unchanged inputs (lines 3-4). This property enables CI systems to detect drift by simple file comparison—if [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) differs from freshly generated content, a module edit was forgotten.

### 3. Selectively Discovers SKILL.md Files

The script implements a two-tier discovery strategy (lines 21-35):

- **Git-tracked files preferred** — Uses `git ls-files` for clean, clone-accurate results
- **Recursive fallback** — Falls back to `Get-ChildItem -Recurse` when Git is unavailable

This ensures the script works in CI environments with full Git history and in constrained build containers alike.

### 4. Parses Front-Matter with Line Limits and Defaults

Between lines 46-66, the script reads only the **first 15 lines** of each [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) for performance, then:

- Extracts the `name` field
- Handles multi-line `description` values including YAML block scalars
- Defaults missing `name` to the parent directory name
- Defaults missing `description` to `(无摘要)` ("no summary")

### 5. Composes INDEX.md with Multiple Sections

The output generation (lines 75-101) creates four distinct blocks:

| Section | Content |
|---------|---------|
| Header banner | Auto-generation warning with script path |
| Module overview table | Linked module names with descriptions |
| Directory tree | Plain-text tree view for quick navigation |
| Routing reference | Pointer to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as primary routing source |

### 6. Supports Check-Mode for CI Validation

When invoked with `-Check` (lines 8-21), the script validates rather than writes:

- Exits with status **0** if [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) matches generated content
- Exits with status **1** if drift detected (failing CI builds)

---

## Running `extract-summaries.ps1`

### Regenerate INDEX.md After Module Edits

```powershell

# Standard regeneration (development workflow)

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

```

Run this after modifying any [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) front-matter to propagate changes to the central index.

### Validate INDEX.md in CI Pipelines

```powershell

# Drift detection (CI workflow)

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

```

This pattern integrates with GitHub Actions, Azure Pipelines, or any system that fails builds on non-zero exit codes.

---

## Generated INDEX.md Structure

The script produces a file matching this pattern:

```markdown

# reverse-skill 技能导航索引

> 本文件由 `skills/scripts/extract-summaries.ps1` 自动生成，**请勿手改**。
> 修改摘要请编辑对应模块 `SKILL.md` 的 frontmatter `description`，然后重跑脚本。

## 模块总览

| 模块 | 摘要 |
|------|------|
| [APK Reverse](skills/apk-reverse/SKILL.md) | 自动化 Android 逆向工作流 … |
| [IDA Reverse](skills/ida-reverse/SKILL.md) | 基于 IDA Pro 的二进制分析 … |

## 目录树

```

skills/apk-reverse/
skills/ida-reverse/

```

## 路由

PRIMARY 路由由 `skills/config/routing.json`（唯一事实源）驱动…

```

The warning comment explicitly discourages manual edits, directing developers to the source-metadata workflow.

---

## Integration with Related Scripts

The `extract-summaries.ps1` utility operates within a broader validation ecosystem:

| Script | Role in INDEX.md Maintenance |
|--------|------------------------------|
| `skills/scripts/verify-routing-coherence.ps1` | Checks [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) existence; prompts to run extractor if missing |
| `skills/scripts/test-routing.ps1` | CI regression suite expecting up-to-date [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Primary routing source; referenced in generated INDEX |
| `skills/**/SKILL.md` | Per-module metadata consumed by extractor |

According to the `zhaoxuya520/reverse-skill` source code, these components form a closed loop: module authors edit [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), the extractor regenerates [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md), and CI validators ensure synchronization.

---

## Summary

- **`extract-summaries.ps1`** is the authoritative generator for [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md)—no manual edits permitted
- **Front-matter driven**: Reads `name` and `description` from each module's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) (first 15 lines)
- **Git-aware discovery**: Prefers `git ls-files`, falls back to recursive search
- **Idempotent output**: Enables CI drift detection via simple file comparison
- **Check-mode validation**: `-Check` flag exits 0 (clean) or 1 (dirty) for pipeline integration
- **Multi-section output**: Table, tree view, and routing reference in one file

---

## Frequently Asked Questions

### What happens if I manually edit [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md)?

Your changes will be overwritten the next time anyone runs `extract‑summaries.ps1`. The generated file includes a prominent warning in Chinese: "**请勿手改**" (do not edit manually). Always modify the source [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) front-matter instead.

### Can the script run without Git installed?

Yes. When `git` is unavailable, the script falls back to `Get‑ChildItem ‑Recurse` to discover [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files (lines 21-35). However, this may include untracked or ignored files that `git ls‑files` would exclude.

### How does CI detect if [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) is out of date?

Run `powershell ‑File skills/scripts/extract‑summaries.ps1 ‑Check`. The script regenerates content in memory, compares against the checked‑in [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md), and exits with status **1** if they differ—standard behavior for failing a build pipeline.

### Why limit front-matter parsing to 15 lines?

Performance and robustness. According to the implementation at lines 46-66, reading only the first 15 lines avoids loading large [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files entirely into memory. All valid front-matter blocks are expected within this window.