agentleFS
go-steergo-steer/core-agent/.agents/skills/changelog-bullet/SKILL.md

changelog-bullet

Skill9 starsChanged 47 days agoApache-2.0View on GitHub

Write the CHANGELOG entry for a core-agent PR. Use whenever a change is user-visible — a feature, bug fix, published-doc or contributor-rule change, breaking change or cleanup. Covers which subsection, citing the issue rather than the PR, what a bullet has to contain, and the stacked-release-branch hazard that silently files a bullet under a shipped version.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every merged PR with a user-visible change adds one bullet under ## [Unreleased] in CHANGELOG.md, as part of the PR itself.

    line 8
  2. Very specific:

    No for everything else under docs/ and dev/.

    line 21
  3. Very specific:

    No check catches the duplicate version heading automatically: verify-release-notes checks [Unreleased] bullets on CHANGELOG.md, not …

    line 71
  4. Distinctive:

    After any base-update on such a branch:

    line 76
  5. Very specific:

    Run dev/ci/presubmits/verify-release-notes before pushing.

    line 87

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

The CHANGELOG bullet

Every merged PR with a user-visible change adds one bullet under ## [Unreleased] in CHANGELOG.md, as part of the PR itself. Both release scripts assume [Unreleased] is current; if it is stale at tag time someone has to backfill it from git log, which produces a worse entry than the person who made the change would have.

Does a doc change need one?

Yes for three kinds: the published site under docs/site/src/content/docs/; README.md and the READMEs under examples/; and a change to a rule in AGENTS.md, CONTRIBUTING.md, docs/release-process.md or a skill under .agents/. All three go under #### Documentation.

No for everything else under docs/ and dev/. Design docs, assessments, UAT write-ups and friction logs are internal. When an internal doc records a user-visible change, the bullet belongs to that change, not to the doc.

This is AGENTS.md's "Which doc changes are user-visible" rule, and if the two ever disagree, AGENTS.md wins. Don't infer the rule from CHANGELOG.md's history. Before the rule, docs-only PRs almost never carried a bullet, even though the text said they should.

Which subsection

#### Feature · #### Bug or Regression · #### Documentation · #### Other (Cleanup) · #### Security

Breaking changes go under #### Changed with a **BREAKING:** prefix, so cut-ga-tag.sh can hoist them into a ### Breaking Changes section automatically at tag time.

Cite the issue, not the PR

([#1137](https://github.com/go-steer/core-agent/issues/1137))

The issue is where the problem is described and where the discussion lives. The PR number is recoverable from git; the issue number is the one a reader six months out actually wants.

What a bullet has to contain (<= 300 characters)

Each [Unreleased] bullet is a single line capped at 300 characters (enforced by dev/tools/verify-release-notes), ending with a ([#NNN](https://github.com/go-steer/core-agent/issues/NNN)) link. The long-form rationale, rejected alternatives, and incident history belong in the PR body or docs/, so CHANGELOG.md and the GitHub Release body stay readable and well under GitHub's 125 KB release-body limit (#1387).

  • Lead with what changed in the user's terms, bolded, naming the affected package or surface.
  • State the concrete effect or fix in one concise sentence.
  • End with the issue link ([#NNN](url)).

The hazard worth memorizing

A base-update on a branch stacked on a release-promotion PR silently duplicates the CHANGELOG version heading. Both sides carry the identical ## [Unreleased] → ## [X.Y.Z] — DATE rename, git resolves two identical insertions without a conflict, and your bullet ends up filed under a release that was tagged from a commit demonstrably lacking it.

No check catches the duplicate version heading automatically: verify-release-notes checks [Unreleased] bullets on CHANGELOG.md, not duplicate version headings, and verify-docs-lint passes on the duplicated file.

After any base-update on such a branch:

git diff <base>...HEAD -- CHANGELOG.md   # three-dot, not the merge exit code
grep -nE '^## \[' CHANGELOG.md | head

Observed on #993.

Also

Run dev/ci/presubmits/verify-release-notes before pushing. If the change touches a user-visible surface, the Astro site under docs/site/src/content/docs/ walks in the same PR, not as a follow-up.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.