Skip to content

chore: add the writing-changelog skill and route CHANGELOG.md edits through it - #92

Merged
V3RON merged 1 commit into
mainfrom
chore/writing-changelog-skill
Sep 23, 2026
Merged

V3RON merged 1 commit into
mainfrom
chore/writing-changelog-skill

Conversation

@V3RON

@V3RON V3RON commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Closes: no issue; follows up the agentic setup in #85.

What changed

Changelog entries were leaking implementation detail: the two entries written after #85 landed ran seven to ten lines and named internal functions, processes and a file descriptor. No skill covered the changelog. implement-issue called the changelog line "separate" from the docs written with writing-user-docs, its finish step named no skill, and writing-user-docs has no length rule (its "concise means no filler, not short" pushes the other way) and no example of an entry.

This adds .claude/skills/writing-changelog: one bullet per change, a bold <Kind>: <what the user notices> part plus at most one more sentence, a list of what never goes in an entry, a leaked-versus-clean example pair, and the Breaking kind that cut-release keys the version bump off. Voice and scope rules stay in writing-user-docs and apply by reference.

Wiring so agents reach it without relying on description matching: AGENTS.md rule 6 and the skills table, both changelog steps in implement-issue, a dedicated finding in review-pr, the PR template checklist, the CHANGELOG.md header, and a LESSONS.md section.

Acceptance criteria

Agent setup only; no code, no tests.

# Criterion Test Tier
1 Every skill that touches CHANGELOG.md names writing-changelog grep -rn writing-changelog .claude/skills AGENTS.md .github manual

E2E evidence

not applicable

Checklist

  • CHANGELOG.md has an entry under Unreleased (writing-changelog skill), or the change is not user-visible
  • User-facing docs updated for every surface the change touches (writing-user-docs skill), or the change is not user-visible
  • No new import past a module's index.ts; no new direct node:* I/O outside an adapter
  • Simplification checklist from the architecture skill applied, exceptions explained above
  • docs/ARCHITECTURE.md updated if a surface it describes changed

Out of scope

The existing entries under 0.11.0 and 0.11.1 are not rewritten; released sections stay as published. A PreToolUse hook on CHANGELOG.md edits was considered and left out until the skill references prove insufficient.

Status

Implement: done Review: pending E2E: not applicable Ready: yes

@V3RON
V3RON merged commit 419e14b into main Sep 23, 2026
8 checks passed
@V3RON
V3RON deleted the chore/writing-changelog-skill branch September 23, 2026 15:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant