docs-build-and-verify

Use when asked to build, preview, or verify the Flet documentation website, including checking for broken links, broken images, and unresolved reST cross-references.

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

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

An exemplary lean, fully executable skill: every step is a runnable command, sequencing is clear, and it captures hard-won environment gotchas (Node 24 for CI parity, silent broken-anchor warnings). The only improvements are structural — move the inline Python checker to a script file and add an explicit fix-and-retry loop for reported failures.

Suggestions

Add a short feedback loop after the image and cross-reference checks, e.g. 'fix the src or reST role, then re-run the check until it reports no findings'.

Move the inline Python image checker into `scripts/check_broken_images.py` and reference it with a one-line invocation to keep SKILL.md as a lean overview.

Dimension	Reasoning	Score
Conciseness	Every section is a copy-paste command plus only genuinely non-obvious rationale (e.g. the `onBrokenAnchors` default-to-warn gotcha). No concepts Claude already knows are explained; every token earns its place.	5 / 5
Actionability	Fully executable throughout: `nvm use 24`, `yarn build`/`yarn start`/`yarn crocodocs:generate`, a complete 24-line Python image checker, and a specific `grep -r` for reST roles. No pseudocode or vague direction.	5 / 5
Workflow Clarity	Sequencing is present ('Run this after `yarn build`') and the broken-links section adds a real validation caveat ('grep the build output for `Broken anchor` rather than trusting the exit code'). Not 5 because there is no explicit fix-and-re-run feedback loop after the image or cross-reference checks report failures.	4 / 5
Progressive Disclosure	Well-organized sections with no dead references and no nested-reference problem. Not 5 because the 26-line inline Python image checker is content that arguably belongs in a `scripts/` bundle file rather than in SKILL.md.	4 / 5
	Total	18 / 20 Passed

Description

78%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, well-targeted description: it names a specific project (Flet docs), lists concrete verification actions, and includes an explicit 'Use when' trigger. The only weaknesses are minor — missing the API-data regeneration capability and a single formal phrasing where synonyms would broaden natural triggering.

Suggestions

Add natural synonyms for the trigger surface, e.g. 'when the user mentions the Flet docs, documentation site, or docs build/CI failures'.

State the what as its own clause, e.g. 'Builds the docs site, regenerates API data and sidebars, and checks for broken links, broken images, and unresolved reST cross-references.'

Mention the `crocodocs:generate` API-data regeneration capability so the description covers all body workflows.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('build, preview, or verify the Flet documentation website', 'checking for broken links, broken images, and unresolved reST cross-references') anchored to a named target. Not 5 because the body's fourth capability — regenerating API data via `yarn crocodocs:generate` — is not mentioned.	4 / 5
Completeness	Has an explicit 'Use when asked to...' trigger plus an embedded what (checking broken links, images, and cross-references). Matches anchor 4 rather than 5 because the what is folded into the when-clause rather than stated as its own complete capability sentence, and only one trigger formulation is offered.	4 / 5
Trigger Term Quality	Good natural terms users would actually say: 'build', 'preview', 'verify', 'broken links', 'broken images'. Not 5 because only the formal 'documentation website' phrasing appears — no synonyms or looser variations like 'docs' or 'Flet docs'.	4 / 5
Distinctiveness Conflict Risk	'Flet documentation website' carves a clear niche and 'reST cross-references' further disambiguates it from generic docs or web skills; minimal conflict risk with other skills.	5 / 5
	Total	17 / 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: flet-dev/flet
Path: .agents/skills/docs-build-and-verify/SKILL.md
Commit: 9748de3

Reviewed: 4 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.