Skip to content
Skills Library
Programming · Writing

design-doc

/design-doc

Use when the user wants a system design doc or RFC written for a feature, or a quick gap check of one: requirements, constraints, architecture, data model, APIs, rollout, and risks. A rigorous multi-expert review before implementation belongs to spec-panel.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the user wants a system design doc or RFC written for a feature, or a quick gap check of one: requirements, constraints, architecture, data model, APIs, rollout, and risks. A rigorous multi-expert review before implementation belongs to spec-panel.

Original author description

Use when the user wants a system design doc or RFC written for a feature, or a quick gap check of one: requirements, constraints, architecture, data model, APIs, rollout, and risks. A rigorous multi-expert review before implementation belongs to spec-panel.

How it works

  1. Modes
  2. Rules
  3. Workflow context
  4. Output contract
Original SKILL.md headings · 35 lines, 366 words
SKILL.md preview
---
name: design-doc
description: "Use when the user wants a system design doc or RFC written for a feature, or a quick gap check of one: requirements, constraints, architecture, data model, APIs, rollout, and risks. A rigorous multi-expert review before implementation belongs to spec-panel."
---

# Design doc (RFC)

A design doc decides how a feature or system will be built, with the alternatives weighed. It takes the what and why from a `prd` as given; a single decision that needs a lasting record goes in an `adr`.

## Modes
- **Write**: produce the doc from `assets/design-doc.md`, keeping only the sections this design needs.
- **Review**: for an existing doc, list concrete gaps and proposed fixes in severity order; do not rewrite it unasked.

Ask only what is missing: the problem and user, 1-3 measurable outcomes, hard constraints (deadline, compatibility, latency, cost, compliance), and what is out of scope. Read the code the design touches before proposing anything; reuse existing modules and framework features before adding components.

## Rules
- Requirements and non-goals before architecture.
- At least two real alternatives, including "extend what exists" when it is plausible, each with honest trade-offs. No straw men.
- Data model first: entities, ownership, keys, access patterns. Follow the house rules where the stack applies: money as `BigDecimal` / `NUMERIC`, time as `Instant` or `OffsetDateTime` / `TIMESTAMPTZ`, internal IDs as TSID `BIGINT`, external IDs as UUIDv7, API errors as RFC 9457 Problem Details. Leave schema and contract detail to `data-design`, `api-design`, and `db-migration`.
- For each external call or async step, state its failure semantics (timeout, duplicate, partial success, unknown outcome) and what the system does then. Choose retries, idempotency, or compensation from those semantics; never assume success.
- Rollout covers compatibility, migration, and a rollback or restore path. Feature flags, staged exposure, and new dashboards only when the risk calls for them.
- Test strategy names the business behaviors and failure modes to prove, not a layer checklist.
- End with open questions (owner each) and a 5-10 item review checklist reviewers can verify quickly.

## Workflow context
- `prd` says what and why; `design-doc` says how; `adr` records one decision; `decision-matrix` compares options when the choice is hard.
- Depth lives in `api-design`, `data-design`, `infra-design`, `migration-plan`.
- Feeds `ticket-breakdown`, `test-plan`, `security-review`, `performance-review`, `spec-to-impl`.

## Output contract
```yaml
produces:
  - type: "design-doc"
    format: "markdown"
    path: "claudedocs/<feature>-design-doc.md"
    sections: [requirements, architecture, data_model, apis, rollout, risks]
    handoff: "Write claudedocs/handoff-design-doc-<timestamp>.yaml - suggest: spec-to-impl, test-plan, security-review"
```
Files in this package (2)
  • SKILL.md 3 KB
  • assets/design-doc.md 2 KB

Versions

RepositoryScoreLicence
This page · omexit/claude-skills-pack100MIT
userKael/rastro100MIT
hxxnn/codemap100MIT
lamngockhuong/aiteamkit100MIT
bdfinst/agentic-dev-team100MIT

Database snapshot: 13.11.2026 · package version 9ecb38b9d643 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tech-design-doc
    Use when authoring, scaffolding, or auditing a technical design doc, RFC, ADR, technical spec, or architecture proposal — for any audience including external dev partners. Triggers include "design doc for X", "I need an RFC", "should this be an ADR or a full design doc", "help…
  • 100writing-rfc
    Write an RFC or design doc — summary-first, with goals/non-goals, real alternatives, drawbacks, and open questions. Use when proposing a technical change for review, writing a design doc, or documenting a system or feature proposal before building it.
  • 100engineer-design-review
    Use when asked to "review this design doc", "review my RFC", "sanity check this plan before we build", "design review", "poke holes in this proposal" or "is this plan a go", including when the doc is not attached yet (load this skill first, then ask for the doc). Reviews a…
  • 100tech-design-generation
    Generates professional Technical Design Documents following industry-standard engineering practices. This skill activates when the user asks to write a technical design, create an architecture design, draft a design doc, write a technical proposal, do system design, create a…
  • 100rfc
    Drafts a short design RFC for a planned change. Interviews the user one question at a time about the problem, goals, non-goals, constraints and options, reads the code the change touches, then writes the RFC as Markdown to the project's RFC folder and can publish it to Notion.…
  • 100design-docs
    Writes and reviews technical design documents (RFCs) and Architecture Decision Records (ADRs) with goals and non-goals, real alternatives, risks, security, rollout, rollback and observability. Use when planning a new system, service or major feature, choosing between…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.