Build the "Release Notes Writer" Skill

Problem / Feature Description

A developer tools company wants to add a new AI skill to their internal skill library: release-notes-writer. This skill will help engineers generate polished release notes from a list of merged PRs and commit messages. The team has been doing this manually for years and keeps producing inconsistent output — some releases have detailed notes, others just say "bug fixes and improvements."

You have been asked to create this skill from scratch. Because this is a new skill with no prior documentation, you need to gather requirements before you start building anything.

The team lead — Jordan — has agreed to answer your questions. Your task has two parts:

Part 1 — Document your interview plan. Before conducting any interview, write out your full interview plan as interview-plan.md. This should describe every question you intend to ask Jordan, what options you would present for each question, and how you will decide when you have enough information to proceed. This document will be shared with other team members who may conduct similar interviews in the future, so it should be thorough and reusable.

Part 2 — Scaffold the skill. Jordan's answers are provided below. Using those answers, produce the initial skill scaffold: at minimum SKILL.md and tile.json.

Output Specification

• interview-plan.md — your full interview plan, including all questions and their answer options
• skills/release-notes-writer/SKILL.md
• skills/release-notes-writer/tile.json

Input Files

The following file contains Jordan's answers to your interview questions. Use these to produce the scaffold.

=============== FILE: inputs/jordan-answers.md ===============

Jordan's Interview Answers — release-notes-writer skill

What does the skill do / what problem does it solve? It takes a list of merged PRs (titles, labels, authors) and a target version number, then produces a formatted release notes document. The audience is external customers, so tone should be user-facing, not internal jargon.

What phrases or situations should trigger this skill? "write release notes", "generate changelog for this release", "draft release notes for v2.3", "help me write the release announcement". Also triggers if someone pastes a list of PRs and asks for a summary for customers.

What steps must the skill always perform, no matter what? Always group PRs by label (features, bug-fixes, breaking-changes). Always include a "Breaking Changes" section at the top if any breaking-change PRs are present — even if there's just one. Always output a version header with the release date.

What are the common mistakes or things that can go wrong? PRs without labels are easy to miss — they must go into an "Other" or "Uncategorised" section, never silently dropped. Version numbers can be ambiguous (1.2 vs 1.2.0) — always normalise to semver. Draft PRs sometimes get included accidentally — always filter them out.

What sub-steps does the workflow involve?

1. Parse the PR list and extract title, labels, author, PR number.
2. Filter out draft PRs.
3. Normalise version number to semver.
4. Group PRs by primary label.
5. Sort within each group: breaking-changes, features, bug-fixes, other.
6. Write the Markdown document with a version header and dated sections.
7. Output to release-notes-<version>.md.

What does the skill produce? A Markdown file: release-notes-<version>.md. Optionally a JSON summary: release-summary-<version>.json with counts per category.

Are there existing patterns or tools the team already uses? The team uses GitHub labels consistently. PRs are listed in JSON from gh pr list --json title,labels,author,number,isDraft. The Markdown follows the Keep a Changelog format loosely.

How will you know the skill is working well? Release notes are ready to paste into the GitHub release form without editing. No PRs are missing. Breaking changes always appear first.

What should the skill never do? Never include draft PRs. Never silently drop unlabelled PRs. Never use internal jargon or commit hashes in the customer-facing output.

Are there any companion reference files that would help? A label taxonomy reference (what each GitHub label maps to in the output) would be useful. Maybe a template for the version header section.