docs

Decide which family a doc belongs to before drafting — SDK/developer, user/product, or working-group (WG) — since family sets the audience, home, and tone. Use when creating, moving, or restructuring docs, when unsure which directory a doc belongs in, or when a request says "document this" / "write docs for X" without naming the kind. Routes to the specialized skill for each family.

Quality

86%

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

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

A well-structured routing skill body with a clear decision tree, concrete placement rules, and exemplary progressive disclosure that pushes detail to AGENTS.md and sibling skills. Weakest on conciseness, where some doctrinal prose could be tightened.

Suggestions

Tighten the opening paragraph: drop the editorial framing ('most common and most expensive docs mistake, because it is invisible...') and keep only the actionable claim that family sets audience, home, and tone.

In the 'Implementation-binding specs' boundary bullet, name the concrete destination more precisely (e.g. 'packages/<pkg>/docs/ or the crate's docs/') instead of 'the package or crate's own docs/' so the rule is copy-pasteable.

Consider adding a one-line 'if none of the three fit, default to ...' fallback to the routing decision tree so the procedure has a terminal default rather than ending implicitly.

Dimension	Reasoning	Score
Conciseness	Mostly lean and repo-specific, but carries minor editorial padding such as 'the most common and most expensive docs mistake, because it is invisible until someone reads it for the wrong reason' that could be trimmed without loss.	4 / 5
Actionability	Provides a concrete ordered decision tree and explicit placement paths ('packages/<pkg>/docs/', 'docs/reference/**') plus concrete boundary rules, with only minor gaps where some edges ('implementation-binding specs live with the code') stay slightly abstract.	4 / 5
Workflow Clarity	The routing flow is a clear ordered 1-2-3 sequence with a 'hand off and stop' checkpoint; it is not a destructive or batch operation, so the missing explicit validation/feedback loop is a minor rather than disqualifying gap.	4 / 5
Progressive Disclosure	A textbook overview/router: it defers operational detail to docs/AGENTS.md ('this skill does not repeat it') and to sibling skills via clearly signaled one-level-deep markdown links, keeping the body navigable.	5 / 5
	Total	17 / 20 Passed

Description

95%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-scoped routing description that clearly states its job, gives explicit 'Use when' triggers with natural phrasing, and distinguishes itself by routing rather than drafting. Minor specificity gap is inherent to being a meta-router rather than a doer.

Dimension	Reasoning	Score
Specificity	Names the docs domain and several concrete actions — 'Decide which family a doc belongs to', 'Routes to the specialized skill for each family', plus 'creating, moving, or restructuring docs' — with only minor coverage gaps typical of a router skill.	4 / 5
Completeness	Explicitly answers both what (decide family, route to the specialized skill) and when, with a concrete 'Use when' clause naming specific triggering situations.	5 / 5
Trigger Term Quality	Captures the natural phrases users actually say — 'document this', 'write docs for X', 'which directory a doc belongs in', 'creating, moving, or restructuring docs' — giving comprehensive trigger coverage.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear router niche with distinct triggers (e.g. 'without naming the kind', 'which directory a doc belongs in') and explicitly hands off to sibling skills, minimizing conflict risk.	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: 19 suspicious	Warning

	Total	15 / 16 Passed

Repository: gridaco/grida
Path: .agents/skills/docs/SKILL.md
Commit: 8ef5e53

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