# Beads Docs

Writes and reviews beads Mintlify docs pages and their navigation.

- Repository: https://github.com/gastownhall/beads (28396 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add gastownhall/beads --skill beads-docs -g -a claude-code -y`
Codex: `npx skills add gastownhall/beads --skill beads-docs -g -a codex -y`
Cursor: `npx skills add gastownhall/beads --skill beads-docs -g -a cursor -y`
Gemini CLI: `npx skills add gastownhall/beads --skill beads-docs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add gastownhall/beads`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Writing beads docs

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/`.

## 1. The canonical model

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.

The rest: https://github.com/gastownhall/beads/blob/HEAD/.claude/skills/beads-docs/SKILL.md