CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

70%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

63%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 body delivers strong, executable workflow guidance with genuine validation checkpoints for a batch content-generation task, held back by verbatim duplicated overview paragraphs and a bundle whose referenced files (examples/v1_109.md, review-procedure.md) are missing. Tightening the duplication and shipping or inlining the referenced files would make this a high-scoring skill.

Suggestions

Remove the verbatim duplication: the Insiders and Stable descriptions in the opening numbered list repeat word-for-word under their respective section headers; keep only one copy of each.

Ship the referenced bundle files (./examples/v1_109.md and ./review-procedure.md) or inline their essentials — both links are broken in the current bundle, and the Review Procedure section depends entirely on the missing file.

Fix the repeated typo "Your task is help generate" → "Your task is to help generate", and add a brief error-recovery note for the gh search step (e.g., what to do when no issues match the milestone and label).

DimensionReasoningScore

Conciseness

The body is mostly lean imperative instructions, but the Insiders and Stable overview paragraphs ("Insiders release notes cover the latest features and updates... based on closed GitHub issues and PRs for a specific milestone" / "Stable release notes summarize the key features...") are duplicated verbatim between the opening list and their own sections, and "Your task is help generate these release notes..." repeats with a typo. It is not a 2 because there is no padding or explanation of concepts Claude already knows, and not a 4 because whole-paragraph verbatim duplication is more than a minor trim.

3 / 5

Actionability

Concrete, executable guidance dominates: a copy-paste gh CLI command with exact flags, file naming format ("v<version>.md, e.g., v1_109.md"), a copy-paste markdown snippet for recovery notes, the issue-link format ("#12345: Issue title"), and before/after phrasing examples. It is not a 5 because several steps defer detail to placeholders or missing files ("run a subagent to update the release notes and TOC" is underspecified), and not a 3 because the core commands and formats are directly executable.

4 / 5

Workflow Clarity

All three workflows (Insiders, Stable, Recovery) have clearly numbered, well-sequenced steps with explicit validation checkpoints: input gating ("DO NOT continue until you have the release version and milestone name!!"), public-availability verification, duplicate/not-planned filtering, and a batched context-gap review. It is not a 5 because there are no error-recovery feedback loops (e.g., what to do when the gh search returns nothing or a subagent summary fails) and the TOC-update step is vague; it is above a 3 because validation is explicit and present throughout.

4 / 5

Progressive Disclosure

Section organization within SKILL.md is clear with sensible one-level pointers, but two in-bundle references are broken — "[this template](../../../templates/...)", "[1.109 release notes](./examples/v1_109.md)" and "[review procedure](./review-procedure.md)" point at files that are not present in the bundle (only SKILL.md exists), and the ../../instructions and ../../../templates references escape the skill directory entirely. It is not a 2 because the SKILL.md itself is well structured rather than an inlined blob, and not a 4 because a whole section (Review Procedure) defers to a missing file and the concrete-example link is broken.

3 / 5

Total

14

/

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.

The description identifies a well-scoped, distinctive niche and uses the natural vocabulary of its users, but it describes only what the skill covers and never says when it should be invoked. Adding an explicit trigger clause and one or two more concrete actions would raise it substantially.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks to write, update, or review VS Code release notes for an Insiders or Stable milestone, or to document a recovery release."

Sharpen the 'what' with one or two concrete actions, such as generating Insiders entries from closed GitHub issues/PRs in a milestone or following the Stable endgame template.

Include common synonyms such as "changelog" or "release documentation" so the description matches more of the phrases users naturally say.

DimensionReasoningScore

Specificity

The description names a specific domain ("Insiders and Stable release notes for Visual Studio Code") and 2-3 actions ("writing and reviewing", "updating release notes for recovery releases"), but the actions are generic verbs with no concrete detail about what the skill actually produces or how. It matches the 'names domain and 1-2 concrete actions, but not comprehensive' anchor; it is not a 4 because writing/reviewing/updating are high-level verbs rather than several specific actions, and not a 2 because three distinct actions are named.

3 / 5

Completeness

The 'what' is clear (guidelines for writing, reviewing, and updating VS Code release notes, including recovery releases), but there is no 'Use when...' clause or equivalent explicit trigger guidance, capping completeness at 3 per the judging guidelines. It is not a 4 because 'when' is entirely absent rather than just imprecise, and not a 2 because the 'what' is specific and multi-part.

3 / 5

Trigger Term Quality

It contains the natural phrases a VS Code contributor would say — "release notes", "Insiders", "Stable", "recovery releases", "Visual Studio Code" — giving good keyword coverage. It falls short of a 5 because common variations like "changelog" or release-documentation synonyms are missing, and it is above a 3 since the core natural terms are all present rather than only partially covered.

4 / 5

Distinctiveness Conflict Risk

"Insiders and Stable release notes for Visual Studio Code" plus "recovery releases" carves out a clear niche with distinct triggers and minimal overlap risk with other skills. It is not a 4 because no closely related skill domain (general changelogs, generic docs writing) plausibly competes for these exact triggers.

5 / 5

Total

15

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.