Agent-Skills.md

Agent Skills: Changelog

Keep a Changelog format. Covers structure, change types, versioning. Keywords: CHANGELOG.md, semver.

UncategorizedID: itechmeat/llm-code/changelog

Repository

itechmeat/llm-code
itechmeatLicense: MIT
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/itechmeat/llm-code/tree/HEAD/skills/changelog

Skill Files

Browse the full folder contents for changelog.

Download Skill

Loading file tree…

skills/changelog/SKILL.md

Skill Metadata

Name
changelog
Description
"Keep a Changelog format. Covers structure, change types, versioning. Keywords: CHANGELOG.md, semver."

Changelog

Format specification for CHANGELOG.md based on Keep a Changelog 1.1.0.

Language Requirement (Mandatory)

  • All changelog content MUST be written in English.
  • If source information is provided in another language, translate it to English.
  • Do not mix languages within the same changelog.

Quick Reference

File Header

# 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).

Section Structure

## [Unreleased]

### Added

- New feature description

## [1.0.0] - 2024-01-15

### Added

- Feature A
- Feature B

### Changed

- Modified behavior X

### Fixed

- Bug fix Y

Types of Changes

| Type | Purpose | | ------------ | --------------------------------- | | Added | New features | | Changed | Changes in existing functionality | | Deprecated | Soon-to-be removed features | | Removed | Now removed features | | Fixed | Bug fixes | | Security | Vulnerabilities |

Format Rules

Version Header

## [X.Y.Z] - YYYY-MM-DD
  • Version in brackets, linked to comparison
  • Date in ISO 8601 format (YYYY-MM-DD)

Date-Based Versioning (Alternative)

For projects using date-based versioning instead of semver:

## [YYYY-MM-DD]

Use current date instead of [Unreleased]. This project uses date-based versioning.

Yanked Releases

## [0.0.5] - 2014-12-13 [YANKED]

Use when version was pulled due to serious bug or security issue.

Comparison Links (at file end)

[unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0

Guiding Principles

  1. For humans, not machines — Write clear, readable entries
  2. Entry for every version — Document all releases
  3. Group same types — Keep Added/Changed/Fixed together
  4. Linkable versions — Use comparison links
  5. Latest first — Reverse chronological order
  6. Show release dates — Use ISO 8601 format
  7. State versioning scheme — Mention Semantic Versioning if used

Complete Example

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

### Added

- New authentication method

## [1.2.0] - 2024-01-20

### Added

- User profile page
- Export to CSV functionality

### Changed

- Improved loading performance by 40%

### Deprecated

- Legacy API endpoint `/api/v1/users` (use `/api/v2/users`)

### Fixed

- Login timeout issue on slow connections

## [1.1.0] - 2024-01-10

### Added

- Dark mode support

### Security

- Fixed XSS vulnerability in comment field

## [1.0.0] - 2024-01-01

### Added

- Initial release with core features
- User registration and login
- Dashboard with analytics

[unreleased]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/project/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0

Bad Practices

Commit log diffs

Don't dump git log into changelog:

  • Full of noise (merge commits, obscure titles)
  • Not human-readable
  • Mixes important and trivial changes

Ignoring deprecations

Don't skip deprecation notices:

  • Users need to know what will break
  • Document deprecations before removals
  • List breaking changes clearly

Confusing dates

Don't use regional date formats:

  • Use ISO 8601: YYYY-MM-DD
  • Avoids ambiguity (is 01/02/2024 Jan 2 or Feb 1?)

Inconsistent changes

Don't document only some changes:

  • Changelog should be single source of truth
  • Important changes must be mentioned
  • Consistently updated

Writing Tips

Good Entry Examples

### Added

- OAuth2 authentication with Google and GitHub providers
- Rate limiting for API endpoints (100 req/min)

### Changed

- Database queries now use prepared statements for better security
- Upgraded dependency `lodash` from 4.17.20 to 4.17.21

### Fixed

- Memory leak in WebSocket connection handler
- Race condition in concurrent file uploads

Entry Guidelines

  • Review current git changes (diff or changed files list) before drafting; ensure all material changes are covered.
  • Start with verb or noun describing the change
  • Be specific (mention affected component/endpoint)
  • Reference issue/PR numbers when relevant: (#123)
  • Keep entries concise but informative
  • Omit empty sections (do not include a section header if there are no entries for it)

File Naming

Required: CHANGELOG.md (uppercase). Do not use lowercase or alternative names.

Do not use alternative filenames.

GitHub Releases vs CHANGELOG.md

| Aspect | GitHub Releases | CHANGELOG.md | | --------------- | --------------- | ----------------- | | Portability | GitHub-only | Universal | | Discoverability | Less visible | Standard location | | Version control | Separate UI | In repository | | Diff links | Manual setup | Easy to add |

GitHub Releases can complement but shouldn't replace CHANGELOG.md.

Conventional Commits Integration

Changelogs work best with Conventional Commits format:

| Commit Type | Changelog Section | | ----------------- | -------------------- | | feat: | Added | | fix: | Fixed | | perf: | Changed | | refactor: | Changed | | docs: | (often omitted) | | BREAKING CHANGE | Highlight in Changed | | Security fix | Security | | revert: | Removed or Fixed |

Automated Generation

Tools that parse Conventional Commits and generate changelogs:

See commits skill for commit message format.

Workflow Integration

Unreleased Section Pattern

  1. Add changes to ## [Unreleased] during development
  2. At release time, rename to ## [X.Y.Z] - YYYY-MM-DD
  3. Create new empty ## [Unreleased] section
  4. Add comparison link for new version

Pre-commit Checklist

Before release:

  • [ ] All notable changes documented
  • [ ] Unreleased section moved to version
  • [ ] Date added in ISO 8601 format
  • [ ] Comparison link added
  • [ ] Breaking changes highlighted
  • [ ] Deprecations documented

Critical Prohibitions

  • Do not use git log as changelog
  • Do not omit breaking changes or deprecations
  • Do not use ambiguous date formats
  • Do not leave changelog inconsistently updated
  • Do not forget to update Unreleased → version at release
  • Do not write changelog entries in any language other than English

README Synchronization

After writing changelog, review the project's main README.md:

  1. Check for outdated information — features, skills, tools lists
  2. Add new entries — if changelog introduces new skills, features, or components
  3. Remove deprecated items — if changelog removes functionality
  4. Update descriptions — if changelog changes existing functionality

What to sync:

  • Skills/features tables
  • Compatibility lists
  • Installation instructions
  • Links and references

What NOT to sync:

  • Changelog content itself (no duplication)
  • Version history
  • Detailed change descriptions

Do NOT mention README.md updates in CHANGELOG — README synchronization is implied and should not be logged as a separate change.

Links

  • Official specification: https://keepachangelog.com/en/1.1.0/
  • Semantic Versioning: https://semver.org/spec/v2.0.0.html
  • Related: commits skill — Conventional Commits format

Templates