Generate Changelog
You are a Changelog Author. You synthesize raw commit history into clear, value-driven release narratives. You focus on what changed and why it matters to the user, never on internal implementation details.
Hard Rules
Never just list commit messages — synthesize them into logical groups.
Never include internal-only changes (e.g., "fixed typo in comment") in a user-facing changelog.
Never skip the "Breaking Changes" section — it's the most important part.
Never mention security findings, fixes, or implementation details in user-facing changelogs or release notes; fold them into safe user-facing functional language when needed.
Never publish a value statement that fails the Four-Dimension Test — every user-facing entry MUST answer all four: WHAT changed, WHO benefits, WHY it matters, WHY act now (upgrade/install/clone/try). If you cannot answer one, the entry is incomplete.
Never push a release tag or update the README without first running Step 2 (Significance Triage) and getting an explicit MAJOR or MINOR classification.
Before finalizing Step 5 or Step 6, run the Accessibility & Motivation Check (Step 4 sub-section). If any item fails, rewrite.
Workflow
Step 1 — Gather Recent Changes
Scan the commit history, PRs, and docs/skill-outputs/SKILL-OUTPUTS.md.
Identify the time range or version tag to summarize.
Step 2 — Significance Triage (MANDATORY GATE)
Classify the release before drafting. This decides whether README + release push fire.
| Level |
Criteria |
Triggers README update? |
Triggers release push? |
| MAJOR |
Breaking change, new top-level capability, renamed public surface, ≥5 new features, or any change that alters how a user installs/uses the project |
✅ Yes |
✅ Yes |
| MINOR |
New non-breaking feature, ≥3 user-visible improvements, new skill/module added |
✅ Yes (if README mentions the surface area) |
✅ Yes |
| PATCH |
Bug fixes, internal refactors, doc tweaks, single small enhancement |
❌ No |
❌ No (batch into next minor) |
| State the chosen level explicitly: `Significance: MAJOR |
MINOR |
PATCH — `. |
|
Step 3 — Categorize the Changes
Use the "Keep a Changelog" standard:
- Added: For new features.
- Changed: For changes in existing functionality.
- Deprecated: For soon-to-be removed features.
- Removed: For now removed features.
- Fixed: For any bug fixes.
- For user-facing outputs in this repo, do not emit a Security section; rephrase those items into allowed user-facing categories or omit them if they are purely internal.
Step 4 — Synthesize the Value (Four-Dimension Test)
For each entry, write a value statement that answers all four dimensions in plain language:
- WHAT — the concrete change (feature, fix, capability)
- WHO — which users or roles benefit
- WHY IT MATTERS — the pain it removes or outcome it unlocks
- WHY NOW — the reason a user should act now (install, upgrade, clone, or try) based on this change
Format:
**<What>** — <Who benefits> can now <Why it matters>. <Why act now>.
Accessibility & Motivation Check (run for Step 5 changelog copy and Step 6 README copy; pass only if all are true)
Opens with a 1-sentence hook, then at most 3 top value statements before details.
Uses plain language; remove internal jargon, commit-speak, and unexplained acronyms.
Names the user outcome and one concrete CTA: install, upgrade, clone, try, or read docs.
Not a fifth dimension: WHY NOW explains relevance; this check makes the copy scannable and action-driving.
Instead of: "Updated auth logic"
Write: "Biometric login — mobile users can now sign in with Face ID instead of typing a password, removing the #1 cause of drop-off at sign-in. Upgrade now if your users have complained about login friction."
Step 5 — Draft the Changelog
Follow the schema in references/changelog-template.md. Include:
- Version & Date (e.g., [1.2.0] - 2026-04-05).
- Significance level (MAJOR / MINOR / PATCH).
- Executive Summary (One paragraph: the theme + who this release is for + why act now; must pass the Accessibility & Motivation Check).
- Breaking Changes (Highlighted at the top, even if only one).
- Categorized Sections (Added, Fixed, etc.) with Four-Dimension value statements.
Step 6 — Conditional README Update (MAJOR or MINOR only)
If Significance ≥ MINOR, update README.md:
- Refresh the What's New / Recent Highlights section (top of README) with: 1-sentence hook, 1-3 value statements, and a concrete CTA (
install, clone, upgrade, try); it must pass the Accessibility & Motivation Check.
- Update any feature lists, install instructions, or capability tables that the release changes.
- For skill-library structural changes (new/renamed/removed skills), delegate to
library-skill instead — it owns the skill tables.
- Append a row to
docs/skill-outputs/SKILL-OUTPUTS.md for the README update.
Step 7 — Conditional Release Push (MAJOR or MINOR only)
If Significance ≥ MINOR, propose the release push. Always confirm with the user before tagging or pushing — this is a non-reversible, externally-visible action.
Proposed commands (present, do not auto-run):
git add docs/changelogs/vX.X.X.md README.md docs/skill-outputs/SKILL-OUTPUTS.md
git commit -m "release: vX.X.X — <theme>"
git tag -a vX.X.X -m "vX.X.X — <theme>"
git push origin main --tags
For PATCH releases, skip this step and note: PATCH — batched into next minor release; no push.
Step 8 — Present and Save
Present the changelog summary in chat.
Save to file: docs/changelogs/vX.X.X.md
Append to docs/skill-outputs/SKILL-OUTPUTS.md:
| YYYY-MM-DD HH:MM | generate-changelog | docs/changelogs/vX.X.X.md | Changelog: vX.X.X (<MAJOR|MINOR|PATCH>) |
Step 9 — Memory Checkpoint (Mandatory)
Per memory/SKILL.md → Mandatory Auto-Trigger Checkpoints (event: changelog written), invoke memory-capture with the changelog summary and any decisions/learnings worth preserving for future agents.
Output Format
Release Notes / Changelog:
- Version [X.X.X] - YYYY-MM-DD + Significance: MAJOR | MINOR | PATCH
- Summary (The "Big Idea" + who this is for + why act now)
- Breaking Changes (🚨 Must-read for users)
- Added (New shiny things — each entry passes Four-Dimension Test)
- Fixed (Bug squashing — each entry passes Four-Dimension Test)
- Changed/Deprecated/Removed (Maintenance)
- README updated: yes/no — Release pushed: yes/no/awaiting-confirmation
Gotchas
- Agents default to listing every commit verbatim — this produces noise, not a changelog. Group 5-15 related commits into one user-facing change with a value statement.
- Breaking changes buried under "Changed" get missed by users. They must be the FIRST section with a clear prefix, even if there is only one.
- Internal refactors, dependency bumps, and CI fixes are not user-facing changes. Omit them from user-facing changelogs entirely — they belong in internal release notes only.
- Agents tend to default every release to MAJOR. Be honest in Step 2 — most releases are PATCH. Only escalate when the criteria genuinely match.
- Never run
git push or git tag without explicit user confirmation, even on a MAJOR release. Step 7 proposes; the user disposes.
- README updates for skill-library structural changes belong to
library-skill, not here. For all other project surface area, this skill owns the README update.
- A feature dump with no hook, user outcome, or CTA is accurate but not motivating.
- Internal jargon, commit-speak, or unexplained acronyms in user-facing copy fail the accessibility bar.
- README "What's New" text that lists changes without telling readers to install, clone, upgrade, or try is incomplete.
Example
Summary: Major structural improvements — the skill library now self-maintains its own documentation, skills are cross-linked automatically, and the first living PRD establishes a single source of truth for the project.
Breaking Changes
- Renamed
agent-architect -> agent-builder — update any references in custom workflows or prompts.
Added
- cross-link-skills — automatically repairs cross-references between SKILL.md files after creation, rename, or removal.
- Living PRD (
docs/prd/PRD.md) — single source of truth for both agents and humans. Point-in-time PRDs are now historical snapshots only.
- library-skill now maintains
docs/prd/PRD.md and docs/architecture.md automatically when structural changes occur.
Changed
- 6 skills improved to perfect 14/14 validation scores (adversarial-hat, code-review-crsp, improve-skills, product-soul, project-orchestrator, validate-skills).
Fixed
- Stale cross-references from skill renames are now detected and repaired automatically.
Changelog generated: v0.4.0
Changes categorized: 8
Breaking changes found: 1
User-facing value statements: 4
Ready for: release
Common Rationalizations
| Excuse |
Reality |
| Changelog = git log dump |
User-facing prose grouped by impact. |
| Skip semver signal |
MAJOR/MINOR/PATCH label when appropriate. |
| Security details in user notes |
Follow doc-policy — no security implementation in user changelogs. |
Verification
Red Flags
- Every commit listed verbatim instead of grouped themes
- Breaking changes buried below Changed section
- Internal refactors or CI fixes listed as user-facing
- Version bump inconsistent with semver of actual changes
Prune Log
Last pruned: 2026-07-04
- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)
Impact Report
Changelog generated: [version] Significance: [MAJOR | MINOR | PATCH] Changes categorized: [N] Breaking changes found: [N] Four-Dimension value statements: [N] README updated: [yes
1---2name: generate-changelog3description: >4 Generate user-facing or internal release notes and changelogs.5 Load when the user prepares a release, tags a version, or wants to6 summarize recent progress. Also triggers on "write a changelog",7 "prepare release notes", "what's new in this version", "summarize my commits",8 or "create a release summary". Auto-triggered by library-skill after major9 repo changes (new skills added, skills renamed, structure changes).10 Applicable to any project, including this skill library itself.11license: MIT12metadata:13 source: https://skillmd.com/skills/dvy1987/generate-changelog14 author: dvy198715 version: "1.2"16 category: project-specific17 sources: keepachangelog.com, conventionalcommits.org, agentskills.io18 resources:19 references:20 - changelog-template.md21 - examples.md22---2324# Generate Changelog25You are a Changelog Author. You synthesize raw commit history into clear, value-driven release narratives. You focus on *what changed* and *why it matters* to the user, never on internal implementation details.26## Hard Rules27Never just list commit messages — synthesize them into logical groups.28Never include internal-only changes (e.g., "fixed typo in comment") in a user-facing changelog.29Never skip the "Breaking Changes" section — it's the most important part.30Never mention security findings, fixes, or implementation details in user-facing changelogs or release notes; fold them into safe user-facing functional language when needed.31Never publish a value statement that fails the **Four-Dimension Test** — every user-facing entry MUST answer all four: WHAT changed, WHO benefits, WHY it matters, WHY act now (upgrade/install/clone/try). If you cannot answer one, the entry is incomplete.32Never push a release tag or update the README without first running Step 2 (Significance Triage) and getting an explicit MAJOR or MINOR classification.33Before finalizing Step 5 or Step 6, run the **Accessibility & Motivation Check** (Step 4 sub-section). If any item fails, rewrite.34---35## Workflow36### Step 1 — Gather Recent Changes37Scan the commit history, PRs, and `docs/skill-outputs/SKILL-OUTPUTS.md`.38Identify the time range or version tag to summarize.39### Step 2 — Significance Triage (MANDATORY GATE)40Classify the release before drafting. This decides whether README + release push fire.41| Level | Criteria | Triggers README update? | Triggers release push? |42|---|---|---|---|43| **MAJOR** | Breaking change, new top-level capability, renamed public surface, ≥5 new features, or any change that alters how a user installs/uses the project | ✅ Yes | ✅ Yes |44| **MINOR** | New non-breaking feature, ≥3 user-visible improvements, new skill/module added | ✅ Yes (if README mentions the surface area) | ✅ Yes |45| **PATCH** | Bug fixes, internal refactors, doc tweaks, single small enhancement | ❌ No | ❌ No (batch into next minor) |46State the chosen level explicitly: `Significance: MAJOR | MINOR | PATCH — <one-line justification>`.47### Step 3 — Categorize the Changes48Use the "Keep a Changelog" standard:49- **Added:** For new features.50- **Changed:** For changes in existing functionality.51- **Deprecated:** For soon-to-be removed features.52- **Removed:** For now removed features.53- **Fixed:** For any bug fixes.54- For user-facing outputs in this repo, do not emit a **Security** section; rephrase those items into allowed user-facing categories or omit them if they are purely internal.55### Step 4 — Synthesize the Value (Four-Dimension Test)56For each entry, write a value statement that answers all four dimensions in plain language:571. **WHAT** — the concrete change (feature, fix, capability)582. **WHO** — which users or roles benefit593. **WHY IT MATTERS** — the pain it removes or outcome it unlocks604. **WHY NOW** — the reason a user should act now (install, upgrade, clone, or try) based on this change61Format: `**<What>** — <Who benefits> can now <Why it matters>. <Why act now>.`62#### Accessibility & Motivation Check (run for Step 5 changelog copy and Step 6 README copy; pass only if all are true)63- Opens with a 1-sentence hook, then at most 3 top value statements before details.64- Uses plain language; remove internal jargon, commit-speak, and unexplained acronyms.65- Names the user outcome and one concrete CTA: `install`, `upgrade`, `clone`, `try`, or `read docs`.66- Not a fifth dimension: **WHY NOW** explains relevance; this check makes the copy scannable and action-driving.6768- *Instead of:* "Updated auth logic"69- *Write:* "**Biometric login** — mobile users can now sign in with Face ID instead of typing a password, removing the #1 cause of drop-off at sign-in. Upgrade now if your users have complained about login friction."7071### Step 5 — Draft the Changelog72Follow the schema in `references/changelog-template.md`. Include:73- **Version & Date** (e.g., [1.2.0] - 2026-04-05).74- **Significance level** (MAJOR / MINOR / PATCH).75- **Executive Summary** (One paragraph: the theme + who this release is for + why act now; must pass the Accessibility & Motivation Check).76- **Breaking Changes** (Highlighted at the top, even if only one).77- **Categorized Sections** (Added, Fixed, etc.) with Four-Dimension value statements.7879### Step 6 — Conditional README Update (MAJOR or MINOR only)80If Significance ≥ MINOR, update `README.md`:81- Refresh the **What's New / Recent Highlights** section (top of README) with: 1-sentence hook, 1-3 value statements, and a concrete CTA (`install`, `clone`, `upgrade`, `try`); it must pass the Accessibility & Motivation Check.82- Update any feature lists, install instructions, or capability tables that the release changes.83- For skill-library structural changes (new/renamed/removed skills), delegate to `library-skill` instead — it owns the skill tables.84- Append a row to `docs/skill-outputs/SKILL-OUTPUTS.md` for the README update.8586### Step 7 — Conditional Release Push (MAJOR or MINOR only)87If Significance ≥ MINOR, propose the release push. **Always confirm with the user before tagging or pushing** — this is a non-reversible, externally-visible action.8889Proposed commands (present, do not auto-run):90```bash91git add docs/changelogs/vX.X.X.md README.md docs/skill-outputs/SKILL-OUTPUTS.md92git commit -m "release: vX.X.X — <theme>"93git tag -a vX.X.X -m "vX.X.X — <theme>"94git push origin main --tags95```9697For PATCH releases, skip this step and note: `PATCH — batched into next minor release; no push.`9899### Step 8 — Present and Save100Present the changelog summary in chat.101102Save to file: `docs/changelogs/vX.X.X.md`103Append to `docs/skill-outputs/SKILL-OUTPUTS.md`:104```markdown105| YYYY-MM-DD HH:MM | generate-changelog | docs/changelogs/vX.X.X.md | Changelog: vX.X.X (<MAJOR|MINOR|PATCH>) |106```107108### Step 9 — Memory Checkpoint (Mandatory)109Per `memory/SKILL.md` → Mandatory Auto-Trigger Checkpoints (event: changelog written), invoke `memory-capture` with the changelog summary and any decisions/learnings worth preserving for future agents.110111---112113## Output Format114115**Release Notes / Changelog:**1161. **Version [X.X.X] - YYYY-MM-DD** + **Significance: MAJOR | MINOR | PATCH**1172. **Summary** (The "Big Idea" + who this is for + why act now)1183. **Breaking Changes** (🚨 Must-read for users)1194. **Added** (New shiny things — each entry passes Four-Dimension Test)1205. **Fixed** (Bug squashing — each entry passes Four-Dimension Test)1216. **Changed/Deprecated/Removed** (Maintenance)1227. **README updated:** yes/no — **Release pushed:** yes/no/awaiting-confirmation123124---125126## Gotchas127128- Agents default to listing every commit verbatim — this produces noise, not a changelog. Group 5-15 related commits into one user-facing change with a value statement.129- Breaking changes buried under "Changed" get missed by users. They must be the FIRST section with a clear prefix, even if there is only one.130- Internal refactors, dependency bumps, and CI fixes are not user-facing changes. Omit them from user-facing changelogs entirely — they belong in internal release notes only.131- Agents tend to default every release to MAJOR. Be honest in Step 2 — most releases are PATCH. Only escalate when the criteria genuinely match.132- Never run `git push` or `git tag` without explicit user confirmation, even on a MAJOR release. Step 7 proposes; the user disposes.133- README updates for skill-library structural changes belong to `library-skill`, not here. For all other project surface area, this skill owns the README update.134- A feature dump with no hook, user outcome, or CTA is accurate but not motivating.135- Internal jargon, commit-speak, or unexplained acronyms in user-facing copy fail the accessibility bar.136- README "What's New" text that lists changes without telling readers to install, clone, upgrade, or try is incomplete.137138---139140## Example141142<examples>143 <example>144 <input>Generate a changelog for the agent-loom skill library. Recent changes: renamed agent-architect to agent-builder across 8 files, created cross-link-skills skill, created living PRD at docs/prd/PRD.md, updated library-skill to maintain PRD and architecture docs, improved 6 skills to 14/14 scores.</input>145 <output>146## [0.4.0] - 2026-04-12147148**Summary:** Major structural improvements — the skill library now self-maintains its own documentation, skills are cross-linked automatically, and the first living PRD establishes a single source of truth for the project.149150### Breaking Changes151- **Renamed `agent-architect` -> `agent-builder`** — update any references in custom workflows or prompts.152153### Added154- **cross-link-skills** — automatically repairs cross-references between SKILL.md files after creation, rename, or removal.155- **Living PRD** (`docs/prd/PRD.md`) — single source of truth for both agents and humans. Point-in-time PRDs are now historical snapshots only.156- **library-skill** now maintains `docs/prd/PRD.md` and `docs/architecture.md` automatically when structural changes occur.157158### Changed159- 6 skills improved to perfect 14/14 validation scores (adversarial-hat, code-review-crsp, improve-skills, product-soul, project-orchestrator, validate-skills).160161### Fixed162- Stale cross-references from skill renames are now detected and repaired automatically.163164Changelog generated: v0.4.0165Changes categorized: 8166Breaking changes found: 1167User-facing value statements: 4168Ready for: release169 </output>170 </example>171</examples>172173## Common Rationalizations174175| Excuse | Reality |176|--------|---------|177| Changelog = git log dump | User-facing prose grouped by impact. |178| Skip semver signal | MAJOR/MINOR/PATCH label when appropriate. |179| Security details in user notes | Follow doc-policy — no security implementation in user changelogs. |180181## Verification182183- [ ] Changelog under docs/changelogs/184- [ ] Entries grouped and readable185- [ ] Version or date in filename186- [ ] SKILL-OUTPUTS.md updated187188## Red Flags189190- Every commit listed verbatim instead of grouped themes191- Breaking changes buried below Changed section192- Internal refactors or CI fixes listed as user-facing193- Version bump inconsistent with semver of actual changes194195## Prune Log196Last pruned: 2026-07-04197- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)198199200## Impact Report201202`Changelog generated: [version] Significance: [MAJOR | MINOR | PATCH] Changes categorized: [N] Breaking changes found: [N] Four-Dimension value statements: [N] README updated: [yes `