Agent-Skills.md

Agent Skills: workbench-docs

Documentation workflows for Workbench CLI. Use when creating or updating specs, ADRs, runbooks, guides, or general docs, and when syncing backlinks or change notes.

UncategorizedID: bravellian/workbench/workbench-docs

Repository

bravellian/workbench
incursaLicense: Apache-2.0

Install this agent skill to your local

pnpm dlx add-skill https://github.com/incursa/workbench/tree/HEAD/skills/workbench-docs

Skill Files

Browse the full folder contents for workbench-docs.

Download Skill

Loading file tree…

skills/workbench-docs/SKILL.md

Skill Metadata

Name
workbench-docs
Description
Documentation workflows for Workbench CLI. Use when creating or updating specs, architecture docs, verification docs, runbooks, guides, or general docs, and when syncing backlinks or change notes.

Key settings

  • .workbench/config.json: paths.docsRoot, paths.templatesDir, ids.width, prefixes, git.defaultBaseBranch, github.owner, github.repository.
  • Use workbench config show --format json to verify effective settings.

Core workflows

  1. Planning phase: create specs and architecture docs before major changes.
  2. Doing phase: keep docs updated as implementation decisions change.
  3. Keep doc front matter and backlinks in sync.
  4. Summarize doc changes when publishing.

Commands

Create a doc:

workbench doc new --type doc --title "Title" --path docs/title.md --work-item WI-WB-0001

Create a spec:

workbench doc new --type spec --title "Title" --path specs/SPEC-EXAMPLE.md --work-item WI-WB-0001

Create an architecture doc:

workbench doc new --type doc --title "System design" --path architecture/system-design.md --work-item WI-WB-0001

Create a verification doc:

workbench doc new --type verification --title "Proof" --path verification/proof.md --work-item WI-WB-0001

Link a doc to work items:

workbench doc link --type spec --path specs/SPEC-EXAMPLE.md --work-item WI-WB-0001

Sync front matter and backlinks:

workbench doc sync --all --dry-run
workbench doc sync --all

Summarize doc changes:

workbench doc summarize --staged --update-index

Output

  • Markdown docs with Workbench front matter and backlinks.
  • Updated work item references in docs and work items.

Guardrails

  • Keep doc types aligned with folder intent (specs, architecture, verification, runbooks, and general docs).
  • Always link docs to relevant work items with --work-item or workbench item link.
  • When writing markdown, use clickable relative links for repository-local references, and keep inline code styling inside the link text when needed. Use absolute URLs only for external resources such as NuGet package pages.
  • For major changes, write a spec before implementation.
  • Prefer workbench doc commands; workbench spec and workbench adr are deprecated.