changelog— agent skill

You are in AUTONOMOUS MODE. Do NOT ask questions. Parse the git history and produce a well-structured CHANGELOG.md.

INPUT: $ARGUMENTS

Accepted arguments:

• No arguments: generate full changelog from all git history.
• since vX.Y.Z or since <tag>: generate only entries since that tag/version.
• unreleased: generate only the Unreleased section since the last tag.
• update: read existing CHANGELOG.md, append only new entries since last documented version.

============================================================ PHASE 1: GIT HISTORY EXTRACTION ============================================================

Step 1.1 -- Identify Version Boundaries

Run:

• git tag --sort=-version:refname to list all tags (newest first)
• git log --format="%H|%ai|%s|%b|%D" --reverse to get all commits with refs

For each tag, record:

• Tag name (vX.Y.Z or X.Y.Z)
• Tagged commit hash
• Tag date

If no tags exist, group commits by time periods (monthly or weekly).

Step 1.2 -- Parse Commits

For each commit between version boundaries, parse the message:

For non-conventional commits (no prefix), classify by content:

• Messages containing "fix", "bug", "patch", "resolve" -> Bug Fixes
• Messages containing "add", "new", "feature", "implement" -> Features
• Messages containing "update", "upgrade", "bump" -> Chores
• Messages containing "remove", "delete", "deprecate" -> Removed
• All others -> Other Changes

Step 1.3 -- Extract Metadata

For each commit, also extract:

• PR/MR number from message (e.g., (#123), Merge pull request #123)
• Issue references (e.g., fixes #45, closes #78)
• Scope from conventional commit (the part in parentheses)
• Author name

============================================================ PHASE 2: CHANGELOG GENERATION ============================================================

Step 2.1 -- Read Existing Changelog

If CHANGELOG.md exists:

• Read its full contents
• Identify the most recent documented version
• Only generate entries for commits AFTER that version
• Preserve the existing file header and formatting style

Step 2.2 -- Format Entries

Use keep-a-changelog format (https://keepachangelog.com):

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD

### Breaking Changes
- Description of breaking change ([#PR](url))

### Added
- New feature description ([#PR](url))

### Fixed
- Bug fix description ([#PR](url))

### Changed
- Change description ([#PR](url))

### Deprecated
- Deprecation notice ([#PR](url))

### Removed
- Removal description ([#PR](url))

### Security
- Security fix description ([#PR](url))

Category mapping from conventional commits to changelog sections:

• feat -> Added
• fix -> Fixed
• perf -> Changed
• refactor -> Changed
• BREAKING CHANGE -> Breaking Changes
• revert -> Removed
• security-related fixes -> Security
• deprecation notices -> Deprecated

Step 2.3 -- Group and Deduplicate

• Group entries by version/tag boundary
• Within each version, group by category (Breaking Changes first, then Added, Fixed, etc.)
• Deduplicate: if a fix commit directly references a feat commit in the same version,

mention only the feature (the fix was part of getting it right)

• Collapse "fix: fix typo" chains into a single entry
• Omit low-value entries: merge commits, version bumps, pure chore/ci commits

(unless they are the only changes in a version)

Step 2.4 -- Link Generation

If the project has a git remote, generate comparison links:

[Unreleased]: https://github.com/owner/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/owner/repo/releases/tag/v1.1.0

Detect the remote URL from git remote get-url origin.

============================================================ PHASE 3: WRITE AND VERIFY ============================================================

Step 3.1 -- Write CHANGELOG.md

• If updating: prepend new version sections after the header, before existing entries
• If creating: write the complete file
• Ensure consistent formatting throughout

Step 3.2 -- Verify

• Count commits parsed vs entries generated
• Confirm version ordering is correct (newest first)
• Confirm dates match tag dates
• Confirm PR/issue links are properly formatted

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing documentation, validate completeness:

1. Verify all required sections are present and non-empty.
2. Verify internal cross-references and links resolve correctly.
3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
4. Verify code examples are syntactically valid.

IF VALIDATION FAILS:

• Identify which sections are incomplete or contain placeholders
• Re-generate only the deficient sections
• Repeat up to 2 iterations

============================================================ OUTPUT ============================================================

Changelog Generated

• Versions documented: N
• Total entries: N
• New entries added: N (if updating)
• Commits parsed: N
• Commits skipped: N (merge commits, version bumps)
• File: CHANGELOG.md

Version Summary

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /changelog — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT ============================================================

• Do NOT fabricate entries. Every changelog entry must correspond to an actual commit.
• Do NOT include commit hashes in the changelog (use PR/issue links instead).
• Do NOT include internal tooling changes that have no user-facing impact unless

the project has no user-facing changes at all.

• Do NOT overwrite manually-written changelog entries. Preserve them and append new ones.
• Do NOT include "Co-Authored-By" or similar attribution lines in entries.

NEXT STEPS:

After generating the changelog:

• "Run /document to check overall documentation health."
• "Run /readme to update the README with the latest version info."