# Release Notes

> Use when a change may need a .changes note, the Release note gate fails, or deciding whether type: internal or no-release-note applies.

- Skill: `4gray/release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 4gray/release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/4gray/release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 4gray (https://skillmd.com/u/4gray)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/4gray/release-notes

---


# Release Notes

Every user-visible change gets one direct `.changes/<area>-<slug>.md` file. The
area matches the conventional-commit scope; the body is present tense, user
language, one to three sentences, and at most 400 characters.

## Format

```markdown
---
type: fix
area: stalker
issues: [1234]
screenshot: optional-manifest-slug
highlight: Optional short headline
---

Stalker series now resume the correct episode.
```

`type` is `breaking`, `feature`, `fix`, `perf`, or `internal`. Omit optional
fields instead of inventing values. Never add a version or PR number.

`highlight` (max 60 characters, never on `internal`) names a headline feature:
it leads the Telegram/Reddit announcement drafts and becomes the blog section
heading. Reserve it for the two or three changes worth announcing.

`internal` records invisible maintenance. It stays collapsed in `CHANGELOG.md`
but is omitted from the blog and the authored public GitHub body. GitHub's
generated commit list may still mention the underlying commits.

## Skip or Label

The gate auto-exempts website, E2E and mock-server apps, `*.spec.{js,ts}`,
`*.e2e.{js,ts}`, snapshots, any `/testing/` path, and Markdown. Other test-only,
docs, CI, workflow, or pure-refactor PRs use `no-release-note` when the gate
would otherwise require a note. At least one newly added direct
`.changes/*.md` file satisfies the gate.

## Verify

```bash
pnpm run release:notes:validate
```

Full format: `.changes/README.md`. Gate policy:
`tools/release/check-release-note-gate.mjs`.

The `.codex` and `.claude` copies of this skill must remain byte-identical.