CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

96%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

92%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 high-quality conventions skill: concrete commands and paths throughout, explicit verification gates with feedback loops, and clean progressive disclosure into three well-signaled reference files. Its only weakness is minor redundancy between the concept-model table (§1) and the terminology table (§2), plus a longish cross-project vocabulary paragraph, which keep it just short of maximal token efficiency.

Suggestions

Merge or cross-reference the overlapping bead/proto/molecule/gate rows between the §1 concept table and the §2 terminology table so each concept is defined once.

Trim the Gas City cross-project paragraph to the operative rule (never import Gas City's definitions; state which project's sense is meant) and move the per-project contrasts into a reference file.

Cut 'the claimable frontier' and similar appositive restatements in table cells where the 'Key idea' column already states the definition.

DimensionReasoningScore

Conciseness

The body is dense and almost entirely project-specific (storage paths, commands, generator pipeline, pin policy) with no explanation of concepts Claude already knows. However, §1's concept table and §2's terminology table restate overlapping bead/proto/molecule/gate definitions, and the Gas City cross-project paragraph runs long — minor over-explanation that could be trimmed, matching anchor 4 rather than the 'every token earns its place' of anchor 5.

4 / 5

Actionability

Guidance is fully executable: copy-paste gates ('bazel test //test/docsync:docsync_test --config=ci', './scripts/generate-cli-docs.sh --check', './scripts/check-doc-freshness.sh', 'make docs-dev'), concrete paths ('.beads/embeddeddolt/', 'docs/cli-docs.pin', 'docs/diagrams/excalidraw/'), and Use/Not-this terminology tables. As an instruction-only skill its specific commands and rules cover the common editing cases, matching the anchor-5 'copy-paste ready… specific examples cover the common cases'.

5 / 5

Workflow Clarity

The skill provides explicit validation steps with commands (§9's gate list), feedback loops for error recovery (§8: drift gates 'fail or auto-fix any hand edit'; regenerate from the pin), and checklists for complex processes (§9's move/remove-a-page procedure, §10's review→commit sequencing with commit grouping). All three elements of the anchor-5 description are present; verification is explicit, so no destructive/batch cap applies.

5 / 5

Progressive Disclosure

The body is a well-organized overview that pushes depth to three real, one-level-deep bundle files, each clearly signaled with its purpose: terminology.md ('The full prose-vs-literal rename discipline is in…'), simplification.md ('the per-page loop and the two guardrails'), and verification.md ('Run the gates in…' with only a short list kept inline). This matches the anchor-5 clear-overview pattern with easy navigation and no nested references.

5 / 5

Total

19

/

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: it states the domain and actions concretely, enumerates the skill's contents, and gives an explicit 'Use this whenever…' clause with verbatim user trigger phrases. It is dense rather than padded, and every clause either scopes the skill or adds a trigger.

DimensionReasoningScore

Specificity

The description names concrete actions ('writing, editing, restructuring, or reviewing the beads user documentation') and comprehensively enumerates what 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… and the gates to run'. This matches the anchor for multiple specific concrete actions with comprehensive coverage, with no generic filler.

5 / 5

Completeness

Both questions are answered explicitly: 'what' via the enumerated conventions and content model, and 'when' via 'Use this whenever you touch anything in docs/ … even when the request is just…' followed by concrete trigger phrases. This is the anchor-5 pattern (explicit what AND when with concrete trigger phrases), not merely the anchor-4 'when could be more explicit'.

5 / 5

Trigger Term Quality

It quotes natural user phrasings verbatim ('fix the docs', 'write a docs page', 'the docs are wrong/confusing', 'rename X across the docs') and covers the artifact surface users would mention (pages, concept docs, reference, integration guides, recovery runbooks, diagrams, docs.json navigation, 'a file under docs/'). Coverage including synonyms and quoted triggers exceeds the anchor-5 example.

5 / 5

Distinctiveness Conflict Risk

The niche is unambiguous — 'the beads user documentation — the Mintlify site under docs/' — and triggers are path- and project-scoped, so overlap with generic documentation skills is minimal. It is written in third person throughout, so no voice penalty applies.

5 / 5

Total

20

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

gastownhall/beads

Path

.claude/skills/beads-docs/SKILL.md

Reviewed

Table of Contents

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.