generate-changelog
Skill4 starsChanged 3 months agoMITView on GitHub
Generate user-facing or internal release notes and changelogs. Load when the user prepares a release, tags a version, or wants to summarize recent progress. Also triggers on "write a changelog", "prepare release notes", "what's new in this version", "summarize my commits", or "create a release summary". Auto-triggered by library-skill after major repo changes (new skills added, skills renamed, structure changes). Applicable to any project, including this skill library itself.
- Commits and pushes
5 other projects use a version of this.
Adopted by
Most recently taken up by
- open-edge-platform/edge-ai-librariestheir own version, first seen Oct 8, 2026
- deepsense-ai/ragbitstheir own version, first seen Oct 8, 2026
- danbooru/danboorutheir own version, first seen Oct 8, 2026
- microsoft/dbt-fabricsparktheir own version, first seen Jul 5, 2026
- maslennikov-ig/claude-code-orchestrator-kittheir own version, first seen Mar 5, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- danbooru/danbooru★ 2.9ksame name
- deepsense-ai/ragbits★ 1.7ksame name
- maslennikov-ig/claude-code-orchestrator-kit★ 248same name
- open-edge-platform/edge-ai-libraries★ 178same name
- microsoft/dbt-fabricspark★ 72same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository125 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/agent-loom-routing.mdcCursor rule
- .cursor/rules/agent-loom-skills-index.mdcCursor rule
- adversarial-hatSkill
- agent-builderSkill
- agent-launcherSkill
- agent-loom-syncSkill
- agent-observabilitySkill
- agent-run-retroSkill
- agent-system-architectureSkill
- api-and-interface-designSkill
- api-deprecation-and-migrationSkill
- apply-paper-to-projectSkill
- app-security-hardeningSkill
- architectural-decision-logSkill
- assumption-mappingSkill
- brainstormingSkill
- browser-testing-with-devtoolsSkill
- business-modelingSkill
- ci-cd-and-automationSkill
- codebase-understandingSkill
- code-review-crspSkill
- code-simplificationSkill
- compress-skillSkill
- context-engineeringSkill
- create-agent-promptSkill
- cross-link-skillsSkill
- customer-discoverySkill
- debug-and-fixSkill
- deep-thinkingSkill
- dependency-mappingSkill
- deploy-anywhereSkill
- deprecate-skillSkill
- design-directionSkill
- design-reviewSkill
- design-systemSkill
- dynamic-routingSkill
- eval-judgeSkill
- eval-outputSkill
- eval-pipelineSkill
- eval-rubric-designSkill
- experimentationSkill
- experiment-backlogSkill
- experiment-readoutSkill
- experiment-runbookSkill
- experiment-specSkill
- fault-localizeSkill
- feature-specSkill
- fermiSkill
- first-principlesSkill
- frontend-designSkill
- git-workflow-and-versioningSkill
- gsap-animationSkill
- harness-engineeringSkill
- harness-evolutionSkill
- harness-generationSkill
- idea-evaluationSkill
- idea-generationSkill
- implementation-planSkill
- improve-skillsSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 14 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Never just list commit messages — synthesize them into logical groups.
- Distinctive: line 26
Never include internal-only changes (e.g., "fixed typo in comment") in a user-facing changelog.
- Distinctive: line 27
Never skip the "Breaking Changes" section — it's the most important part.
- Distinctive: line 28
Never mention security findings, fixes, or implementation details in user-facing changelogs or release notes.
- Very specific: line 29
Never publish a value statement that fails the Four-Dimension Test — every user-facing entry MUST answer all four: WHAT changed, WHO …
- Distinctive: line 30
Never push a release tag or update the README without first running Step 2 (Significance Triage) and getting an explicit MAJOR or MINOR …
- Distinctive: line 31
Before finalizing Step 5 or Step 6, run the Accessibility & Motivation Check (Step 4 sub-section).
- Distinctive: line 46
Use the "Keep a Changelog" standard:
- Distinctive: line 64
Not a fifth dimension: WHY NOW explains relevance.
- Very specific: line 70
Follow the schema in references/changelog-template.md.
- Distinctive: line 78
If Significance ≥ MINOR, update README.md:
- Distinctive: line 80
Update any feature lists, install instructions, or capability tables that the release changes.
- Distinctive: line 85
If Significance ≥ MINOR, propose the release push.
- Distinctive: line 130
Never run git push or git tag without explicit user confirmation, even on a MAJOR release.
- Distinctive: line 188
Every commit listed verbatim instead of grouped themes
- Distinctive: line 195
No changes — citation audit passed.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 — <one-line justification>`. |
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, orread 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-skillinstead — it owns the skill tables. - Append a row to
docs/skill-outputs/SKILL-OUTPUTS.mdfor 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 --tagsFor 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 pushorgit tagwithout 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
<examples>
<example>
<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>
<output>
## [0.4.0] - 2026-04-12Summary: 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.mdanddocs/architecture.mdautomatically 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
</output>
</example>
</examples>
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
- Changelog under docs/changelogs/
- Entries grouped and readable
- Version or date in filename
- SKILL-OUTPUTS.md updated
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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

