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

86%

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

75%Weight 40%Scale 1-5

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

A highly actionable, well-sequenced workflow skill with concrete commands and real validation checkpoints. Its main weaknesses are redundant restatements of the MCP/gh fallback and mislabeled-feature rules that inflate token cost, and the absence of an explicit feedback loop after verification.

Suggestions

State the 'prefer the GitHub MCP server, fall back to gh' rule once (in Prerequisites) and delete its repetition in the 'Identify features' intro and Step 3.

Consolidate the mislabeled-feature judgment guidance into Step 2.5 and reference it from Step 3 instead of restating the 'Treat those as features too' rule.

Add a brief feedback loop after 'Verify technical details': what to do when a setting/command does not exist or a link fails (fix and re-verify before writing to the file).

Dimension	Reasoning	Score
Conciseness	Mostly efficient direct instruction with no tutorials on known concepts, but notable repetition: the prefer-MCP/fallback-to-gh rule is stated three times (Prerequisites, 'Identify features' intro, Step 3), the mislabeled-feature rule appears in both Step 2.5 and Step 3, and Step 0's memory guidance is re-explained in Step 2.5. This goes beyond the 'minor instances that could be trimmed' of the 4 anchor.	3 / 5
Actionability	Fully executable guidance: concrete `gh search issues` / `gh issue view` commands with exact `--json` field lists, an exact file-discovery method (search for 'TOCTitle: <milestone name>'), a filename convention ('v<version>.md'), and explicit label filters. Copy-paste ready with specific handling for the common cases.	5 / 5
Workflow Clarity	A clearly sequenced multi-step workflow (Steps 0, 1, 2, 2.5, 3) with checkpoints: a user-confirmation gate for the milestone name, a reconciliation pass in Step 2.5, and a 'Verify technical details' section. The batch-operation cap at 3 does not apply since verification is present, but there is no explicit validate-fix-retry feedback loop, so it falls short of the 5 anchor.	4 / 5
Progressive Disclosure	No bundle files exist (no references/, scripts/, or assets/), so all content lives in SKILL.md. The body points one level out to '../../instructions/release-notes-writing.instructions.md' and '../../instructions/docs-writing.instructions.md' with an inline 'Key rules' summary — an appropriate split for an instruction-only skill with well-organized sections. Minor gap: detailed writing-style rules and the reconciliation procedure could live in a reference file, and the referenced instruction files sit outside the bundle.	4 / 5
	Total	16 / 20 Passed

Description

95%Weight 40%Scale 1-5

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 description: concrete, comprehensive action list with explicit multi-phrase trigger guidance and a clearly bounded niche. The only defect is second-person voice ('you worked on', 'you own') where third person is required.

Suggestions

Rewrite in third person: replace 'for the features you worked on' and 'features you own' with e.g. 'for the features the user worked on' / 'the user's milestone features' to satisfy the third-person voice requirement.

Dimension	Reasoning	Score
Specificity	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 into the milestone release notes file'), which matches the comprehensive 5 anchor. However, the second-person phrasing ('for the features you worked on', 'features you own') violates the third-person voice rule, reducing the score by 1 per the judging guidelines.	4 / 5
Completeness	Explicitly answers both what ('gathers... analyzes... writes user-focused feature sections') and when ('ALWAYS use this skill when the user asks to...') with concrete quoted trigger phrases, exactly matching the 5 anchor.	5 / 5
Trigger Term Quality	Provides three verbatim natural user phrases ('write release notes for my features', 'document my milestone features', 'generate release notes from my issues') alongside supporting terms like release notes, milestone, and issues — comprehensive synonym coverage of what a user would actually say.	5 / 5
Distinctiveness Conflict Risk	The niche is narrow and clearly bounded (VS Code milestone release notes generated from GitHub issues) with distinct trigger phrases, so it is unlikely to fire for the wrong skill or conflict with generic documentation skills.	5 / 5
	Total	19 / 20 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: 279a4a7

Reviewed: 9 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.