beads-docs

Project conventions for writing, editing, restructuring, or reviewing the beads user documentation — the Mintlify site under docs/. Use this whenever you touch anything in docs/ (pages, concept docs, reference, integration guides, recovery runbooks, diagrams, docs.json navigation) or write/edit prose about beads, even when the request is just "fix the docs", "write a docs page", "the docs are wrong/confusing", "rename X across the docs", or an edit to a file under docs/. It defines the canonical concept model (bead → dependencies → ready work; formula → proto → molecule/wisp; gates; Dolt sync and federation), required terminology, the prose/emphasis/diagram conventions, the rule that generated docs are edited at their source, and the gates to run before docs work is done.

Quality

94%

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

88%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 dense, high-signal conventions skill: executable commands and exact paths everywhere, explicit verification gates with feedback loops, and a sensible split of the three procedure-heavy topics (terminology renames, simplification pass, verification) into one-level-deep reference files. The main residual cost is length in the body itself — the canonical concept table and cross-project vocabulary section push SKILL.md past overview size.

Suggestions

Move the §1 canonical-model table and the Gas City cross-project vocabulary block into a reference file (e.g. references/concept-model.md), keeping in SKILL.md only the pipeline summary and a pointer — this would cut ~40 lines from the always-loaded body.

In §9, link each gate to the failure it catches (e.g. what a docsync or drift failure looks like and how to fix it), shortening the inline explanations while keeping the checklist copy-pasteable.

Trim §3/§5 rationale sentences that restate the rule they follow ('A page that tries to teach *and* specify does neither' style justifications) to pure imperatives where the rule is already unambiguous.

Dimension	Reasoning	Score
Conciseness	Efficient and imperative throughout ('Never open on vocabulary', 'a page that tries to teach and specify does neither — split it and cross-link') with no padding and no explanation of concepts Claude already knows. Falls short of lean-every-token-earns-its-place because the 10-row concept table in §1 and the long Gas City cross-project vocabulary paragraph are dense reference material that could live in a bundle file.	4 / 5
Actionability	Fully executable, copy-paste-ready commands throughout: 'go test ./test/docsync', './scripts/generate-cli-docs.sh --check', './scripts/check-doc-freshness.sh', 'make diagrams-excalidraw', 'bd mol pour', 'make docs-dev at localhost:3000', plus exact paths (docs/cli-docs.pin, docs/diagrams/excalidraw/, refs/dolt/data). As an instruction-only skill the guidance is concrete and specific; nothing is pseudocode or hand-wavy.	5 / 5
Workflow Clarity	Multi-step processes are clearly sequenced with explicit validation: §9 is a verification checklist of gates ('the short list: go test ./test/docsync... a live preview with make docs-dev'), §8 gives the edit-source-then-regenerate workflow whose drift gates 'fail or auto-fix any hand edit' (a feedback loop), and the move/remove-page procedure includes the error-recovery branch ('check whether bd prints the old path... fix the Go source and regenerate'). Not 4 because validation checkpoints and error-recovery branches are explicit, not merely present.	5 / 5
Progressive Disclosure	Three one-level-deep references, all verified real files, each clearly signaled with its purpose ('the full prose-vs-literal rename discipline', 'the per-page loop and the two guardrails... loss-check and fact-check', 'Run the gates in'). Not 5: at ~205 lines the body is more than an overview — §1's 10-row canonical-model table and the Gas City vocabulary block are bulk content inlined in SKILL.md that could be split out.	4 / 5
	Total	18 / 20 Passed

Description

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

An exemplary description: concrete capabilities, an explicit 'use this whenever' trigger clause with quoted natural user phrasings, and a clearly delineated niche. Density is functional rather than padded — every clause is either a capability or a trigger.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions ('writing, editing, restructuring, or reviewing') with a comprehensively enumerated scope ('pages, concept docs, reference, integration guides, recovery runbooks, diagrams, docs.json navigation') plus the specific content it defines (concept model, terminology, prose/emphasis/diagram conventions, generated-docs rule, gates). Matches the comprehensive-coverage anchor; it is not the level below because no action area is missing.	5 / 5
Completeness	Explicitly answers both what ('defines the canonical concept model... required terminology, the prose/emphasis/diagram conventions... and the gates to run') and when ('Use this whenever you touch anything in docs/... even when the request is just...') with concrete trigger phrases, matching the top anchor exactly. Not 4 because the 'when' is fully explicit, not merely improvable.	5 / 5
Trigger Term Quality	Comprehensive natural-phrasing coverage with synonyms: "'fix the docs', 'write a docs page', 'the docs are wrong/confusing', 'rename X across the docs'", plus paths and file names (docs/, docs.json, Mintlify, Dolt). These are exactly the words a user would say; nothing common is missing.	5 / 5
Distinctiveness Conflict Risk	Clear niche (beads user-documentation conventions, the Mintlify site under docs/) with distinct project-specific triggers; minimal overlap risk with other skills. The named-CLI and path vocabulary makes wrong-skill triggering very unlikely.	5 / 5
	Total	20 / 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
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: gastownhall/beads
Path: .claude/skills/beads-docs/SKILL.md
Commit: 671715b

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