CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

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

The body is a well-structured, highly actionable two-phase workflow with explicit approval checkpoints and appropriate offloading of style detail to external instruction files. Its main weakness is token redundancy: the plan-first/no-edit rule is repeated several times, which could be tightened without losing clarity.

Suggestions

State the no-edits-before-approval rule once (e.g., in Guardrails or the intro) and remove the repeated restatements in 'When to Use', Phase 1 step 7, and the Phase 2 preamble.

Merge the duplicated 'even if the change seems small' caveat and the duplicated 'no documentation update needed' note so each appears in only one place.

Add a brief example of what the Phase 1 plan summary should look like to close the actionability gap and make the presentation step copy-paste ready.

DimensionReasoningScore

Conciseness

Mostly efficient, project-specific policy (e.g., policies.md regeneration, sitemap rules, public-availability criteria), but the no-edits-before-approval rule is stated at least four times and the "even if the change is small" caveat and no-update-needed note each appear twice.

3 / 5

Actionability

Highly concrete guidance for an instruction-only skill — exact files (docs/toc.json, build/sitemap.xml, enterprise/policies-template.md), copy-paste branch-dialog choices, named tooling (gh CLI) and named sibling skills to avoid — with minor gaps such as no example of the Phase 1 plan summary.

4 / 5

Workflow Clarity

Two clearly sequenced phases with explicit stop-and-wait checkpoints (plan approval, branch confirmation), error recovery for uncommitted-change conflicts, and a final verification step against the approved persona and reader intent.

5 / 5

Progressive Disclosure

No bundle files exist and none are needed; the body is cleanly sectioned and heavy detail (style guide, content framing) is offloaded via clearly labeled one-level-deep links to the project's docs-writing instructions.

5 / 5

Total

17

/

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 that explicitly covers what the skill does and when to use it, with natural quoted trigger phrases and a distinct VS Code-documentation niche. Minor improvements are possible: add one or two more trigger variations and a brief exclusion of sibling doc skills to reduce overlap risk.

DimensionReasoningScore

Specificity

Names the domain and several concrete actions ("Plan and write VS Code documentation", "Proposes a documentation plan and asks clarifying questions first"), with minor coverage gaps (e.g., sitemap/navigation updates and auditing are not mentioned).

4 / 5

Completeness

Explicitly answers both what ("Plan and write VS Code documentation for a new or updated feature") and when ("ALWAYS use this skill when the user asks to 'document', 'add docs for', ...") with concrete trigger phrases.

5 / 5

Trigger Term Quality

Quotes four natural user phrasings ("document", "add docs for", "write docs for", "update the docs for") plus the issue/PR-link trigger, but a few natural variations (e.g., "document this functionality", "documentation for") are missing.

4 / 5

Distinctiveness Conflict Risk

Clear niche (VS Code feature docs, plan-first workflow) with distinct triggers, but the description itself does not carve out the sibling doc skills (release notes, redirects, API docs) that the body excludes, leaving minor overlap risk.

4 / 5

Total

17

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

relative_links

Relative link issues: 4 suspicious

Warning

Total

14

/

16

Passed

Repository

microsoft/vscode-docs

Path

.github/skills/doc-writer/SKILL.md

Reviewed

Table of Contents

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.