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

95%

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

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

A tight, well-structured two-phase workflow skill with concrete guardrails, a clear approval checkpoint, and clean single-level references; it earns full marks across all content dimensions.

Dimension	Reasoning	Score
Conciseness	Lean instruction-only body that assumes Claude's competence — no concept padding, no library tutorials; every section (guardrails, two phases, the area→repo table) carries task-specific value, with only minor reinforcement of the approval gate across phases.	3 / 3
Actionability	Concrete, executable guidance for an instruction skill: names the exact source repos per area, specifies 'never edit enterprise/policies.md' vs 'policies-template.md', links the style guide, and prescribes TODO placeholders for screenshots — no vague 'process the docs' direction.	3 / 3
Workflow Clarity	Two-phase workflow is clearly sequenced with an explicit validation checkpoint ('Stop and wait for approval' before Phase 2) and a feedback loop for the no-update case ('say so and ask the user to confirm'); the approval gate serves as the validation step for the doc-editing operation.	3 / 3
Progressive Disclosure	Well-organized into clear sections with one-level-deep, clearly signaled references (style guide link, gh-cli memory, source repos); no nested reference chains, and the body is short enough that the section structure alone justifies a top score.	3 / 3
	Total	12 / 12 Passed

Description

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

A strong, well-scoped description with explicit triggers and clear capabilities; the only ding is the second-person 'you approve' phrasing, which costs a specificity point under the rubric's voice rule.

Suggestions

Rephrase 'until you approve the plan' in third person (e.g., 'until the user approves the plan') to avoid the second-person voice penalty and recover the specificity point.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions ('Plan and write VS Code documentation', 'Proposes a documentation plan and asks clarifying questions', 'does not edit any files until you approve'), which would be a 3, but the second-person phrasing 'until you approve the plan' triggers the rubric's voice penalty, reducing specificity by one.	2 / 3
Completeness	Explicitly answers both 'what' (plan and write VS Code docs, propose a plan, ask clarifying questions) and 'when' via an explicit 'ALWAYS use this skill when...' trigger clause, satisfying the anchor for full completeness.	3 / 3
Trigger Term Quality	Covers natural phrasings a user would actually say — 'document', 'add docs for', 'write docs for', 'update the docs for' — plus the GitHub issue/PR link trigger, giving good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	Scoped to a clear niche — VS Code feature documentation — with specific triggers unlikely to fire for adjacent tasks; the 'even if the change seems small' guidance further narrows it against competing doc-editing skills.	3 / 3
	Total	11 / 12 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: 2 suspicious	Warning

	Total	14 / 16 Passed

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