Skip to main content
skill CX Codex

design-docs — Claude Code skill: what it does, how to install

Writes and syncs a project's design docs: domain, technical spec, behavior spec, plus a traceability registry and changelog.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a claude-code
Open on GitHub

What design-docs does

The skill carries the execution protocol for DESIGN_DOCS. When the design-docs command emits a [MODE: DESIGN_DOCS ...] header, the architect loads this file and work moves into the repo being built. Output is a fixed set: domain.md with entities and invariants, technical-spec.md with layers and contract shapes, behavior-spec.md as Given/When/Then, a design changelog, and a reference/ folder for anything language-specific.

The header supplies out (default docs), lang (default auto) and the update flag; with update=false the trailing text has to describe the system. Writing goes to the docs_design subagent. Section IDs (D-###, S-###, B-###, R-###) are minted once and kept across syncs. The registry sits in reference/traceability.json, and each section ends with a traceability line pointing at spec FRs.

Framework and library names stay out of the three normative files. Signatures, SQL, CLI strings and code belong under reference/. One precondition matters: the docs_design agent exists only when design_docs.enabled is true in opencode-swarm.json. Skip that flag and the protocol halts at step one. A pending spec-staleness marker can block writes with SPEC_DRIFT_BLOCK too.

What it helps with

  • generate a domain model and technical spec for a fresh project
  • sync design docs after a phase of code changes
  • keep section IDs stable across regenerations
  • map doc sections back to spec requirements
  • keep framework details in reference/ instead of normative text

Example prompts for the agent

  • Run design-docs with out=docs and update=false for the booking service.
  • Sync docs/ against this phase's diff in src/orders/.
  • Check behavior-spec.md for framework names and append the changelog entry.

How to install design-docs

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a claude-code

2Manually: put the files in place

~/.claude/skills/design-docs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-docs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about design-docs

How do I install design-docs for Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a claude-code. The skill file lands at ~/.claude/skills/design-docs/SKILL.md.

What does design-docs do?

It generates and syncs the project's design docs: domain, technical spec, behavior spec, changelog and reference/. It runs when the design-docs command emits a [MODE: DESIGN_DOCS ...] header.

Does it need the opencode-swarm plugin?

Yes. design_docs.enabled must be true in opencode-swarm.json, otherwise the docs_design agent isn't there to write the files.

Source text

SKILL.md · MIT
---
name: design-docs
description: >
  Full execution protocol for MODE: DESIGN_DOCS — generate or sync structured,
  language-agnostic design docs (domain.md, technical-spec.md, behavior-spec.md,
  reference/) for the project under build, with a stable section-ID registry and
  a design changelog. Loaded on demand by the architect when the design-docs
  command emits a [MODE: DESIGN_DOCS ...] signal (issue #1080).
metadata:
  audience: swarm-plugin
---

# Design-Doc Generation & Sync Protocol

Generate or maintain the project's structured design documentation. The work is delegated to the `docs_design` agent (a design-doc-author role variant of the docs agent). This mode authors a fixed set of version-controlled docs in the **target project repo** (NOT under `.swarm/`). It does NOT modify source code, does NOT call `declare_scope`, and does NOT touch `.swarm/spec.md`, `CHANGELOG.md`, or `docs/releases/pending/*`.

### MODE: DESIGN_DOCS

## Step 0 — Parse Header

Parse the `[MODE: DESIGN_DOCS ...]` header to extract:
- `out`: output directory, project-relative (default `docs`)
- `lang`: target language for `reference/` docs, or `auto` (default `auto`)
- `update`: boolean — `true` = sync existing docs to current code/spec; `false` = generate fresh
- the trailing free text = the system description (required when `update=false`)

If the header is malformed, report the error and stop.

## Step 1 — Preconditions

1. Confirm `design_docs.enabled` is true (the `docs_design` agent only exists when enabled). If it is not, tell the user to set `design_docs.enabled: true` in `opencode-swarm.json` and stop.
2. If a spec-staleness block is active (`.swarm/spec-staleness.json` present), resolve/acknowledge spec staleness FIRST — otherwise design-doc writes may be blocked by the guardrail, which emits `SPEC_DRIFT_BLOCK`. Do not blindly retry on `SPEC_DRIFT_BLOCK`.
3. Read `.swarm/spec.md` if present — it is the authoritative requirements source (FR-### IDs). The design docs must be consistent with it.
   Run `/swarm sdd status` to resolve the effective spec before reading.

## Step 2 — Index Existing State (always)

Have the `docs_design` agent (or `doc_scan`) index `<out>/` to discover any existing design docs. If `<out>/reference/traceability.json` exists, it is the section-ID registry — load it. Existing section IDs MUST be preserved on regeneration.

## Step 3 — Generate or Sync

Dispatch the **`docs_design`** agent (the active swarm's `docs_design` — never the standard `docs` agent) with:
- `TASK`, `MODE` (generate|sync), `OUT_DIR`, `LANGUAGE`
- For sync: `FILES CHANGED` and `CHANGES SUMMARY` from the current phase/diff
- `SKILLS: file:.swarm/bundled-skills/design-docs/SKILL.md` (this skill)

The agent owns exactly these files under `<out>` and creates NOTHING else:

```
<out>/
├── domain.md              # 100% language-agnostic. Entities in neutral notation
│                          #   (field: type-class), domain invariants. ZERO framework
│                          #   names in normative text. Section IDs: D-###
├── technical-spec.md      # Language-agnostic architecture: layers, dependency rules,
│                          #   contract SHAPES (inputs→outputs→error-kinds), algorithms,
│                          #   invariants. + the traceability table. Section IDs: S-###
├── behavior-spec.md       # 100% language-agnostic Given/When/Then specs. IDs: B-###
├── design-changelog.md    # Keep-a-Changelog log of design-doc changes (NOT release notes)
└── reference/             # ALL [INCIDENTAL] language/framework-specific material here.
    ├── reference-impl.md  #   Exact signatures, CLI strings, SQL, code. Mapped to
    │                      #   spec sections by ID. Section IDs: R-###
    ├── idiom-notes.md     #   "Here is how the reference solved X" — examples only.
    └── traceability.json  #   Machine-readable section-ID registry (source of truth)
```

## Step 4 — Invariants the docs MUST satisfy

- **Language-agnostic normative text**: `domain.md`, `technical-spec.md`, and `behavior-spec.md` contain ZERO framework/library/language names in normative content. All such material lives ONLY in `reference/`.
- **Version header** on every doc:
  `<!-- design-doc: <name>  version: <phase-or-counter>  generated: <ISO-8601>  spec-hash: <8 chars> -->`
- **Stable section IDs**: assigned once, never renumbered. `D-###` domain, `S-###` technical-spec, `B-###` behavior-spec, `R-###` reference. On sync, reuse every existing ID; mint new IDs only for genuinely new sections.
- **Traceability footer** ending each section: `> Traceability: FR-012, FR-013 | invariant: <id-or-none>`.
- **traceability.json** kept in sync: `{ "schema_version": 1, "sections": [ { "section_id", "doc", "title", "spec_frs": [], "invariants": [], "code_anchors": [] } ] }`. `technical-spec.md` renders a human-readable mirror table `| Doc Section | Spec FR | Invariant | Code anchors |`.
- **design-changelog.md**: append one entry per generate/sync under `## [Unreleased]` (Added/Changed/Removed), e.g. `- <ISO date> phase <N>: <sections touched> (<FR refs>)`. This file is SEPARATE from release-please artifacts — never edit `CHANGELOG.md` or `docs/releases/pending/*` here.

## Step 5 — Verify & Report

1. Confirm the agent created/updated only the allowed files and `traceability.json` is consistent with the docs.
2. Confirm no normative doc names a framework (spot-check) and every section has an ID + traceability footer.
3. Report `UPDATED` / `ADDED` / `REMOVED` / `SUMMARY` back to the user.

## Notes on the PHASE-WRAP sync path

During PHASE-WRAP, the deterministic design-doc drift check (`runDesignDocDriftCheck`) writes `.swarm/doc-drift-phase-N.json`. If the verdict is `DOC_STALE` and `design_docs.enabled`, dispatch `docs_design` in **sync** mode for the affected sections only, then append a design-changelog entry. This is advisory and non-blocking — never block phase completion on design-doc lag.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Writing and docs →

From the same set121

The whole set →
commit-pr commit-pr — a portable skill that verifies your code before push, writes conventional commits, and fills in a PR body. Guards against accidentally committing generated files or secrets. CX Codex +1 ★ 539repo stars test-file-split test-file-split breaks an oversized test file into parts along describe() boundaries when it nears the 500-line cap or blows past it. CX Codex +1 ★ 539repo stars fork-pr-operations fork-pr-operations guides agents through fork pull request workflows: GitHub Actions approval, safe rebasing with force-with-lease, and handling multi-round bot reviews. CX Codex +1 ★ 539repo stars parallel-work-check parallel-work-check is a Claude Code skill that compares local and remote commits on an existing branch and reviews new changes. It helps catch overlapping work before editing. CX Codex +1 ★ 539repo stars orchestrating-subagents orchestrating-subagents is a Claude Code skill for dividing project tasks among subagents, with parallel explorers and independent code review in isolated contexts. CX Codex +1 ★ 539repo stars commit-pr The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars contributing contributing walks an agent through the full pull-request cycle in the opencode-swarm repo: branch naming, commit format, a release-notes fragment, local checks and the PR template. CX Codex +1 ★ 539repo stars clarify-spec clarify-spec resolves spec clarification markers and ambiguous requirements in Swarm projects by asking targeted questions one at a time. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open