docs-wg

Doctrine for drafting and keeping working-group docs under `docs/wg/**` — RFC/RFD specs and findings/research/glossary. A WG doc is a language-agnostic, code-agnostic study of a domain: it argues *why* and defines *what*, never *how in our code*. Use when writing or editing anything under `docs/wg/`, an RFC/RFD, a spec, a design note, a glossary, or research findings — including "write up the design", "document the spec", or "capture what we learned". Not for plans/TODOs (untracked `*.plan.md`), user docs, or SDK API refs — use `docs` to route those.

Quality

81%

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

67%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 doctrine skill: dense with concrete rules, concrete placement/frontmatter details, and an explicit pre-save validation checklist, with external mechanics properly delegated one level deep. Its main costs are rhetorical repetition of the code-agnostic principle across sections and the absence of a single ordered workflow or a concrete doc/frontmatter example.

Suggestions

Consolidate the code-agnostic argument: state the rot rationale once and let the 'good/bad/NOT' sections and checklist reference it, cutting the restated justifications in each section.

Add a minimal example — a short sample WG-doc frontmatter block (title, description, tags from docs/tags.yml, format: md) to make the frontmatter rule copy-paste ready.

Present the drafting process as one ordered sequence (name genre → draft at spec altitude → place in cluster → update index.md → run the review checklist) instead of distributing it across sections.

Dimension	Reasoning	Score
Conciseness	The core doctrine (code-agnostic, domain-first) is re-argued in the intro ("A file path or a function name is stale within months"), in both genre sections, in "What a bad WG doc is", in "What is NOT a WG doc", and again in the review checklist, with rhetorical flourishes ("That is the bar", "You are writing the thing that outlives the code"). Mostly efficient rule-dense prose, but more than minor tightening is available via consolidation.	3 / 5
Actionability	Guidance is concrete for an instruction-only skill: exact cluster paths (`docs/wg/platform/`, `feat-*`), frontmatter field list (`title`, `description`, `tags: [internal, wg, <topic>…]`, `format: md`), explicit review search tokens (`crates/`, `editor/`, `packages/`), and a deletability test ("could you delete the section and replace it with a link"). It falls short of fully executable because no sample frontmatter or doc skeleton is provided.	4 / 5
Workflow Clarity	"Before you save — review" is an explicit validation checklist and placement/upkeep covers sequencing signals ("When you add a doc, update the hub"), matching the clear-sequence-with-most-checkpoints anchor. It is a 4 rather than 5 because the end-to-end process (name genre → draft → place → update index → review) is implied by section order rather than given as one ordered workflow.	4 / 5
Progressive Disclosure	No bundle files exist; operational mechanics are correctly deferred one level deep to `docs/AGENTS.md` ("read it once") and sibling skills (`grounding`, `naming`, `links`) are each linked with a stated purpose. The body is well-sectioned and navigable, but all doctrine lives inline in a single ~210-line file — placement/upkeep specifics and the research-subtree rules are candidates for externalized references.	4 / 5
	Total	15 / 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 description: third-person, concrete about both scope and triggers, with quoted natural trigger phrases and explicit exclusions that route edge cases to sibling skills. The only soft spot is that the capability verbs (drafting, keeping) are fewer than the enumerated artifact types.

Dimension	Reasoning	Score
Specificity	"Doctrine for drafting and keeping working-group docs under `docs/wg/**` — RFC/RFD specs and findings/research/glossary" names several concrete artifact types and the exact tree it governs, going beyond the 1–2-action anchor. It stays below a 5 because the action verbs themselves are limited to drafting/keeping rather than a comprehensive action list.	4 / 5
Completeness	It explicitly answers what ("Doctrine for drafting and keeping working-group docs… it argues why and defines what, never how in our code") and when ("Use when writing or editing anything under `docs/wg/`… including 'write up the design'…"), with concrete trigger phrases and explicit negative scope. Both halves are present, explicit, and specific.	5 / 5
Trigger Term Quality	Natural user phrases are quoted verbatim — "'write up the design'", "'document the spec'", "'capture what we learned'" — alongside object synonyms ("an RFC/RFD, a spec, a design note, a glossary, or research findings") and the concrete path `docs/wg/`. This matches the comprehensive-synonyms anchor.	5 / 5
Distinctiveness Conflict Risk	The niche is tightly bounded by the `docs/wg/*` path and doc genres, and it actively de-conflicts: "Not for plans/TODOs (untracked `.plan.md`), user docs, or SDK API refs — use `docs` to route those." Minimal conflict risk with neighboring skills.	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: 14 suspicious	Warning

	Total	15 / 16 Passed

Repository: gridaco/grida
Path: .agents/skills/docs-wg/SKILL.md
Commit: d086528

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.