Specs Overview Generator Skill

Specs Overview Generator

Generate a specs/OVERVIEW.md file that catalogues all feature specs in the project's specs/ directory. This skill can create the file from scratch or fully regenerate it.

Prerequisites

A specs/ directory must exist in the project root
At least one spec subdirectory must exist with spec files (requirements.md, smolspec.md, design.md, plan.md, etc.)

Process

1. Discover Specs

List all subdirectories under specs/
Exclude specs/bugfixes/ (bug-specific specs are tracked separately)
For each directory, collect:
- Directory name (used as the spec identifier)
- Display name (derived from directory name: kebab-case to Title Case)
- Creation date (earliest git commit that added files in the directory): git log --diff-filter=A --format='%aI' -- 'specs/{dirname}/' — take the last (oldest) entry, format as YYYY-MM-DD
- Status — determined by examining the spec's task file:
  - Done — all tasks are completed (all checkboxes checked)
  - In Progress — some tasks are completed, some remain
  - Planned — tasks exist but none are completed
  - No Tasks — no tasks.md file exists
- Summary — a one-sentence description (max ~15 words) extracted from the first substantive paragraph of the primary document (check in order: requirements.md, smolspec.md, design.md, plan.md, implementation.md)
- Files — list of all .md files in the directory (exclude non-documentation artifacts like comparison-report directories)

2. Generate the Overview

The output file specs/OVERVIEW.md MUST follow this structure:

# Specs Overview

| Name | Creation Date | Status | Summary |
|------|---------------|--------|---------|
| [Spec Name](#anchor) | YYYY-MM-DD | Status | One-line summary |
...

---

## Spec Name

One-line summary.

- [filename.md](spec-dir/filename.md)
- [filename2.md](spec-dir/filename2.md)
...

Table rules:

Sort rows chronologically by creation date (oldest first)
Name column links to the detail section anchor below the table (e.g., [Spec Name](#spec-name))
Anchors are the display name lowercased with spaces replaced by hyphens

Detail section rules:

One H2 section per spec, in the same chronological order as the table
Summary line repeated below the heading
Bulleted list of all .md files in the spec directory, each linking to the file relative to specs/
Exclude non-markdown items (directories like comparison-report, .DS_Store, etc.)

3. Write the File

Write the complete file to specs/OVERVIEW.md
If the file already exists, overwrite it entirely (this is a full regeneration)

Constraints

The model MUST NOT include specs from specs/bugfixes/
The model MUST use git history for creation dates, not filesystem timestamps
The model MUST examine task files to determine status, not guess from other signals
The model SHOULD parallelize git date lookups and file reads where possible for efficiency
The model MUST NOT create any files other than specs/OVERVIEW.md

Agent Skills: Specs Overview Generator

Install this agent skill to your local