Agent Skills › medusajs/medusa › writing-releases

writing-releases

GitHub

根据提交记录和PR元数据生成符合Medusa规范的GitHub发布说明，支持多种发布类型及破坏性变更处理。

.claude/skills/writing-releases/SKILL.md medusajs/medusa

Trigger Scenarios

需要生成版本发布说明基于提交列表起草Release描述

Install

npx skills add medusajs/medusa --skill writing-releases -g -y

More Options

Non-standard path

npx skills add https://github.com/medusajs/medusa/tree/develop/.claude/skills/writing-releases -g -y

Use without installing

npx skills use medusajs/medusa@writing-releases

指定 Agent (Claude Code)

npx skills add medusajs/medusa --skill writing-releases -a claude-code -g -y

安装 repo 全部 skill

npx skills add medusajs/medusa --all -g -y

预览 repo 内 skill

npx skills add medusajs/medusa --list

SKILL.md

Frontmatter

{
    "name": "writing-releases",
    "description": "Writes GitHub release notes for Medusa releases in the established style. Use when generating a draft release description from a list of commits and PR metadata. Covers minimal patch releases, single-highlight releases, multi-feature releases, and releases with breaking changes."
}

Writing Medusa Release Notes

Generates GitHub release notes from commit/PR data in the established Medusa style.

Constraints

Full Changelog link is mandatory — always the last line: **Full Changelog**: [vPREV...vNEW](compare-url)
No top-level Breaking Changes section — breaking changes are embedded inside their Highlight subsection with 🚧 Breaking change, never in a separate ## Breaking Changes heading
Bullet format is strict — every entry in Features/Bugs/Chores/etc. must include author link and PR link (see reference/format.md)
Highlights are not a summary of all PRs — only significant changes qualify; routine additions go in Features/Bugs bullets only (see reference/release-types.md)
No emojis — the only permitted emoji is 🚧 on breaking change highlights; use none anywhere else
Code block required for actionable steps — if a highlight requires the developer to install a package, run a command, or update config, include a fenced code block with the exact command(s)

Load Reference Files When Needed

Load at least one reference file before writing.

Task	Load
Formatting sections and bullets	`reference/format.md`
Deciding whether to write Highlights, and identifying breaking changes	`reference/release-types.md`
Writing the Highlights section	`reference/highlights.md`

Quick Reference

Release type decision

Commit set	Release type
Only routine fixes/chores, no user-facing impact	Minimal — no Highlights section
One important change is the main reason for the release	Single Highlight
Multiple significant features or fixes	Multi-Highlight
Any PR with a minor changeset in `.changeset/`	Add `🚧` to that Highlight

Section order (include only sections with entries)

## Highlights
## Features
## Bugs
## Documentation
## Chores
## Other Changes
## New Contributors
**Full Changelog**: [vPREV...vNEW](url)

Common Mistakes

Adding a title or # Heading at the top — release notes have no title, start directly with the first section
Adding a ## Breaking Changes top-level section — embed inside the Highlight instead
Putting a routine bug fix or small feature addition in Highlights
Missing the Full Changelog link at the end
Bullet missing author link or PR link
Using PR title verbatim as a Highlight heading — write a descriptive outcome-focused title
Treating every feat: commit as a Highlight candidate
Using emojis anywhere except 🚧 on breaking change highlights
Writing a Highlight that requires a developer action (install, run, config change) without a fenced code block

Reference Files

reference/format.md          — section order, bullet format, commit prefix → section mapping
reference/release-types.md   — when to add Highlights, breaking change detection, highlight criteria
reference/highlights.md      — how to write Highlight subsections