New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Design Docs

by ZaxbyHub in ZaxbyHub/opencode-swarm

Full execution protocol for MODE: DESIGNDOCS — generate or sync structured, language-agnostic design docs (domain.md, technical-spec.md, behavior-spec.md, reference/) for the project under build…

MITAuto-check passedDevelopment

Install Design Docs

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

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ZaxbyHub/opencode-swarm design-docs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ZaxbyHub/opencode-swarm.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/design-docs .claude/skills/design-docs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
design-docs
GitHub stars
494
Token cost
~1.5k tokens
SKILL.md length
532 words
Files
1
Skills in repo
91
Repo updated
First seen
Licence
MIT

At a glance

Full execution protocol for MODE: DESIGNDOCS — generate or sync structured, language-agnostic design docs (domain.md, technical-spec.md, behavior-spec.md, reference/) for the project under build…

  • Works in 6 steps: Parse Header → Preconditions → Index Existing State (always) → …
  • Tasks that involve Architecture decision records
  • SKILL.md covers Step 0 — Parse Header, Step 1 — Preconditions, Step 2 — Index Existing State… and Step 3 — Generate or Sync, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Design Docs is an agent skill from ZaxbyHub/opencode-swarm. Full execution protocol for MODE: DESIGNDOCS — 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: DESIGNDOCS ...] signal (issue 1080).

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Architecture decision records. The repository describes itself as: Architect-centric agentic swarm plugin for OpenCode. Hub-and-spoke orchestration with SME consultation, code generation, and QA review. The licence is MIT.

When your agent uses it

  • Tasks that involve Architecture decision records

Example prompts

  • “/design-docs”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Parse Header
  2. Preconditions
  3. Index Existing State (always)
  4. Generate or Sync
  5. Invariants the docs MUST satisfy
  6. Verify & Report

What it can do on your machine

Read from SKILL.md and the folder at commit b63a4bd. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Design Docs loads about 1.5k tokens when it runs. Until then it costs about 96 tokens; SKILL.md has 532 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~96
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ZaxbyHub/opencode-swarm at commit b63a4bd, republished under its MIT licence (© ZaxbyHub). 532 words, ~1,488 tokens.

Download SKILL.mdSave it as .claude/skills/design-docs/SKILL.md (or your agent's skills folder).
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).
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)
Show full SKILL.md (235 more words)Show less

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. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/design-docs of ZaxbyHub/opencode-swarm.

Open the folder on GitHubat commit b63a4bd

Compare with similar skills

Design Docs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Design Docs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Design Docs this skillZaxbyHub/opencode-swarm494—~1.5kAutomated safety check: PassMIT
PR Design DocOpenHands/OpenHands90k—~2.4kAutomated safety check: PassMIT
Cto AdvisorIbrahim-3d/orchestrator-supaconductor3814 repos~2.4kAutomated safety check: PassMIT
Architecture DecisionDonchitos/Claude-Code-Game-Studios26k—~1.7kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0
Domain Modelingbrim-borium/spotify_sdk1665 repos~806Automated safety check: PassApache-2.0

Similar skills

  • PR Design Doc

    OpenHands/OpenHands

    For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link a visibility-appropriate preview in the PR description, so maintainers grasp the…

    90k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed

  • Cto Advisor

    Ibrahim-3d/orchestrator-supaconductor

    Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.

    381 GitHub starsUsed in 4 repos~2.4k tokens
    DevelopmentAuto-check passed

  • Architecture Decision

    Donchitos/Claude-Code-Game-Studios

    Create an ADR documenting a technical decision: context, alternatives considered, consequences.

    26k GitHub stars~1.7k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

  • Improve Codebase Architecture

    ywwynm/EverythingDone

    Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed

  • Domain Modeling

    brim-borium/spotify_sdk

    Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.

    166 GitHub starsUsed in 5 repos~806 tokens
    DevelopmentAuto-check passed

  • Design Doc Mermaid

    SpillwaveSolutions/design-doc-mermaid

    Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.

    176 GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed

