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

extract-summaries.ps1 is a PowerShell utility that automatically builds the repository-wide navigation file 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 navigation index in the zhaoxuya520/reverse-skill repository. Rather than maintaining this central index manually, developers edit individual module 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 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 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 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 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 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 matches generated content
• Exits with status 1 if drift detected (failing CI builds)

---

Running extract-summaries.ps1

Regenerate INDEX.md After Module Edits

# Standard regeneration (development workflow)

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

Run this after modifying any SKILL.md front-matter to propagate changes to the central index.

Validate INDEX.md in CI Pipelines

# 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:

# 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 existence; prompts to run extractor if missing
skills/scripts/test-routing.ps1	CI regression suite expecting up-to-date INDEX.md
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, the extractor regenerates INDEX.md, and CI validators ensure synchronization.

---

Summary

• extract-summaries.ps1 is the authoritative generator for skills/INDEX.md—no manual edits permitted
• Front-matter driven: Reads name and description from each module's 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?

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 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 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 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, 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 files entirely into memory. All valid front-matter blocks are expected within this window.

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