Menu
Use when authoring or substantially editing a design doc, architecture doc, or subsystem explanation โ the "here's what's there and why" companion to an ADR's terse decision record.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when ingesting, refreshing, listing, searching, or deleting a local corpus with Blackbird code search and `gh blackbird search --fileset`.
Use when reaching for `gh blackbird` (Blackbird code search) for cross-repo lexical, symbol, or semantic search on GitHub โ finding callers, ownership, or how systems work without cloning.
Use when creating a GitHub pull request, or when updating an existing PR's title or body so it matches what the code actually does.
Use when creating a repo-tracked multi-agent planning PR for a large project, especially when phases, living docs, parallel agent prompts, and cross-PR coordination are needed.
Use when about to call a library, crate, or framework API you haven't verified, when a dependency's behavior is surprising, when training-data memory might be stale, or when investigating how a dependency actually behaves.
Use when investigating an alert, monitor, incident, error spike, degraded service, or production anomaly, and the repository has no incident-investigation skill of its own.
| name | design-doc-author |
| description | Use when authoring or substantially editing a design doc, architecture doc, or subsystem explanation โ the "here's what's there and why" companion to an ADR's terse decision record. |
Design docs explain how a system actually works โ its shape, mechanism, invariants, and trade-offs. They are the long-form complement to an ADR.
This is a user-level skill โ repo-local conventions, when they exist, always win over the defaults here.
These four artifacts pair up. Knowing which to reach for is half the work:
adr-author.docs/<topic>-architecture.md, docs/design/<topic>.md, or the repo's equivalent.planning-multi-agent-projects for durable repo-tracked planning hubs.A mature subsystem often has the ADR, design doc, and plan; a SKILL only when there's a recurring failure mode worth pinning. They cross-link.
Write a design doc when:
Don't write one for:
Locations vary by repo:
docs/design/<topic>.md directory of focused subsystem docs.docs/<topic>-architecture.md at the repo root, paired with docs/<topic>-plan.md.docs/<area>/<topic>.md layout.Look at sibling docs before picking a location. Match the established pattern โ don't introduce a parallel convention.
If the repo has no design-doc convention at all, default to docs/design/<topic>.md and mention the choice in your next message so the user can correct it.
Don't stash design docs in a session scratch directory, /tmp, or any other location the user can't see in the file tree โ a doc the user can't read is a doc they can't iterate on. A doc on a feature branch is, by definition, a draft; the branch and PR are what mark it as in-progress. Land the file at its real path from the first version and edit it in place.
Open the doc with a short "read this first" block: companion docs (ADR, SKILL, related design docs, active plans), and a one-paragraph summary of what the doc covers. Future readers should know within 30 seconds whether they're in the right place.
# <Topic> โ Architecture
> **Read this first.** Companion docs:
> - [`docs/adr/NNNN-<topic>.md`](...) โ the decision that led here.
> - [`skills/<topic>/SKILL.md`](...) โ the hard rules contributors must follow.
> - [`docs/<topic>-plan.md`](...) โ execution sequence (history; not the design).
One paragraph: what this doc explains, and what it does **not** cover.
The first substantive section should answer "why does this exist?" โ what forced the current shape. Without that frame, the rest of the doc reads as arbitrary structure. Reference the ADR if there is one, but restate the framing in the design doc's own voice.
If the subsystem has invariants โ complexity bounds, layering rules, ordering guarantees, performance budgets, security properties โ name them explicitly. A contract turns the doc from prose into something reviewers can hold a PR against.
If the contract has hard laws that contributors must apply during day-to-day work, those belong in a SKILL, not duplicated in the design doc. Link out, don't repeat.
After the why and the contract, walk the actual mechanism: pipeline stages, data flow, key types, interaction sequences. Use ASCII or mermaid diagrams when they earn their place. Be concrete โ name actual files, functions, and types.
Avoid generic boilerplate ("the request enters the system, is validated, and routed"). If the same sentence could appear in any design doc, delete it.
Design docs that pretend everything is figured out age badly. Include a section for:
This is what makes the doc honest. A reader can trust the rest if they see the unknowns named.
Once written, cross-link:
Related: line points at the design doc.Bidirectional links keep the four artifacts navigable.
A design doc says what the system is. A plan says how we get there from here. Plans are time-bound and become history once executed; design docs are durable references.
If a plan accumulates design content during execution, harvest the design into a real design doc and leave the plan as a record of the work. Don't let the plan doc become the de facto design doc โ it ages out the moment the work ships.
When the system changes:
The temptation this skill prevents: reaching for a design doc whenever a system feels "important enough" to deserve one, when an ADR, a few code comments, or a README update would actually serve readers better. The excuse: "future contributors will want this written down." The loophole closer: a design doc earns its existence only when there's a recurring need for the explanation โ onboarding pain, repeated misunderstandings, invariants reviewers can't enforce without it. If you cannot name the recurring need, write the ADR or the code comment and stop.