release-note-writer

Guidelines for writing and reviewing Insiders and Stable release notes for Visual Studio Code. This also includes instructions for updating release notes for recovery releases.

Quality

63%

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

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/release-note-writer/SKILL.md

Quality

Content

67%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.

The content is well-structured, actionable, and workflow-oriented with explicit validation and gating steps, but it carries duplicated introductory paragraphs and leaves a few subagent-driven steps at a high level.

Suggestions

Remove the verbatim duplication of the Insiders and Stable overview paragraphs (lines 28 and 78) since they already appear in the opening overview, replacing them with a one-line pointer.

Tighten the abstract "run a subagent to update the release notes" steps with the specific inputs/outputs the subagent should produce so the guidance is fully executable.

Make the validate-fix-retry loop explicit for the batch issue-fetch step (e.g., what to do when a candidate fails the public-availability check beyond "exclude and report").

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and assumes Claude's competence, but the Insiders and Stable section intros verbatim repeat paragraphs already stated in the opening overview, which is unnecessary padding that could be tightened.	3 / 5
Actionability	Provides concrete, copy-paste-ready guidance including an explicit `gh search issues ...` command, file naming formats, image filenames, template links, and a recovery-release markdown snippet; minor gaps remain in the abstract "run a subagent to update" steps.	4 / 5
Workflow Clarity	Insiders, Stable, and recovery flows are clearly sequenced with explicit gating ("DO NOT continue until you have the release version and milestone name!!") and verification checkpoints ("Verify that each candidate is available in the public Insiders build"), though full validate-fix-retry feedback loops are not spelled out.	4 / 5
Progressive Disclosure	Well-organized into clear sections with one-level-deep, clearly signaled references (writing instructions, templates, examples, review-procedure.md); no bundle files are present in the skill directory, and content is appropriately split rather than inlined.	4 / 5
	Total	15 / 20 Passed

Description

58%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.

The description clearly communicates a focused niche (VS Code release notes) with concrete actions and good distinctiveness, but it lacks an explicit "Use when..." trigger clause and relies on a narrow set of trigger terms.

Suggestions

Add an explicit "Use when..." trigger clause, e.g. "Use when writing or reviewing VS Code Insiders or Stable release notes, or updating notes for a recovery release."

Broaden trigger terms with natural synonyms such as "changelog" or "endgame notes" that users may actually say.

Dimension	Reasoning	Score
Specificity	Names the domain (VS Code release notes) and several concrete actions across three note types — "writing and reviewing Insiders and Stable release notes" and "updating release notes for recovery releases" — giving broad but not exhaustively detailed coverage.	4 / 5
Completeness	The "what" is clearly stated, but there is no "Use when..." clause or equivalent explicit trigger guidance, so per the rubric completeness is capped at 3.	3 / 5
Trigger Term Quality	"release notes", "Insiders", "Stable", "Visual Studio Code", and "recovery releases" are relevant natural terms, but the trigger vocabulary centers on one phrase with sub-type variations rather than distinct synonyms a user would voice (e.g. "changelog").	3 / 5
Distinctiveness Conflict Risk	The VS Code Insiders/Stable release-notes niche is specific with minimal conflict risk, though there is minor overlap with general documentation-writing skills.	4 / 5
	Total	14 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 2 missing, 5 suspicious	Warning

	Total	15 / 16 Passed

Repository: microsoft/vscode-docs
Path: .github/skills/release-note-writer/SKILL.md
Commit: 193d3e4

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