write-my-release-notes

Generate VS Code release notes for the features you worked on in a milestone. ALWAYS use this skill when the user asks to "write release notes for my features", "document my milestone features", or "generate release notes from my issues". It gathers the milestone features you own from GitHub, analyzes each feature and its related issues, and writes user-focused feature sections into the milestone release notes file.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

85%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A thorough, highly actionable skill body with a well-sequenced workflow, verification checkpoint, and clear external references. Its main weakness is mild redundancy around reconciling mislabeled features, which adds tokens without adding instruction.

Suggestions

Consolidate the 'mislabeled features should still be documented as features' guidance into one place (Step 2.5) and reference it from Step 3 and Build rather than restating it.

Add an explicit validate→fix→retry loop in 'Verify technical details' (e.g., re-check setting names/command IDs after correcting them) to match the workflow's feedback-loop pattern.

Tighten the 'Value proposition' guidance to remove the illustrative parentheticals ('buffer-based rendering' vs 'chat responses feel more fluid') once the rule is stated.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and assumes Claude's competence (no preamble on what release notes or gh are), but the 'treat mislabeled labels as features' point is restated across Step 2.5, Step 3, and the feature-gathering note, so it could be tightened.	2 / 3
Actionability	It provides copy-paste-ready `gh` search/view commands with exact `--json` fields, plus concrete formatting rules (setting(...), kb(...), link/screenshot alt conventions) — fully executable guidance.	3 / 3
Workflow Clarity	A clear numbered sequence (Step 0→1→2→2.5→3, Build, Verify, Write) with an explicit 'Verify technical details' checklist and feedback loops ('when in doubt... ask the user whether to include it').	3 / 3
Progressive Disclosure	Well-organized sections with clearly signaled one-level-deep references to the release-notes and docs writing instructions; the inline 'Key rules' act as a distilled overview pointing to the fuller referenced files. No bundle files are present to offload to.	3 / 3
	Total	11 / 12 Passed

Description

100%Weight 40%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, third-person description that states concrete actions, gives explicit 'use when' triggers in natural user phrasing, and occupies a distinct niche. Voice and trigger guidance both follow best practice.

Dimension	Reasoning	Score
Specificity	It lists multiple concrete actions — 'gathers the milestone features you own from GitHub, analyzes each feature and its related issues, and writes user-focused feature sections' — matching the multi-action anchor.	3 / 3
Completeness	It explicitly answers both what (generate/gather/analyze/write VS Code release notes) and when ('ALWAYS use this skill when the user asks to...'), with explicit trigger guidance.	3 / 3
Trigger Term Quality	It quotes natural user phrasings verbatim — 'write release notes for my features', 'document my milestone features', 'generate release notes from my issues' — covering the ways a user would actually ask.	3 / 3
Distinctiveness Conflict Risk	The VS Code milestone feature-documentation niche is narrow and its triggers are specific to release-notes-from-issues requests, making overlap with other skills unlikely.	3 / 3
	Total	12 / 12 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 2 suspicious	Warning

	Total	14 / 16 Passed

Repository: microsoft/vscode-docs
Path: .github/skills/write-my-release-notes/SKILL.md
Commit: 66977a9

Reviewed: 10 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.