Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →gastownhall/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
Passed 21 of 22 test cases with the skill, and 6 of 22 without it.
and 26 more in the full report
15 fixed6 passed either way1 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 15 test cases the skill fixed. Same model, same prompt, with and without the skill.
I am shortening prose across several workflow pages to remove fluff. What two explicit verification checks must I perform before committing shortened documentation?
| Checked | Without skill | With skill |
|---|---|---|
| Includes a loss-check to ensure no facts unique to that page are lost. | Missed | Passed |
| Includes a fact-check to ensure shortened prose does not drift from current code behavior. | Missed | Passed |
The instructions your model reads when the skill loads.
This is the house style for docs/ — the beads user documentation, published
as a Mintlify site. The goal is docs that motivate before they jargon, say the
same thing the same way everywhere, show concepts as pictures and snippets
instead of walls of prose, and never drift from the code. Apply it to any page
you create, edit, or review.
The audience of docs/ is a user of beads — a human or agent installing
bd, tracking work, and syncing it. Contributor-facing material lives in
engdocs/ and AGENTS.md and follows different rules (it may describe the
implementation literally). When this skill says "the docs," it means docs/.
Beads is a dependency-aware issue graph with a workflow layer on top. Teach it
consistently and link to the canonical concept page —
docs/core-concepts/index.md — rather than re-explaining it.
| Concept | Role | Key idea |
|---|---|---|
| bead (issue) | the unit of work | one tracked item with a hash ID (bd-a1b2), type, status, priority; "bead" and "issue" name the same thing |
| dependency | ordering | blocks edges hide a bead from agents until its blockers close; parent-child, related, discovered-from organize without blocking |
| ready work | what bd ready computes | open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier |
| formula | workflow source | a TOML/JSON file defining a DAG of steps; bd cook compiles it into a proto |
| proto | workflow template | a template epic (label template) with {{variables}}; not live work |
| molecule | instantiated workflow | real beads poured from a proto (bd mol pour); persistent |
| wisp | ephemeral molecule | same instantiation, transient lifecycle (bd mol wisp); purged by bd purge |
| gate | async wait | blocks a workflow step until closed — by a human, a timer, a GitHub run/PR, or a cross-rig bead |
| sync | cross-machine movement | Dolt push/pull over refs/dolt/data on the git remote; .beads/issues.jsonl is a passive export, never the database |
| federation | cross-repo sync | peer-to-peer sharing of beads across repos/organizations |
The pipeline worth internalizing: formula → (cook) → proto → (pour) →
molecule or → (wisp) → wisp. Gates pause molecule steps; bd ready
surfaces the claimable steps; sync moves the whole graph between machines.
Storage facts that pages keep getting wrong: embedded mode (the default
bd init) stores data at .beads/embeddeddolt/; server mode
(bd init --server) uses .beads/dolt/. Never present .beads/dolt/ as the
general data path.
test cases passed, vs 6 / 22 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.