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

77%

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

81%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 skill body with concrete commands, templates, and validation checkpoints for all three release-note workflows. Its main weaknesses are duplicated overview prose that inflates token cost and references that rely on files outside the skill's own directory.

Suggestions

Remove the duplicated Insiders/Stable overview paragraphs — the descriptions repeated in the "Insiders Release Notes" and "Stable Release Notes" sections restate the intro nearly verbatim.

Consolidate the "Input parameters" gating rules (release version, milestone name) into a single shared section since they apply to both Insiders and Stable workflows.

Consider moving the writing-instruction dependencies into the skill's own references/ folder so the skill is self-contained and its links resolve reliably.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and imperative, but the Insiders and Stable overview paragraphs are duplicated nearly verbatim (the "Insiders release notes cover the latest features..." and "Stable release notes summarize..." text appears twice, plus two "Your task is..." statements), which is unnecessary padding that could be trimmed.	3 / 5
Actionability	Fully executable guidance throughout: a copy-paste-ready `gh search issues` command, exact file naming format (`v<version>.md`), a concrete markdown snippet for recovery-release notes, and before/after phrasing examples ("Add support for..." vs "...now supports...").	5 / 5
Workflow Clarity	Multi-step workflows for Insiders, Stable, and recovery releases are clearly sequenced with explicit validation checkpoints ("DO NOT continue until you have the release version and milestone name!!", "Verify that each candidate is available in the public Insiders build. Exclude and report internal-only candidates") and feedback loops (batched context-gap questions with best-guess drafts). The batch-update operation includes verification and exclusion reporting, so the missing-validation cap does not apply.	5 / 5
Progressive Disclosure	Well-organized sections with clearly signaled, one-level-deep references (templates, an example release note, the review procedure, writing instructions). Minor organization gap: several references point outside the skill bundle (../../instructions/, ../../../templates/) and no bundle files ship alongside this SKILL.md to back the referenced paths, which slightly weakens navigation reliability.	4 / 5
	Total	17 / 20 Passed

Description

65%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 distinctive, domain-specific description with good trigger keywords, but it lacks any explicit "when to use" guidance and describes actions in fairly generic terms. Adding a trigger clause and more concrete capability detail would raise completeness and specificity.

Suggestions

Add an explicit trigger clause, e.g. "Use when writing, reviewing, or updating VS Code Insiders or Stable release notes, or when the user mentions release notes, changelogs, or recovery releases."

Include the "VS Code" abbreviation and other natural synonyms (e.g., changelog) among trigger terms so the skill surfaces for the phrasings users actually type.

Enumerate more concrete capabilities (e.g., grouping closed milestone issues into dated sections, updating the TOC, applying endgame templates) to sharpen specificity.

Dimension	Reasoning	Score
Specificity	Names the specific domain (Visual Studio Code Insiders and Stable release notes) and a few actions ("writing and reviewing", "updating release notes for recovery releases"), but the verbs are generic and coverage is not comprehensive — no mention of TOC updates, milestone-driven issue fetching, or templates. This matches anchor 3 rather than 4, whose examples list several distinct concrete operations.	3 / 5
Completeness	The "what" is clear (guidelines for writing, reviewing, and updating VS Code release notes), but there is no "Use when..." clause or equivalent explicit trigger guidance anywhere, which caps completeness at 3. Not 4 because a 'when' element is required for 4.	3 / 5
Trigger Term Quality	Good natural keyword coverage: "release notes", "Insiders", "Stable", "Visual Studio Code", "recovery releases" are phrases users would naturally say. Not 5 because common synonyms like "VS Code" or "changelog" are missing.	4 / 5
Distinctiveness Conflict Risk	The description occupies a clear niche — VS Code Insiders/Stable/recovery release notes — with distinct trigger terms and virtually no overlap risk with other skills.	5 / 5
	Total	15 / 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: 279a4a7

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.