More from ZaxbyHub/opencode-swarm

All 91 skills in this repo

  • Codebase Review Swarm

    ZaxbyHub/opencode-swarm

    Runs an evidence-gated, quote-grounded audit of a codebase for security, QA, accessibility, performance and more, and writes a verified report without changing source files.

    494 GitHub stars~2.8k tokensUpdated today
    Auto-check passed

  • Issue Tracer

    ZaxbyHub/opencode-swarm

    Drives a bug report from validation and root-cause tracing through a critic-reviewed plan, an approved minimal fix and a PR-ready closure, never merging without recorded human approval.

    494 GitHub stars~4.4k tokensUpdated today
    Auto-check passed

  • Commit and PR Publishing for Codex

    ZaxbyHub/opencode-swarm

    Codex adapter for opencode-swarm that governs commits, pushes, draft PRs, PR body updates and CI closeout, deferring to the repo's canonical commit-pr protocol.

    494 GitHub stars~1.6k tokensUpdated today
    Auto-check passed

  • Durable Session State

    ZaxbyHub/opencode-swarm

    Keeps plans, decisions, evidence and reviewer verdicts in small files so long multi-phase tasks survive context compaction and session resumes.

    494 GitHub stars~896 tokensUpdated today
    Auto-check passed

  • Swarm PR Feedback Closer

    ZaxbyHub/opencode-swarm

    Ingests existing pull request feedback such as review comments and CI failures, verifies each claim, fixes confirmed issues and reports closure status for every item.

    494 GitHub stars~14k tokensUpdated today
    Auto-check passed

  • Swarm PR Subscribe

    ZaxbyHub/opencode-swarm

    Monitor a pull request after creation and act autonomously on pushed PR activity.

    494 GitHub stars~2.2k tokensUpdated today
    Auto-check passed

Categories

Questions about Design Docs

What does Design Docs do?

Full execution protocol for MODE: DESIGNDOCS — generate or sync structured, language-agnostic design docs (domain.md, technical-spec.md, behavior-spec.md, reference/) for the project under build…. Design Docs is an agent skill from ZaxbyHub/opencode-swarm.md, reference/) for the project under build, with a stable section-ID registry and a design changelog.

When should I use Design Docs?

Design Docs fits situations like: tasks that involve Architecture decision records.

How do I install Design Docs in Claude Code?

Run `npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a claude-code`. Or copy the skill folder (.claude/skills/design-docs in ZaxbyHub/opencode-swarm) into .claude/skills/design-docs in your project. Claude Code loads it when a task matches its description.

How do I install Design Docs in Codex?

Run `npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a codex`. Or copy the skill folder (.claude/skills/design-docs in ZaxbyHub/opencode-swarm) into .agents/skills/design-docs in your project. Codex loads it when a task matches its description.

Can I use Design Docs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/design-docs, .gemini/skills/design-docs, .github/skills/design-docs and .opencode/skills/design-docs in your project.

What does Design Docs need to run?

SKILL.md names no scripts, command-line tools or credentials: Design Docs is instructions for the agent only.

Does Design Docs access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Design Docs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Design Docs use?

Design Docs is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Design Docs use?

About 1.5k tokens (SKILL.md is roughly 6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Design Docs?

Skills that share tags, products or a category with Design Docs: PR Design Doc (OpenHands/OpenHands, 90k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 381 stars), Architecture Decision (Donchitos/Claude-Code-Game-Studios, 26k stars) and Improve Codebase Architecture (ywwynm/EverythingDone, 144 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Design Docs?

ZaxbyHub (a GitHub organization) maintains it in ZaxbyHub/opencode-swarm, which has 494 GitHub stars. The repository holds 91 skills in this directory. The repository was last updated on October 10, 2026.

Source: ZaxbyHub/opencode-swarm on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.