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

71%

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

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.

The body is highly actionable and well-sequenced with explicit validation gating and clean one-level-deep references. Its main weakness is redundancy from verbatim-duplicated overview paragraphs, which could be consolidated to improve token efficiency.

Suggestions

Remove the verbatim duplication of the Insiders and Stable descriptions between the intro (lines 9-15) and their dedicated sections, keeping each description in only one place.

Tighten or cut the 'This skill is designed to help you write release notes...' opener, which restates what the title and description already convey.

Consider adding an explicit validate-and-retry note for the subagent-driven issue-summaries step to reinforce the existing gating checkpoints.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and instructional, but the Insiders and Stable overview paragraphs are duplicated verbatim in their dedicated sections (lines 11/26 and 13/74) and the 'This skill is designed to help you...' opener is padding, fitting the 'mostly efficient but could be tightened' anchor.	2 / 3
Actionability	Provides fully executable guidance: a concrete 'gh search issues' CLI command, exact file paths and filename formats, named templates, and a copy-paste-ready recovery markdown snippet, matching the 'fully executable code/commands' anchor.	3 / 3
Workflow Clarity	Multi-step generation processes are numbered and gated with explicit validation checkpoints ('DO NOT continue until you have the release version and milestone name!!') plus a 'Verify context gaps with the user' feedback loop, matching the 'clear sequence with explicit validation steps' anchor.	3 / 3
Progressive Disclosure	No bundle files exist, so this is scored on signaling: the body is an overview pointing to one-level-deep, clearly signaled markdown links (writing instructions, templates, an example release note, and the review procedure), matching the 'clear overview with well-signaled one-level-deep references' anchor.	3 / 3
	Total	11 / 12 Passed

Description

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

The description clearly identifies a specific niche and names relevant actions, but it lacks an explicit 'Use when...' trigger clause, capping completeness and trigger-term quality at the midpoint. Adding explicit usage triggers would raise the score across the completeness and trigger dimensions.

Suggestions

Append an explicit 'Use when...' clause, e.g. 'Use when writing, reviewing, or updating VS Code Insiders, Stable, or recovery release notes.'

Expand trigger terms with common variations a user might say, such as 'VS Code release notes', 'changelog', or 'endgame notes'.

Enumerate a few more concrete actions (e.g. 'generate from GitHub issues and PRs, update the TOC, frame feature value propositions') to strengthen specificity.

Dimension	Reasoning	Score
Specificity	Names a concrete domain (VS Code Insiders and Stable release notes) and some actions ('writing and reviewing', 'updating'), matching the 'names domain and some actions' anchor rather than a broad list of specific actions.	2 / 3
Completeness	Clearly states what the skill does but provides no 'Use when...' clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 2.	2 / 3
Trigger Term Quality	Includes natural terms a user would say ('release notes', 'Visual Studio Code', 'Insiders and Stable') but lacks common variations, fitting the 'some relevant keywords but missing common variations' anchor.	2 / 3
Distinctiveness Conflict Risk	The niche is narrow and specific to VS Code Insiders/Stable/recovery release notes, making it clearly distinguishable and unlikely to trigger for the wrong skill.	3 / 3
	Total	9 / 12 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: 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.