update-changelog

Files (1)

• SKILL.md

SKILL.md (first lines)

Manage CHANGELOG.md files and GitHub releases — add new entries, backfill missing versions, and sync release notes.

## Formatting

### CHANGELOG.md format

Follow [Keep a Changelog](https://keepachangelog.com/) with these specific conventions:

```markdown
# Changelog

## [1.2.0] - 2026-03-15

### Added
- Add git stage/unstage actions to action palette
- Add git commit via action palette

### Fixed
- Fix Ctrl+R refresh not reloading git status
- Skip .git and hidden dirs in file finder

### Changed
- Clean up keybindings and action names

## [1.1.0] - 2026-03-14
...
```

Rules:
- **File heading**: `# Changelog` (nothing else on the line)
- **Version heading**: `## [x.y.z] - YYYY-MM-DD` — square brackets around version, space-dash-space before date
- **Unreleased heading**: `## [Unreleased]` — no date
- **Category headings**: `### Added`, `### Changed`, `### Fixed`, `### Removed` — only include categories that have entries
- **Category order**: Added → Changed → Fixed → Removed
- **Entry format**: `- Verb-led phrase` — start with present-tense verb, no trailing period, no sub-bullets
- **Verb matches category**:
  - Added → "Add ...", "Enable ...", "Introduce ..."
  - Changed → "Update ...", "Move ...", "Use ...", "Rename ...", "Convert ..."
  - Fixed → "Fix ...", "Correct ...", "Prevent ..."
  - Removed → "Remove ...", "Delete ...", "Drop ..."
- **Whitespace**: one blank line between version sections, one blank line between category sections, no blank lines between entries within a category, no trailing blank line at end of file

### GitHub release format

Release notes use the same content as the CHANGELOG.md entry but **without** the version heading (`## [x.y.z] - ...`). Include all categories present in the changelog entry. Keep the category headings and entries as-is:

```markdown
### Added
- Add git stage/unstage actions to action palette
- Add git commit via action palette

### Fixed
- Fix Ctrl+R refresh not reloading git status
```

## Modes of operation

This skill operates in two modes based on user intent:

1. **Add/update** (default) — add a new changelog entry for a specific version, optionally sync to a GitHub release
2. **Backfill** — populate missing versions in CHANGELOG.md and/or GitHub releases from git history

## Add/update mode

### Tag naming

Versions are always bare (e.g. `1.2.0`), including versions passed in by callers such as the `ship` skill; never add a second `v` to an input that already has one. Build tag names from the repo's existing convention:

```bash
git tag --list 'v*'
git tag --list '[0-9]*'
```

- If version tags use a `v` prefix, the tag for a version is `v{version}`; if they are bare, it is `{version}`.
- If no version tags exist, default to `v{version}` and tell the user.

Below, `{tag}` means the tag built this way for the version in question.

### Step 1 — Find CHANGELOG.md

Glob for `**/CHANGELOG.md`. If multiple are found, ask the user which to update. If none found, offer to create one with the [Keep a Changelog](https://keepachangelog.com/) header:

```markdown
# Changelog
```

### Step 2 — Determine what changed

Two sources, in priority order:

1. **User-provided description** — if the user described the changes, use that directly
2. **Git history** — if no description provided, identify changes since the last version:
   - Read the top entry in CHANGELOG.md to get the latest version number. If the changelog is empty or has only a header, treat it as a fresh changelog with no prior version.
   - Run `git log {tag}..HEAD --oneline` (where `{tag}` is the tag for the latest version) to list commits since that version (if no matching tag exists, use the entry's date with `--since=YYYY-MM-DD`; if no prior version at all, use the full log)
   - Summarize the changes into concise bullet points

### Step 3 — Determine version and date

- If the user provided a version, use it
- If a version was recently bumped in the working tree (check `git diff` and `git diff --staged` for version file changes), detect and use the new version
- Otherwise, ask the user for the new version
- Date defaults to today

### Step 4 — Categorize entries

Classify each change into [Keep a Changelog](https://keepachangelog.com/) categories:

| Category | When to use | Git message keywords |
|---|---|---|
| **Added** | New features, files, capabilities | "add", "introduce", "new" |
| **Changed** | Modifications to existing functionality | "update", "improve", "refactor" |
| **Fixed** | Bug fixes | "fix", "repair", "resolve" |
| **Removed** | Removed features or files | "remove", "delete", "drop" |

If the user provided pre-categorized entries, respect their categorization. Only include categories that have entries — omit empty categories.

### Step 5 — Insert the entry

Insert the new version section at the top of the changelog (after the `# Changelog` heading or after `## [Unreleased]` if present), following the formatting rules above. Use the Edit tool to insert, not a full file rewrite. If the file was just created (empty or header-only), writing the full file is acceptable.

From lucaspimentel/agent-skills, MIT.

More from lucaspimentel/agent-skills