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

87%

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

86%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 compact, well-structured instruction-only skill with a clear workflow and explicit verification step. The main gap is the absence of an explicit fix-and-re-verify feedback loop in the batch-edit Verify step.

Suggestions

Add an explicit error-recovery loop to the Verify step: if banned words, em-dashes, or MetaDescription violations are found, fix them and re-run the checks until clean — this would lift workflow_clarity from 4 to 5.

Name the specific tool or command used to search for banned words / measure MetaDescription length (e.g., a grep pattern or length check) to make the Verify step copy-paste executable and raise actionability.

Clarify the cross-reference to docs-writing.instructions.md so it is obvious it is a shared repo-level guide, reducing any navigation ambiguity for the progressive-disclosure dimension.

Dimension	Reasoning	Score
Conciseness	The body is lean and high-signal — guardrails, a five-step workflow, a compact terminology table, and a capability checklist — with no padding or explanations of concepts Claude already knows; every section earns its place, matching the score-5 anchor.	5 / 5
Actionability	Provides concrete guidance (specific high-traffic files to check, named external sources like github.com/features/copilot, and concrete verification checks for banned words/em-dashes/MetaDescription length) but the Verify step lacks a specific command or tool, leaving minor gaps versus fully copy-paste-ready instructions.	4 / 5
Workflow Clarity	A clear five-step sequence (Gather context, Audit, Gap analysis, Edit, Verify) with an explicit Verify checkpoint and a pre-edit confirmation guardrail, but it lacks an explicit fix-and-re-verify feedback loop, fitting the score-4 anchor rather than the error-recovery-loop score-5 anchor.	4 / 5
Progressive Disclosure	Well under 50 lines and tightly organized into clear sections with clearly signaled, one-level-deep references to the repo-level docs-writing instructions, matching the simple-skill exception that allows a 5 with well-organized sections.	5 / 5
	Total	18 / 20 Passed

Description

88%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, third-person description that clearly states both capability and trigger conditions with concrete actions. The only weaknesses are slightly technical trigger phrasing and minor overlap risk with the general docs-writing skill.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Audit and update docs/copilot/ documentation to accurately reflect current VS Code AI capabilities' and 'Produces a gap analysis plus targeted edits across affected files' — covering audit, gap analysis, and targeted edits comprehensively, matching the score-5 anchor.	5 / 5
Completeness	Explicitly answers both what ('Audit and update docs/copilot/ documentation... Produces a gap analysis plus targeted edits') and when via a concrete 'Use when:' clause with multiple trigger phrases, matching the score-5 anchor exactly.	5 / 5
Trigger Term Quality	Includes several natural triggers ('competitive analysis reveals gaps', 'product launches new features', 'docs use outdated framing') but terms like 'keyword coverage needs strengthening' and 'discoverability by users and AI agents' lean technical and miss common synonyms, landing above the score-3 anchor but short of fully comprehensive coverage.	4 / 5
Distinctiveness Conflict Risk	Has a clear niche (VS Code Copilot docs product-alignment) with distinct triggers, but the sibling docs-writing instruction set referenced in the body creates minor overlap risk with a closely related writing skill, placing it at the score-4 anchor rather than minimal-conflict 5.	4 / 5
	Total	18 / 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: 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.