documentation

Add documentation for contributors and developers.

Quality

40%

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

43%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 content efficiently delivers useful project-specific conventions but is mostly vague direction rather than executable guidance, with no sequenced workflow or validation. It is short and unstructured but free of unnecessary padding.

Suggestions

Provide concrete, executable steps (e.g., exact commands to build/scan the 11ty site, the path pattern for versioned doc folders, how to run validation).

Add a short sequenced workflow for a documentation change (locate affected docs -> update DESIGN.md/website -> scan site -> verify build) with an explicit verification checkpoint.

Introduce section headers (e.g., '## Design docs', '## Website', '## Breaking changes') to give the otherwise flat prose clear structure.

Dimension	Reasoning	Score
Conciseness	The body is lean and conveys project-specific facts (DESIGN.md, 11ty, fast-element, versioned folders) that Claude would not already know, with only minor redundancy.	4 / 5
Actionability	Guidance is high-level ('ensure the website has been scanned', 'update the documentation in the 3.x folder', 'migration document has been updated') with no concrete commands or specific steps, matching anchor 2.	2 / 5
Workflow Clarity	The content is a scattered set of rules with no clear sequence and no validation checkpoints, fitting anchor 2 rather than the incoherent anchor 1 or the checkpointed anchors above.	2 / 5
Progressive Disclosure	The skill is short and needs no external references, but it lacks section headers and structure, so it falls short of the well-organized anchor 5 and sits at anchor 3.	3 / 5
	Total	11 / 20 Passed

Description

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

The description states a clear but generic purpose and identifies an audience, yet lacks any 'Use when...' trigger guidance or concrete actions. It is distinguishable but only weakly triggered.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers (e.g., 'when adding or updating DESIGN.md, website docs, or migration guides').

Replace the generic verb 'Add' with 2-3 specific concrete actions (e.g., 'Update DESIGN.md, edit website markdown, maintain migration guides').

Include natural synonyms users would say (documentation, docs, README, API docs) to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	The phrase 'Add documentation' names the domain but the action is minimal and generic, matching anchor 2 rather than the vague anchor 1 or the multi-action anchor 3.	2 / 5
Completeness	A clear 'what' ('Add documentation for contributors and developers') is present but there is no 'when' trigger guidance, which per the guidelines caps completeness at 3.	3 / 5
Trigger Term Quality	Only generic keywords ('documentation', 'contributors', 'developers') appear with no natural trigger phrases, synonyms, or file extensions a user would say, fitting anchor 2.	2 / 5
Distinctiveness Conflict Risk	Scoping to 'contributors and developers' adds some specificity, but 'documentation' is broad and could overlap with other doc-related skills, matching anchor 3.	3 / 5
	Total	10 / 20 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: a909e87

Reviewed: about 18 hours 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.