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

87%

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

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 well-structured, plan-first instructional skill with concrete guardrails, an explicit approval gate, and strong validation checkpoints throughout both phases. The workflow is exemplary; the remaining gains are minor tightening of repeated statements and moving detail content into bundle reference files.

Suggestions

Trim repetition between the intro and Phase 1 (the 'no documentation update needed' outcome and the 'no edits before approval' rule are each stated twice) to improve conciseness.

Move the source-repo mapping table and content-framing details into a references/ bundle file (e.g. references/source-repos.md), keeping SKILL.md a leaner overview with one-level-deep links.

Make the Phase 2 implementation steps more concrete (e.g. example edit patterns or a checklist of style-guide checks) so 'apply the documentation edits exactly as agreed' becomes fully actionable.

Dimension	Reasoning	Score
Conciseness	Mostly lean and operational, but there is some repetition: 'no documentation update is needed' appears in both the intro and Phase 1 step 6, and 'do not start editing docs directly without first running Phase 1' duplicates the 'Stop and wait for approval' checkpoint. Efficient overall with minor trimming possible, so anchor 4 rather than 5.	4 / 5
Actionability	Concrete guidance throughout: named files (build/sitemap.xml, docs/toc.json, enterprise/policies-template.md), exact user-question options, a source-repo mapping table, and a TODO-screenshot convention. A few steps remain high-level ('Apply the documentation edits exactly as agreed'), so not fully copy-paste ready per anchor 5.	4 / 5
Workflow Clarity	Two clearly sequenced phases with explicit validation checkpoints and error-recovery loops: 'Stop and wait for approval', mandatory branch confirmation before edits, handling of uncommitted changes ('stop and explain the conflict instead of stashing'), and a final verify-and-summarize step. Matches the anchor-5 pattern.	5 / 5
Progressive Disclosure	No bundle files exist, and the body is well-sectioned with one-level-deep, clearly signaled links (../../instructions/docs-writing.instructions.md, the gh-cli memory file). Minor gap: content like the source-repo table and content-framing guidance could live in a references/ file to keep SKILL.md a leaner overview, so anchor 4 rather than 5.	4 / 5
	Total	17 / 20 Passed

Description

91%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 and explicitly states both capability and trigger conditions in third person, with natural user phrasings. The only weaknesses are minor: it omits the navigation-metadata maintenance aspect and defers all boundary/exclusion guidance to the body.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions in third person ('Plan and write VS Code documentation', 'Proposes a documentation plan', 'asks clarifying questions', 'does not edit any files until you approve the plan'). Not a 5 because coverage has minor gaps, e.g. updating navigation metadata for existing docs is not mentioned.	4 / 5
Completeness	Explicitly answers both what ('Plan and write VS Code documentation... Proposes a documentation plan') and when ('ALWAYS use this skill when the user asks to...') with concrete trigger phrases, matching the anchor-5 example.	5 / 5
Trigger Term Quality	Comprehensive natural trigger phrasings users would actually say: 'document', 'add docs for', 'write docs for', 'update the docs for', plus 'GitHub issue/PR link to document'. Clearer than the anchor-4 example, which only lists a few terms with some missing.	5 / 5
Distinctiveness Conflict Risk	Clear niche (VS Code feature documentation) with distinct triggers, but the description itself does not carve out adjacent skills (release notes, redirects, copy-edits are only excluded in the body), leaving minor overlap risk with sibling doc skills.	4 / 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: 279a4a7

Reviewed: 9 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.