docs-conventions

Use when writing or reviewing Flet documentation, including Python docstrings (Google style, reST roles, admonitions), Markdown docs (cross-references, images, code examples), and sidebar navigation.

Quality

82%

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

72%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 actionable, well-structured conventions reference with strong code examples, but it is a monolithic single-file guide lacking progressive disclosure to separate reference files and explicit validation checkpoints in its few workflows.

Suggestions

Move the detailed cross-reference rules and admonition/reference tables into a separate REFERENCES.md and link to it from a concise overview, enabling one-level-deep progressive disclosure.

Add an explicit validation/verification step to the sidebar workflow (e.g. 'run yarn crocodocs:generate and confirm the build succeeds before committing').

Trim contextual asides like 'Docusaurus renders them as the website' to tighten token efficiency.

Dimension	Reasoning	Score
Conciseness	Mostly lean reference material with terse rules and code blocks, but a few explanatory sentences ('Docusaurus renders them as the website', rationale prose) could be trimmed; not quite every-token-earns-its-place.	4 / 5
Actionability	Copy-paste-ready examples for reST roles, xrefs, markdown links, admonitions, front matter, Image/CodeExample JSX, and sidebar YAML, plus concrete rules covering the common cases.	5 / 5
Workflow Clarity	Sequences exist where relevant (sidebar: edit YAML then 'cd website && yarn crocodocs:generate'; xref verification via build), but no explicit validation checkpoints or feedback loops, and most content is reference rather than a sequenced process.	3 / 5
Progressive Disclosure	Well-organized into clear section headers, but ~200 lines of reference content live in a single inline file with no bundle files or one-level-deep references that could split out detailed material.	3 / 5
	Total	15 / 20 Passed

Description

92%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, niche-scoped description with an explicit 'Use when' trigger and a concrete enumeration of covered doc areas. Slightly richer trigger synonyms would push trigger_term_quality to the top anchor.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions across the documentation domain — 'Python docstrings (Google style, reST roles, admonitions)', 'Markdown docs (cross-references, images, code examples)', and 'sidebar navigation' — giving comprehensive coverage.	5 / 5
Completeness	Explicit 'Use when writing or reviewing Flet documentation' clause answers 'when' with concrete triggers, while the enumerated doc areas answer 'what' clearly; the 'when' is more specific than the 4-anchor allows.	5 / 5
Trigger Term Quality	Natural trigger phrases like 'writing or reviewing Flet documentation', 'Python docstrings', and 'sidebar navigation' are present, but common synonyms and file extensions (e.g. '.md', 'API docs') are missing.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche — Flet-specific documentation conventions — with distinct triggers, so overlap with other skills is minimal.	5 / 5
	Total	19 / 20 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: 4 suspicious	Warning

	Total	15 / 16 Passed

Repository: flet-dev/flet
Path: .agents/skills/docs-conventions/SKILL.md
Commit: 8f74fe9

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