documentation

Add documentation for contributors and developers.

Quality

50%

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

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/documentation/SKILL.md

Quality

Content

50%

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 compact, instruction-only overview that correctly identifies concrete documentation artifacts and audiences without padding. However, it lacks section headers, executable commands, and explicit validation checkpoints, leaving its guidance abstract.

Suggestions

Add section headers (e.g. '## Design docs', '## Website docs', '## Migration guides') to organize the content for quick scanning.

Replace abstract directives with concrete steps, such as the exact docs-folder path and the specific major-version folder to edit.

For breaking changes, add an explicit verify step, e.g. 'After updating the migration document, confirm the changed entry renders in the latest major-version docs build'.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining what documentation is and stays short, but directives like 'ensure that the website has been scanned on whichever latest major version is available' are loosely worded and could be tightened, fitting 'mostly efficient but includes some unnecessary explanation or could be tightened'.	2 / 3
Actionability	It names concrete artifacts (DESIGN.md, 11ty, 1.x/2.x/3.x folders, migration document, docs folder) giving some concrete guidance, but offers no executable commands, paths, or copy-paste-ready steps, leaving key details missing.	2 / 3
Workflow Clarity	A loose sequence is implied ('When making changes, ensure...' / 'If you are making a breaking change, ensure...'), but there are no explicit validation checkpoints or feedback loops, matching 'steps listed but validation gaps'.	2 / 3
Progressive Disclosure	No bundle files exist and the body is under 50 lines, but it is unstructured prose with no section headers to organize discovery, fitting 'some structure but could be better organized' rather than the well-organized sections needed for a 3.	2 / 3
	Total	8 / 12 Passed

Description

50%

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 in proper third person and identifies the documentation domain and audience, but it lists only one action and omits any explicit 'use when' trigger guidance. It is adequately specific yet generic enough to risk overlapping with other skills.

Suggestions

Expand the action list to concrete documentation tasks, e.g. 'Update DESIGN.md files, add code comments, write website docs, and refresh migration guides'.

Add an explicit trigger clause such as 'Use when the user asks to add or update documentation, DESIGN.md files, code comments, or migration guides'.

Include natural keyword variants like 'docs', 'documentation', and 'DESIGN.md' to improve trigger matching and distinctiveness.

Dimension	Reasoning	Score
Specificity	The phrase "Add documentation for contributors and developers" names a domain (documentation) and an audience plus a single action, but it is not a comprehensive list of concrete actions, matching the 'names domain and some actions, but not comprehensive' anchor.	2 / 3
Completeness	It states what to do ("Add documentation") but provides no "Use when..." or equivalent trigger for when Claude should invoke it; per the guidelines a missing explicit trigger caps completeness at 2.	2 / 3
Trigger Term Quality	"documentation" and "contributors and developers" are natural terms a user might say, but common variations like "docs", "DESIGN.md", "code comments", or "migration guide" are absent, fitting 'some relevant keywords but missing common variations'.	2 / 3
Distinctiveness Conflict Risk	The description is somewhat specific to documentation work but is generic enough that it could overlap with many code-adjacent skills, fitting 'somewhat specific but could still overlap with similar skills'.	2 / 3
	Total	8 / 12 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: microsoft/fast
Path: .github/skills/documentation/SKILL.md
Commit: 27a4304

Reviewed: 1 day 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.