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

78%

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

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/docs-product-alignment/SKILL.md

Quality

Content

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

The skill body is concise and well-structured with a clear workflow and terminology guidance. It is held back by incomplete actionable detail on the verification step and the absence of a fix-and-retry feedback loop for batch edits.

Suggestions

Add an executable check for the Verify step, e.g. a grep/ripgrep command for banned words and em-dashes, and state the MetaDescription length limit explicitly.

Turn the Verify step into a feedback loop: if violations are found, fix them and re-run the check until clean before finishing.

Specify how page traffic is sourced or ranked in the Gap analysis step so prioritization is actionable rather than assumed.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-organized — guardrails, a numbered workflow, a terminology table, and a capability list — with no padding explaining concepts Claude already knows and every section earning its place.	3 / 3
Actionability	It names concrete targets (specific file paths like 'docs/copilot/overview.md') and concrete checks (banned words, em-dashes, MetaDescription length) but provides no executable command or script to run those checks and no numeric threshold for MetaDescription length, leaving the guidance incomplete.	2 / 3
Workflow Clarity	The five-step sequence is clear and includes a Verify step, but for batch edits across files the verification lacks a fix-and-retry feedback loop ('if violations found, fix and re-verify'), which the scoring notes say caps workflow clarity at 2.	2 / 3
Progressive Disclosure	Content is a single well-organized SKILL.md with clearly signaled sections and a one-level style-guide reference; no nested multi-level references, and no bundle files exist to evaluate beyond the body.	3 / 3
	Total	10 / 12 Passed

Description

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

The description is specific, complete, and distinctive, clearly stating both what the skill does and when to use it. The main weakness is that the trigger terms are framed as situational conditions rather than natural language a user would actually say.

Suggestions

Rewrite the 'Use when' triggers as natural user phrases (e.g., 'when the user says the Copilot docs are outdated, inaccurate, or missing new features') so they match real user utterances.

Add common keyword variants to the trigger clause such as 'Copilot docs', 'VS Code AI docs', or 'documentation is wrong'.

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' — matching the anchor for multiple specific concrete actions.	3 / 3
Completeness	Explicitly answers both what ('Audit and update docs/copilot/ documentation to accurately reflect current VS Code AI capabilities') and when ('Use when: competitive analysis reveals gaps, product launches new features, docs use outdated framing...').	3 / 3
Trigger Term Quality	The 'Use when' clause lists situational conditions ('competitive analysis reveals gaps', 'product launches new features') but these are not natural user utterances and omit common variations like 'docs are wrong' or 'update the Copilot docs'.	2 / 3
Distinctiveness Conflict Risk	Scoped specifically to VS Code Copilot docs alignment, a clear niche with distinct triggers unlikely to fire for unrelated skills.	3 / 3
	Total	11 / 12 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: 9 suspicious	Warning

	Total	15 / 16 Passed

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