Skip to content

Changelog genereration skill #2852

Open
Open
Changelog genereration skill#2852
@henryiii

Description

@henryiii
henryiii
opened on May 14, 2026

Steps:

  • Had AI analyze the current changelog and describe the style
  • Had AI write a skill (given agentskills.io) for generating a changelog
  • Had AI generate a changelog (unedited version below)
  • Had AI reflect on what would have been better and update the SKILL based on experience. Updated skill below.

All using GLM-5.1 (open source, MIT license) in OpenCode.

Generated changelog

.agents/skills/changelog-entry/SKILL.md: 

---
name: changelog-entry
description: Generate a new changelog entry for cibuildwheel based on all changes since the last tag. Use when updating the changelog or preparing a release.
---

# Generate Changelog Entry

Produce a new version section at the top of `docs/changelog.md` summarizing all changes since the last git tag.

## Steps

1. **Find the last tag** — run `git tag --sort=-version:refname | head -1` to get the most recent version tag.
2. **Gather changes** — run `git log <last-tag>..HEAD --oneline` and `git log <last-tag>..HEAD --format="%H %s"` to see all commits since that tag.
3. **Read each merge/commit** — for substantive commits, read the full message and any linked PRs to understand the change. Use `git log <last-tag>..HEAD --format="---%n%B"` for full messages. If a commit message is ambiguous, use `gh pr view <number>` to get richer context from GitHub.
4. **Classify and draft entries** — assign each change an emoji and write a one-line description following the style rules below. Combine related small PRs of the same type (bot dependency updates, dependabot CI action bumps, pre-commit autoupdates) into a single entry listing all PR numbers. Skip meta-changelog PRs (e.g., "Add missing CHANGELOG entries") — they don't describe user-facing changes. If a bot/dependency PR contains a substantive fix mixed in (e.g., a pip revert inside a dependency update), split it: mention the fix separately under its own category.
5. **Determine the new version number** — inspect commits for breaking changes or new features to decide patch/minor/major bump. Ask the user if unclear.
6. **Determine the date** — use today's date.
7. **Insert the new section** — add it at the top of `docs/changelog.md`, right after the `# Changelog` heading and a blank line, before any existing version sections.

## Style Rules

These are non-negotiable formatting conventions derived from the existing changelog.

### Version heading

```markdown
### v3.4.2
```

`###` heading, `v` prefix, full semver.

### Date line

```markdown
_14 May 2026_
```

Italic (underscore-wrapped), day without leading zero, full month name, 4-digit year. One blank line after the date.

### Entry format

```markdown
- <emoji> <Description> (#<PR number>)
```

- Each entry is a single bullet starting with `- `.
- Emoji immediately after the dash-space.
- Space between emoji and description text.
- PR number(s) in parens at end: `(#1234)` or `(#1234, #5678)`.
- No trailing period for single-sentence entries.
- Period at end of multi-sentence entries only.

### Emoji categories

Use exactly one emoji per entry, chosen by category:

| Emoji | Category | Used for |
|-------|----------|----------|
| 🌟 | Major feature | New platforms, significant new capabilities |
| ✨ | Feature | New features, additions, user-visible enhancements |
| 🐛 | Bug fix | Bug fixes |
| 🛠 | Maintenance | Dep updates, internal improvements, behavior tweaks |
| ⚠️ | Warning | Deprecations, breaking changes, dropped support |
| 📚 | Docs | Documentation changes |
| 💼 | Internal | Non-user-facing infra/tooling changes |
| 🧪 | Tests | Test changes |
| 🔐 | Security | Security-related changes (used in past changelogs) |

### Category disambiguation

When a change could fit multiple categories, use these tiebreakers:

- **CI/workflow fixes** → 💼 (not 🧪) — they fix infra, not test logic.
- **Test suite changes** → 🧪 — only for changes to the test code itself.
- **Diagnostic output changes** (e.g., printing more info during builds) → 🛠 (not 🐛) — they're improvements, not bug fixes.
- **A bug fix that also changes test code** → 🐛 — the user-facing fix takes priority; test changes are implicit.

### Writing style

- **Present tense**: "Adds", "Fixes", "Updates", not "Added", "Fixed".
- **Sentence case**: capitalize only the first word after the emoji.
- **Link option names to docs**: `[`option-name`](https://cibuildwheel.pypa.io/en/stable/options/#option-name)`. Option anchors match the option name — verify in `docs/options.md` by searching for `{: #option-name }`.
- Be specific about what changed and why, not just that something changed.

### Ordering

Within a version section, order entries by importance:

1. 🌟 entries first
2. ⚠️ entries next
3. ✨ entries
4. 🐛 entries
5. 🛠 entries
6. 📚 entries
7. 💼 entries
8. 🧪 entries last

### Multi-line entries

For complex features needing explanation, use an indented italic paragraph:

```markdown
- ✨ Short summary here. (#1234)

    _Longer explanation with details and caveats._ (#1234)
```

### Blank lines

- One blank line between version sections.
- No blank lines between bullets within a version.

## Validation

After inserting the new section:

1. Check that the new section follows all style rules above.
2. Verify PR numbers match actual PRs in the commit log.
3. Ensure no duplicate entries — multiple commits to the same PR should produce one entry.
4. Run a final review of the file to confirm formatting is consistent with surrounding entries.

The skill might be something we want to commit? Also not sure how to best tie it into the current procedure. Actually, that would be easy, as there's a spot where it just waits for it to be updated.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions