Update changelog

Update Changelog Skill

Overview

Maintain accurate, user-facing changelog entries as you build. This skill helps you document new features, fixes, enhancements, and breaking changes in a structured format that follows Keep a Changelog.

The changelog is your project's narrative—it tells users what changed and why. AI agents should document their work just as humans do.

---

When to Use This Skill

Use this skill whenever you:

• Add a new feature — enhancement that extends functionality
• Fix a bug — resolution of unexpected behavior
• Deprecate something — warn users about upcoming removal
• Remove functionality — breaking change that affects users
• Improve performance — optimization or security hardening
• Release a version — formalize changes under a version number

---

The Changelog Structure

The CHANGELOG.md file has this structure:

# Changelog

## [Unreleased]
### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security

## [Version] - [Date]
### Added
...

Important sections:

• [Unreleased] — changes that haven't been released yet (always at the top)
• Categories — Added, Changed, Deprecated, Removed, Fixed, Security (use all that apply)
• Entries — clear, user-facing descriptions (not implementation details)

---

Workflow: Adding an Entry

Step 1: Identify the Category

Decide which category your change belongs to:

Category	When to Use	Example
Added	New feature or capability	"Add priority-based task queuing for agents"
Changed	Behavior or API modification	"Improve agent coordination algorithm"
Deprecated	Mark something for future removal	"Deprecate legacy executor API"
Removed	Delete functionality	"Remove deprecated tmux executor support"
Fixed	Bug resolution	"Fix agent crash when PR has no comments"
Security	Vulnerability or safety fix	"Fix privilege escalation in plugin system"

Step 2: Write a Clear Entry

Write entries from the user's perspective, not implementation details.

✅ Good entries:

• "Add ability to prioritize high-urgency tasks in the orchestrator"
• "Improve agent responsiveness during CI failures by 40%"
• "Fix agents hanging on repos with very large file trees"

❌ Avoid:

• "Refactor TaskQueue class"
• "Update dependencies"
• "Merge branch feature/xyz"

Step 3: Add References (Optional)

If relevant, link to the PR, issue, or commit:

- Added new plugin system for extensible agent behaviors ([PR #42](https://github.com/your-org/your-repo/pull/42))
- Fixed memory leak in event listener ([Issue #89](https://github.com/your-org/your-repo/issues/89))

Step 4: Open CHANGELOG.md and Locate [Unreleased]

Find the ## [Unreleased] section at the top of the file.

Step 5: Add Your Entry Under the Correct Category

Add your entry as a bullet point under the relevant category in [Unreleased]:

## [Unreleased]

### Added
- New feature description goes here
- Another feature

### Fixed
- Bug fix description goes here

Step 6: Review and Commit

• Verify the entry is clear and in the right category
• Make sure it reads naturally alongside other entries
• Commit with a message like: docs: update changelog for [feature name]

---

Example: Adding a Feature

What you did: Built a new plugin system for agents.

The entry you add to [Unreleased]/Added:

- Add plugin system with extensible hooks for custom agent behaviors ([PR #42](https://github.com/your-org/your-repo/pull/42))

In context (CHANGELOG.md):

## [Unreleased]

### Added
- Add plugin system with extensible hooks for custom agent behaviors ([PR #42](https://github.com/your-org/your-repo/pull/42))
- Improve agent task decomposition for better parallelization

### Fixed
- Fix agents hanging on repos with very large file trees

---

Example: Fixing a Bug

What you did: Resolved agents crashing when processing empty PRs.

The entry you add to [Unreleased]/Fixed:

- Fix agent crash when processing PRs with no body or comments

---

Releasing a Version

When you're ready to formalize changes as a release:

1. Decide on a Version Number

Use Semantic Versioning:

• Major (X.0.0) — breaking changes
• Minor (0.X.0) — new features (backward-compatible)
• Patch (0.0.X) — bug fixes (backward-compatible)

2. Create a New Version Section

Replace [Unreleased] with a new version heading:

## [0.2.0] - 2025-03-26

### Added
- Add plugin system with extensible hooks for custom agent behaviors
- Improve agent task decomposition for better parallelization

### Fixed
- Fix agent crash when processing PRs with no body or comments

## [Unreleased]

### Added

### Changed

### Deprecated

### Removed

### Fixed

### Security

3. Update the Version Table (Optional)

If you have a version summary table, update it:

| Version | Date | Highlights |
|---------|------|-----------|
| 0.2.0 | 2025-03-26 | Plugin system + better decomposition |
| 0.1.0 | 2025-03-01 | Foundation + initial setup |

4. Commit and Tag

git add CHANGELOG.md
git commit -m "release: v0.2.0"
git tag v0.2.0
git push origin main --tags

---

Rules for Keeping Changelog Clean

1. [Unreleased] always at the top — new changes go here first
2. Reverse chronological order — newest versions first
3. Clear, user-facing language — explain what changed, not how
4. One entry per line — easy to scan and read
5. Group related changes — if features are interdependent, mention it
6. Use backticks for code — `feature-name`, `PluginAPI`, `ConfigOption`
7. Link to PRs/issues — when possible, for traceability
8. Deprecation warnings — announce removals 1-2 releases in advance

---

Common Mistakes to Avoid

Mistake	Wrong	Right
Implementation details	"Refactor executor class"	"Improve executor performance by 30%"
Missing category	Entry floating in the file	Clearly under Added/Fixed/Changed/etc.
Too vague	"Various improvements"	"Improve agent coordination during peak load"
No user impact	"Update dependencies"	Only if users are affected (e.g., "Drop Python 3.8 support")
Typos	"Imprve agent responsivness"	Spell-check before committing

---

Hands-On: Your First Entry

Practice Scenario

You just added a feature: agents can now run custom pre-flight checks before starting work.

Your changelog entry:

### Added
- Allow agents to run custom pre-flight checks before task execution

In context:

## [Unreleased]

### Added
- Allow agents to run custom pre-flight checks before task execution

✅ Why this works:

• User-facing (explains what agents can now do)
• Clear action verb (Allow, Add, Improve, Fix)
• Concise but complete
• In the right category

---

Tips for Agents Adding Entries

When an AI agent is updating the changelog:

1. Parse the current [Unreleased] section — understand what's already there
2. Determine the best category — don't force-fit into the wrong section
3. Write from the user's perspective — "what does this change do for them?"
4. Check for duplicates — don't add the same feature twice
5. Maintain alphabetical order — optional but helpful for long lists
6. Preserve formatting — keep the markdown clean and readable
7. Validate before committing — ensure the file is still valid markdown

---

File Paths

• Changelog file: CHANGELOG.md (root directory)
• This skill: .claude/skills/update-changelog/SKILL.md (or your skill directory)

---

References

• Keep a Changelog — the standard this follows
• Semantic Versioning — how to number releases
• Git Commit Message Conventions — structure your commits

---

Quick Reference

# Workflow
1. Make changes to your codebase
2. Run this skill to add entries to CHANGELOG.md
3. Review the entries for clarity
4. Commit: git add CHANGELOG.md && git commit -m "docs: update changelog"
5. When releasing: create version section, commit, and tag

# Categories (in order)
- Added (new features)
- Changed (behavior changes)
- Deprecated (warn about removal)
- Removed (deleted features)
- Fixed (bug fixes)
- Security (vulnerabilities)

# Entry format
- Short, user-facing description
- Optional: link to PR/issue
- Start with action verb (Add, Improve, Fix, Allow, etc.)

---

Last updated: March 2025
Maintained with: Agent Orchestrator by Composio (MIT License)