Case Study: A Release-Notes Skill for a Team

From a repeated chore to a shared skill

The team writes release notes every two weeks and each time explains the format again. Scope: draft notes from merged PRs since the last tag; read-only except for writing one Markdown file. Folder: .claude/skills/release-notes/ with SKILL.md, scripts/prs_since_tag.py (prints merged PRs as JSON using git log), references/style-guide.md (tone, grouping, what to skip), and templates/notes.md. Description: names the job, says when to use it, lists trigger phrases ("release notes, changelog, what shipped, what changed"). Body: steps (run the script, group entries, apply the style guide, fill the template), a verification step (every PR number in the notes appears in the script output), and gotchas (skip dependency bumps; never invent PR numbers). Safety: allowed-tools limited to that one script; no network; no secrets. Testing: 6 should-trigger and 6 should-not prompts; script tests with a fixture repository; two real releases tried and transcripts read to fix a missing gotcha. Sharing: committed to the repo, reviewed in a PR like code, an owner named, and the skill updated whenever the release process changes.

A small, sharp, tested, reviewed skill

Sharp description, focused body, deterministic scripts, tests, and review make a skill the whole team can trust.

The checklist on one page

Each line maps to a section of this course.

Scope        one job; says what it does NOT do                                   (Sec 2)
Description  what + when + trigger phrases; validated; tested both ways                   (Sec 2, 5)
Body         steps, expected output, verification step, gotchas; < 500 lines              (Sec 2)
Files        script (JSON out, exit codes), style guide reference, template                (Sec 3)
Safety       allowed-tools = that one script; no secrets; fetched text is data             (Sec 3, 6)
Testing      should / should-not prompts; script tests on fixtures; read transcripts        (Sec 5)
Sharing      .claude/skills in git, PR review, owner, update with the process              (Sec 4)

Measure the benefit

Compare the time to produce release notes before and after the skill.

Quick check: Why is the skill committed to the repository?

• To hide it from teammates
• Because skills only work in git
• So the team shares it, reviews changes like code and keeps it versioned
• Because it is required by Markdown