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

89%

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 instruction-only style guide: dense, command-rich, and properly split across an overview plus three leaf reference files. Its main weakness is the absence of a single worked example page demonstrating the doctrine end-to-end, and the fully ordered verification sequence being delegated to a reference rather than carried inline.

Suggestions

Add one short worked example (a before/after page snippet) in §3 or §5 that applies the motivate-before-mechanize and terminology rules end-to-end, lifting actionability toward 5.

Inline the ordered verification gate sequence with explicit pass/fail branching (or a numbered checklist mirroring references/verification.md) so the workflow is self-contained without following the link.

Trim the most discursive doctrine prose — the §5 Convert/Delete narration and the beads↔Gas City paragraph could be shortened to a table or a few bullets to tighten conciseness.

Dimension	Reasoning	Score
Conciseness	Mostly efficient: tables for the concept model and terminology, bullets for doctrine, and project-specific concepts (bead/proto/molecule) that Claude would not already know. Minor discursive asides (the Convert/Delete lists in §5, the beads↔Gas City vocabulary paragraph) could be trimmed, keeping it just below the lean anchor-5.	4 / 5
Actionability	Highly concrete for an instruction-only skill — exact commands (`bd mol pour`, `./scripts/generate-cli-docs.sh --check`, `go test ./test/docsync`), exact paths (`.beads/embeddeddolt/`, `docs/core-concepts/index.md`), and a use/not-this terminology table. Held at 4 rather than 5 because there is no single end-to-end worked example showing the doctrine applied to a real page.	4 / 5
Workflow Clarity	Clear multi-step workflows with explicit validation gates (§9 short-list), feedback loops (drift gates that fail/auto-fix in §8, loss-check/fact-check guardrails in §5), and a checklist for the risky move/remove-page operation. Not 5 because the fully ordered, branched gate sequence is delegated to references/verification.md rather than spelled out inline with explicit error-recovery branching.	4 / 5
Progressive Disclosure	Overview doctrine lives inline while the heavier procedures are split into three real, one-level-deep references (terminology.md, simplification.md, verification.md — all present on disk), each clearly signaled with a markdown link and a 'when to read this' cue. Appropriate split, easy navigation, no nested references.	5 / 5
	Total	17 / 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.

A dense, trigger-rich description that concretely names the actions, surfaces, and paraphrased user requests that should activate it, while pinning a distinct niche (beads Mintlify docs). It is long but information-dense rather than padded, and the 'Use this whenever you touch …' clause follows the recommended impersonal trigger pattern rather than the penalized second-person 'You can use this' framing.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('writing, editing, restructuring, or reviewing') plus a comprehensive enumeration of doc surfaces (pages, concept docs, reference, integration guides, recovery runbooks, diagrams, docs.json navigation), matching the comprehensive-coverage anchor.	5 / 5
Completeness	Explicitly states what ('Project conventions … defines the canonical concept model, required terminology, the prose/emphasis/diagram conventions … and the gates') and when ('Use this whenever you touch anything in docs/ … or write/edit prose about beads'), with concrete trigger phrases — a clean anchor-5 match.	5 / 5
Trigger Term Quality	Quotes natural phrases users actually say — 'fix the docs', 'write a docs page', 'the docs are wrong/confusing', 'rename X across the docs' — alongside the docs/ path trigger, giving comprehensive natural-term coverage including paraphrases.	5 / 5
Distinctiveness Conflict Risk	Scoped to 'the beads user documentation — the Mintlify site under docs/', a clear niche with project-specific triggers unlikely to fire for any other skill; minimal conflict risk.	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: efaeaf2

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