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

75%

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

70%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, actionable operational guidance with unusually explicit validation checkpoints and gating across all three workflows, though it is held back by verbatim duplicated sections and by bundle references that point to files that are not present. Progressive disclosure is further weakened by three paths that escape the skill directory entirely.

Suggestions

Remove the verbatim duplication: the intro's descriptions of Insiders and Stable release notes are repeated word-for-word under their own H2 headings, and the public-availability rule appears in three places — state each once and cross-reference.

Ship the referenced bundle files (examples/v1_109.md, review-procedure.md) or fix/remove the links, and verify the ../../instructions/... and ../../../templates/... paths actually resolve for skill consumers.

Provide a concrete subagent prompt template (inline or as a reference file) for the per-issue update step, since "run a subagent to update the release notes... with a concise, technically accurate summary" leaves the most-executed step underspecified.

DimensionReasoningScore

Conciseness

The two note-type descriptions ("Insiders release notes cover the latest features... sections grouped by the date of the updates") are repeated verbatim in the intro and again under their H2 headings, and the public-availability rule appears in three places (general guidelines, Insiders step 7, Stable step 4). Matches anchor 3 ("Mostly efficient but includes some unnecessary explanation or could be tightened"): not 4 because verbatim duplication of two full paragraphs exceeds minor trimming, and not 2 because the bulk is dense, non-obvious operational guidance with no padding or explanations of things Claude already knows.

3 / 5

Actionability

Concrete, executable guidance throughout: the exact CLI command "gh search issues --repo microsoft/vscode --label <label name> --milestone <milestone name> --state closed \"closed:>=<latest update date>\" -L 100", the filename format "v<version>.md, e.g., v1_109.md", a copy-paste recovery-note markdown snippet, and before/after phrasing examples ("Add support for sorting sessions by date" vs "The sessions view now supports sorting by date"). Matches anchor 4 ("Mostly executable guidance... with minor gaps"): not 5 because the referenced templates and example files are missing from the bundle and the per-issue subagent step ("run a subagent to update the release notes... with a concise, technically accurate summary") provides no concrete subagent prompt; not 3 because the commands, formats, and snippets given are directly executable.

4 / 5

Workflow Clarity

All three workflows are clearly sequenced with explicit validation checkpoints: hard gating ("DO NOT continue until you have the release version and milestone name!!"), candidate filtering ("Require a directly associated, merged implementation PR for each candidate before drafting an entry"), availability verification ("Verify that each remaining candidate is available in the public Insiders build. Exclude and report internal-only candidates"), a review loop ("perform a code review of the existing release note"), and a checklist for gap resolution ("Ask when: Value prop unclear... Multi-release context missing..."). Matches anchor 5 ("Clear sequence with explicit validation steps; feedback loops...; checklists"): the batch issue-processing workflow includes validation, so the missing-validation cap does not apply, and 4 would undersell the explicit checkpoints, exclusion reporting, and ask-when checklist present in every workflow.

5 / 5

Progressive Disclosure

The body has a clear H2/H3 structure with well-signaled links ("[this template](../../../templates/template-release-note-insiders.md)", "[1.109 release notes](./examples/v1_109.md)", "follow the full [review procedure](./review-procedure.md)"), but the bundle contains only SKILL.md — ./examples/v1_109.md and ./review-procedure.md do not exist, and three paths (../../instructions/..., ../../../templates/...) resolve outside the skill directory. Matches anchor 3 ("Some structure but could be better organized"): not 4 because dangling references are more than a minor organization gap, and not 2 because the body itself is well sectioned, not a monolithic wall of text.

3 / 5

Total

15

/

20

Passed

Description

70%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 carves a distinctive niche and names several concrete actions with good natural keywords, but it never tells Claude when to activate — there is no "Use when..." clause, which caps completeness at 3. It also omits common synonyms like "VS Code" that users would naturally say.

Suggestions

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

Include natural synonyms users would say, such as "VS Code" (not just "Visual Studio Code") and "changelog", to broaden trigger-term coverage.

Mention the core generation capability (building entries from closed GitHub issues/PRs in a milestone) so the action list is comprehensive rather than partial.

DimensionReasoningScore

Specificity

Quotes: "writing and reviewing Insiders and Stable release notes for Visual Studio Code", "updating release notes for recovery releases" — it names the domain and three concrete actions (write, review, update-for-recovery). Matches anchor 4 ("Lists several specific actions; minor gaps in coverage"): not 5 because the skill's fuller capabilities (generating entries from closed GitHub issues/PRs, template application, TOC updates) are unmentioned, and not 3 because it lists several actions rather than 1-2.

4 / 5

Completeness

The "what" is clear ("Guidelines for writing and reviewing Insiders and Stable release notes... updating release notes for recovery releases") but there is no "Use when..." clause or equivalent explicit trigger guidance, capping completeness at 3 per the judging guidelines. Not 4 because "when" is entirely absent rather than merely imprecise; not 2 because the "what" half is concrete and complete.

3 / 5

Trigger Term Quality

Quotes: "release notes", "Insiders and Stable", "Visual Studio Code", "recovery releases" — the core natural terms a user would say are present. Matches anchor 4 ("Good keyword coverage; a few natural terms missing"): not 5 because common synonyms like "VS Code" and "changelog" are absent, and not 3 because the primary natural phrases are all explicitly included.

4 / 5

Distinctiveness Conflict Risk

Quotes: "Insiders and Stable release notes for Visual Studio Code", "recovery releases" — a narrow, well-defined niche with distinct, product-specific triggers. Matches anchor 5 ("Clear niche with distinct triggers; minimal conflict risk"): not 4 because the combination of VS Code, Insiders/Stable, and recovery releases makes overlap with any other skill extremely unlikely.

5 / 5

Total

16

/

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 possibly missing (./examples/v1_109.md, ./review-procedure.md), 4 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.