doc-writer

Plan and write VS Code documentation for a new or updated feature. ALWAYS use this skill when the user asks to "document", "add docs for", "write docs for", or "update the docs for" a feature, or provides a GitHub issue/PR link to document — even if the change seems small. Proposes a documentation plan and asks clarifying questions first — it does not edit any files until you approve the plan.

Quality

82%

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

Quality

Content

75%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 well-structured, lean instruction-only skill with concrete file and tool guidance plus a strong plan-first approval gate. It falls just short of top marks because the public-availability check is somewhat abstract and there is no error-recovery feedback loop.

Suggestions

Make 'Verify public availability' more executable by naming the concrete signals to check (e.g., a grep for `included: false`, the product quality-gate config, or the Insiders/Preview label) rather than listing categories.

Add an explicit feedback loop for Phase 2 (e.g., re-verify against the approved plan and the style guide after edits, with a retry path if a guardrail is violated).

De-duplicate the release-notes/API-docs exclusion between the 'When to Use' section and the Guardrails to trim a little redundancy.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence — no padding about what VS Code or docs are — with only minor repetition between the 'When to Use' exclusions and the Guardrails section that could be tightened.	4 / 5
Actionability	Concrete, specific guidance throughout — named files (docs/, enterprise/policies-template.md), a source-repo mapping table, the gh CLI, TODO placeholders for screenshots — with the 'Verify public availability' step being slightly more abstract than a concrete check.	4 / 5
Workflow Clarity	A clear two-phase sequence with an explicit approval checkpoint ('Stop and wait for approval') and a plan-summary checklist, but it lacks the validate→fix→retry error-recovery loop that characterizes the top anchor.	4 / 5
Progressive Disclosure	Well-organized into clear sections (When to Use, Guardrails, Phase 1, Phase 2) with one-level-deep, clearly signaled references to the style guide; no bundle files exist to split further, and minor organization gaps remain.	4 / 5
	Total	16 / 20 Passed

Description

90%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 strong description that clearly states both capability and explicit trigger conditions with comprehensive natural-language phrasing. The only weakness is a voice lapse into second person ('you approve'), which costs specificity points.

Suggestions

Rewrite in consistent third person: replace 'until you approve the plan' with 'until the user approves the plan' to avoid the second-person voice penalty.

Consider naming the concrete artifacts produced (e.g., 'drafts or updates markdown articles in the docs/ folder') to make the actions more tangible.

Dimension	Reasoning	Score
Specificity	Names the domain (VS Code documentation) and several concrete actions ('Plan and write', 'Proposes a documentation plan', 'asks clarifying questions'), but the second-person phrasing 'until you approve the plan' triggers the -1 voice penalty, bringing it from a 4 down to 3.	3 / 5
Completeness	Explicitly answers both what (plan and write VS Code docs, propose plan, ask clarifying questions, no edits until approval) and when (concrete trigger phrases prefixed by 'ALWAYS use this skill when').	5 / 5
Trigger Term Quality	Comprehensive natural trigger coverage including synonyms users actually say — 'document', 'add docs for', 'write docs for', 'update the docs for' — plus the GitHub issue/PR link case.	5 / 5
Distinctiveness Conflict Risk	Clear niche (VS Code feature documentation in docs/) with distinct triggers and explicit carve-outs from sibling skills like release-note-writer and content-redirect, minimizing wrong-skill triggering.	5 / 5
	Total	18 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 3 suspicious	Warning

	Total	14 / 16 Passed

Repository: microsoft/vscode-docs
Path: .github/skills/doc-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.