docs-product-alignment

Audit and update docs/copilot/ documentation to accurately reflect current VS Code AI capabilities. Use when: competitive analysis reveals gaps, product launches new features, docs use outdated framing, or keyword coverage needs strengthening for discoverability by users and AI agents. Produces a gap analysis plus targeted edits across affected files.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

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

Excellent content: lean, entirely non-redundant, and highly actionable with concrete page lists, terminology rules, and verification checks. The only gap is a missing error-recovery loop after the verify step, which keeps workflow clarity one point below the top anchor.

Dimension	Reasoning	Score
Conciseness	Every section carries project-specific knowledge Claude cannot know (the use/avoid terminology table, the high-traffic page list, capability areas, banned-word verification) with zero padding or explanation of known concepts.	5 / 5
Actionability	The guidance is fully concrete for an instruction-only skill: exact page paths to audit, a use/avoid terminology table, specific verification checks ("Search changed files for banned words, em-dashes, and MetaDescription length violations"), and an explicit escalation rule to ask the writer when framing is ambiguous.	5 / 5
Workflow Clarity	The 5-step sequence (context, audit, gap analysis, edit, verify) is clearly ordered with an explicit verification step containing specific checks, but there is no feedback loop describing what to do when verification fails, which matters for a batch-edit operation across many files.	4 / 5
Progressive Disclosure	A compact, well-sectioned body with no bundle files; the sole external reference (the docs-writing style guide) is clearly signaled with a link and section anchor one level deep, and the inline terminology table and page list are needed on every run so they belong in SKILL.md.	5 / 5
	Total	19 / 20 Passed

Description

83%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 with explicit what and when coverage, concrete deliverables, and a well-scoped niche. Weakest spots are trigger-term synonym coverage and action descriptions that name verbs rather than the specific artifacts being edited.

Suggestions

Add common user phrasings as triggers, e.g. 'Use when the user says the Copilot docs are out of date, inaccurate, or hurt discoverability/SEO' to broaden natural-term coverage.

Name the concrete edit targets in the description (e.g. MetaDescriptions, Keywords, opening paragraphs, terminology) instead of stopping at 'audit and update' and 'targeted edits'.

Dimension	Reasoning	Score
Specificity	"Audit and update docs/copilot/ documentation" and "Produces a gap analysis plus targeted edits across affected files" list several concrete actions scoped to a specific docs tree, but the actions stay at the verb level without naming the concrete edit targets (MetaDescriptions, Keywords, terminology) the body actually covers.	4 / 5
Completeness	Explicitly answers both "what" ("Audit and update docs/copilot/ documentation... Produces a gap analysis plus targeted edits") and "when" (an explicit "Use when:" clause with four concrete trigger conditions), matching the top anchor.	5 / 5
Trigger Term Quality	"Use when: competitive analysis reveals gaps, product launches new features, docs use outdated framing, or keyword coverage needs strengthening" provides good natural-phrase coverage, but misses common user variations like "docs are out of date", "update the Copilot docs", or "SEO".	4 / 5
Distinctiveness Conflict Risk	The docs/copilot/ scoping and VS Code AI-capability framing give it a clear niche, but generic phrases like "update documentation" leave minor overlap risk with a general documentation-editing skill.	4 / 5
	Total	17 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 10 suspicious	Warning

	Total	15 / 16 Passed

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