home / skills / basedhardware / omi / changelog

changelog skill

This skill generates changelog entries from git commits and PRs, formats, and updates CHANGELOG.md for releases.

npx playbooks add skill basedhardware/omi --skill changelog

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.7 KB

---
name: changelog
description: "Generate changelog entries. Use on releases or PR merges. Parses git commits, categorizes changes, formats changelog entries, and updates CHANGELOG.md."
---

# Changelog Skill

Automate changelog generation from git commits and pull requests.

## When to Use

Use this skill when:
- On release or version bump
- When PR is merged
- When user requests changelog
- Before creating release
- When preparing release notes

## Capabilities

### 1. Parse Git Commits

Extract information from commits:
- Parse commit messages following conventional commits format
- Extract type (feat, fix, docs, refactor, etc.)
- Extract scope (component/module)
- Extract description
- Extract breaking changes
- Extract issue references (#123)

### 2. Categorize Changes

Organize changes by category:
- **Features** (`feat`): New functionality
- **Bug Fixes** (`fix`): Bug fixes
- **Documentation** (`docs`): Documentation changes
- **Refactoring** (`refactor`): Code refactoring
- **Performance** (`perf`): Performance improvements
- **Tests** (`test`): Test additions/changes
- **Chores** (`chore`): Maintenance tasks
- **Breaking Changes** (`BREAKING CHANGE`): Breaking changes

### 3. Format Changelog Entries

Create formatted changelog entry:
- Use standard changelog format
- Group by category
- Include issue references
- Highlight breaking changes
- Include contributor credits if available

### 4. Update CHANGELOG.md

Update changelog file:
- Add new entry at top
- Follow existing format
- Include version number
- Include release date
- Maintain chronological order

## Commit Message Format

Follows conventional commits (from `.cursor/rules/git-workflow.mdc`):
```
type(scope): subject

body (optional)

footer (optional)
```

Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Formatting
- `refactor`: Code refactoring
- `test`: Tests
- `chore`: Maintenance

## Changelog Format

```markdown
## [Version] - YYYY-MM-DD

### Added
- New feature description (#123)

### Changed
- Change description (#456)

### Fixed
- Bug fix description (#789)

### Breaking Changes
- Breaking change description (#999)
```

## Workflow

1. **Get Commits**: Fetch commits since last release or tag
2. **Parse Messages**: Extract information from commit messages
3. **Categorize**: Group changes by type
4. **Format**: Generate formatted changelog entry
5. **Update File**: Add entry to CHANGELOG.md
6. **Validate**: Check format and completeness

## Related Resources

### Rules
- `.cursor/rules/git-workflow.mdc` - Commit message format
- `.cursor/rules/documentation-standards.mdc` - Documentation standards

### Subagents
- `.cursor/agents/changelog-generator.md` - Changelog generation subagent

### Commands
- `/auto-changelog` - Generate changelog automatically

Overview

This skill generates and updates changelog entries from git commits and merged pull requests. It parses commit messages, groups changes into conventional categories, formats a release entry, and appends it to CHANGELOG.md with version and date. The output is ready-to-publish release notes that highlight features, fixes, and breaking changes.

How this skill works

The skill fetches commits since the last tag or release and parses messages following the conventional commits format. It extracts type, scope, description, issue references, and any breaking-change notes. Changes are grouped into categories (Added, Changed, Fixed, Breaking Changes, etc.), formatted into a standard markdown changelog entry, and inserted at the top of CHANGELOG.md with version and release date.

When to use it

When cutting a new release or bumping version
After merging pull requests into the main branch
When preparing release notes for stakeholders
When a user requests an up-to-date changelog
Before publishing packages to package registries

Best practices

Follow conventional commits for clear parsing and categorization
Include issue numbers and concise descriptions in commit subjects
Add BREAKING CHANGE in body or footer for incompatible changes
Run the skill after validating tests and CI to ensure accuracy
Review generated entry before publishing to include any manual notes

Example use cases

Generate changelog for a patch release after multiple bugfix merges
Create release notes for a new feature version including contributor credits
Produce a draft changelog before publishing mobile/Flutter app builds
Automatically update CHANGELOG.md in CI when a release tag is created
Consolidate merged PRs into a single formatted entry for release PR

FAQ

What commit message format does this expect?

It expects conventional commits (type(scope): subject with optional body and footer). Types like feat, fix, docs, refactor, perf, chore are supported.

How does it detect breaking changes?

It scans commit bodies and footers for the text BREAKING CHANGE or equivalent notes and promotes those items to the Breaking Changes section.

Can it include contributor credits and issue links?

Yes. If commit metadata or PR data include author and issue references, the skill includes contributor names and issue numbers in the entry.