--- name: Docs slug: docs category: Writing description: "Docs accesses and updates the user's document vaults, letting the agent read, find, create, update, or store notes, documents, plans, and HTML artifacts. Use it when the user asks to manage documents or when a Docs @-mention appears." github: "https://github.com/get-bb/bb/tree/main/plugins/docs/skills/docs" language: TypeScript stars: 2274 forks: 253 install: "npx degit https://github.com/get-bb/bb/tree/main/plugins/docs/skills/docs ~/.claude/skills/docs" installs_to: ~/.claude/skills/docs source_path: plugins/docs/skills/docs/SKILL.md collection_size: 14 category_size: 1012 collection_url: "https://dirskills.com/collections/get-bb/bb" added: 2026-08-18T06:58:20.983Z last_synced: 2026-08-18T06:58:20.983Z canonical_url: "https://dirskills.com/skills/docs" --- # Docs Docs accesses and updates the user's document vaults, letting the agent read, find, create, update, or store notes, documents, plans, and HTML artifacts. Use it when the user asks to manage documents or when a Docs @-mention appears. **Install:** ```bash npx degit https://github.com/get-bb/bb/tree/main/plugins/docs/skills/docs ~/.claude/skills/docs ``` ## README # Docs Docs is the user's filesystem-first document library. Documents can live on the primary machine or another connected host, but the `bb docs` command handles that routing through named vaults. ## Access documents Start with the smallest useful lookup: ```sh bb docs vaults --json bb docs list --vault --json bb docs read --vault ``` Use the path and vault exactly as returned. Paths are relative to the vault; do not guess an absolute host path or inspect the vault outside `bb docs`. ## Docs @-mentions A Docs mention resolves at send time and appears in agent context as a `Docs document (/)` block. Treat that block as user-provided source material from their document library: - Read and use its current contents even if the prompt only says “this” or “the attached doc.” - Preserve its meaning and distinguish its claims from your own inference. - Do not rewrite the mentioned document unless the user asks you to change it. - When your answer refers the user back to it, emit a Docs directive rather than an opaque filesystem path. ## Create and update documents Docs is a good destination for durable plans, specifications, write-ups, and HTML artifacts the user should be able to reopen. ```sh bb docs pull plans/release-plan.md --vault personal --into ./docs-work # Edit ./docs-work/plans/release-plan.md with normal file tools. bb docs status ./docs-work --diff bb docs push ./docs-work ``` Pull a folder subtree with `--folder`, or the whole selected vault with `--all`: ```sh bb docs pull plans --folder --vault personal --into ./docs-work bb docs pull --all --vault personal --into ./docs-work ``` Always edit the pulled files with ordinary workspace tools, then run `status` before `push`. The manifest in `.bb-docs-state.json` records stable vault paths and remote SHA-256 versions; do not edit it. Pull and push fail closed when both the local and vault copies changed. Resolve the content manually, then pull or push again. `push --dry-run --diff` previews without writing. Local file and empty-directory deletions are ignored by default. Only use `push --delete` when the user explicitly asked to delete the corresponding vault paths. A pulled folder root is intentionally retained; pull its parent or the whole vault to remove that folder. Binary assets round-trip with their original bytes. If state is malformed, preserve the directory for recovery and pull into a new clean `--into` directory. The direct `write`, `mkdir`, `move`, and `remove` commands are deprecated. Do not use them for agent edits; they remain temporarily available only for backward compatibility. Use Markdown for documents and plans. Use a self-contained `.html` file for a visual artifact or interactive report; relative assets can live beside it. Only write into Docs when the user asks to create, save, store, or update something there. ## Link documents in responses Emit this leaf directive on its own line: ```md ::docs{vault="personal" path="plans/release-plan.md" title="Release plan"} ``` `vault` and `path` are required. Include a short human-readable `title` when known. The rendered card opens an editable, autosaving document in the thread side panel; its secondary action opens the full Docs editor. Use the directive for both Markdown documents and full HTML artifacts.