agentleFS
tjst-ttjst-t/claude-skills/skills/design/SKILL.md

design

Skill0 starsChanged 4 months agoMITView on GitHub

Front-loads architectural design for complex systems. Guides a user from a fuzzy idea through dialogue to a structured set of design documents (VISION, DESIGN_PRINCIPLES, domain model, system architecture, ADRs, non-functional requirements) before implementation begins. The output feeds autopilot setup and sprint planning.

198 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ui-styling, infra-audit and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    ui-styling

    Guide for the visual style, structure, and shared building blocks used by Semantic Link Labs interactive UI tools (HTML widgets and anywidget-based widgets). Use this when adding a new interactive UI, modifying an existing one, or adding shared visual components.

    Also in 39 projects that use this

  • mayankjain1815-commitsSkill

    infra-audit

    Reads docker-compose, env files, ORM configs, and connection strings to map current infrastructure. Flags missing layers (cache, queue, analytics) based on observed access patterns. Outputs a structured infrastructure manifest.

    Also in 3 projects that use this

  • JetBrainsSkill

    slides

    Create and edit presentation slide decks (`.pptx`) with PptxGenJS and render/validation utilities. Use when tasks involve building a new PowerPoint deck, recreating slides from screenshots/PDFs/reference decks, modifying slide content while preserving editable output, adding charts/diagrams/visuals, or diagnosing layout issues such as overflow, overlaps, and font substitution.

    Also in 42 projects that use this

  • AnthropicSkill

    design-system

    Audit, document, or extend your design system. Use when checking for naming inconsistencies or hardcoded values across components, writing documentation for a component's variants, states, and accessibility notes, or designing a new pattern that fits the existing system.

    Also in 49 projects that use this

  • henrikthome-archSkill

    infra

    Manage all infrastructure for the Volos school project — Render (API backend), Cloudflare (DNS + Pages frontend), PostgreSQL database, and GitHub Actions workflows.

    Also in 3 projects that use this

  • Daeguk-SunSkill

    acceptance

    story 또는 epic 구현 완료 후 제품 단위 검수를 수행하는 MVP skill. 사용자가 "/acceptance story", "/acceptance epic", "story 검수", "epic 검수", "AC 기준으로 완료됐는지 봐줘" 등을 말할 때 사용한다. full E2E 검증은 MVP 범위 밖이지만, 핵심 AC가 mock-only green이나 대상 사용자에게 부적합한 입력/진행 동선으로만 닫히는 것은 gap으로 분리한다. direct `/impl` 단발 작업에 자동 강제하지 않는다.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 7 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 175 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If none of the above hold, the decision belongs in sprint plan or sprint run, not here.

    line 27
  2. Distinctive:

    When a command is invoked, read the corresponding reference file before taking any action.

    line 49
  3. Very specific:

    All files are JSON for the same reasons ROADMAP.json is JSON: machine-readable, easy to slice with jq, integrates with the rest of the …

    line 68
  4. Distinctive:

    Before Phase 1, detect existing state and pick the mode:

    line 74
  5. Very specific:

    Add a single new ADR after the initial design is established.

    line 112
  6. Distinctive:

    Ask the user: title, context, alternatives, decision, consequences, reversibility cost.

    line 115
  7. Very specific:

    Write docs/DESIGN/adr/ADR-{NNNN}-{kebab-title}.json per references/ADR_SCHEMA.json.

    line 116
  8. Distinctive:

    If the ADR contradicts an existing one, prompt: "Should ADR-XXXX be marked superseded?"

    line 117
  9. Very specific:

    Read all docs/DESIGN/*.json and the ADR set.

    line 121
  10. Very specific:

    Read docs/DESIGN/ and present a one-screen view: artifact presence, ADR counts by status, open questions (from tentative: true items).

    line 130
  11. Distinctive:

    Front-load, don't over-design: Only put decisions in DESIGN/ that meet the scope discriminator.

    line 134
  12. Distinctive:

    ADRs are append-only: Never edit an accepted ADR to change its meaning.

    line 137
  13. Distinctive:

    Reversibility cost is a first-class field: Every ADR records this. It's how future Claude (and the user) decides whether to revisit a …

    line 139
  14. Very specific:

    autopilot setup: When invoked, detects existing docs/DESIGN/.

    line 144
  15. Very specific:

    sprint run / sprint auto: When making an autonomous technical decision, check whether it touches anything in DESIGN/.

    line 146
  16. Very specific:

    When autopilot review classifies a user request as ④ direction change (see autopilot/SKILL.md → Review Mode) AND docs/DESIGN/ exists, it …

    line 155
  17. Very specific:

    If docs/DESIGN/ does NOT exist, ④ skips this handoff and autopilot review re-runs sprint roadmap directly.

    line 162

“Common” is measured: kept by at least 6 in 10 of the 175 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design

Front-loads load-bearing design decisions for complex systems through guided dialogue. Produces VISION, DESIGN_PRINCIPLES, and a docs/DESIGN/ set of architectural artifacts that sprint and autopilot read as authority.

Philosophy

The sprint/autopilot workflow defers technical decisions to implementation time. That is correct for reversible, locally-scoped decisions. For complex systems (hydra-class) it breaks down: cross-cutting and irreversible decisions made locally cause drift, integration pain, and expensive rework.

This skill identifies and locks the load-bearing decisions before implementation starts. It deliberately does NOT decide reversible things (library choice, naming, file layout) — those stay autonomous in sprint run.

Scope discriminator

A decision belongs in this skill if ANY of:

  • It spans multiple Sprints (changing it later touches >1 Sprint)
  • It is non-trivially reversible (migration cost is meaningful)
  • It locks a contract other parts will rely on (data model, API, protocol, domain boundary)
  • It has a real trade-off between viable alternatives

If none of the above hold, the decision belongs in sprint plan or sprint run, not here.

InOut
Product intent (VISION)Library selection
Judgment rules (DESIGN_PRINCIPLES)Code style, naming, file layout
Domain model (entities, relationships, glossary)Sprint-local error handling
System architecture (components, boundaries, key interfaces, data flow)Test framework choice
Non-functional requirements (perf, consistency, security targets)Single-Sprint local design
Load-bearing decisions (ADR)Reversible per-Story decisions
Data model / protocol contracts (when stateful/distributed)UI micro-copy

Commands

CommandPurpose
design startInteractive design dialogue (3 phases). Produces all artifacts.
design adrAdd a new ADR when a load-bearing decision emerges later
design refreshRe-read all DESIGN/ docs and find inconsistencies or stale items
design statusShow design state (artifacts present, ADR list, open questions)
design helpCommand list

When a command is invoked, read the corresponding reference file before taking any action.

Output layout

docs/
├── VISION.json                      # Product intent (autopilot schema)
├── DESIGN_PRINCIPLES.json           # Judgment rules (autopilot schema)
└── DESIGN/
    ├── domain.json                  # Entities, relationships, glossary
    ├── system.json                  # Components, boundaries, key interfaces, data flow
    ├── non-functional.json          # Performance/availability/security targets
    ├── data.json                    # (optional) Schema / protocol contracts
    └── adr/
        ├── ADR-0001-{kebab-title}.json
        ├── ADR-0002-{kebab-title}.json
        └── ...

All files are JSON for the same reasons ROADMAP.json is JSON: machine-readable, easy to slice with jq, integrates with the rest of the toolchain.

design start

A three-phase dialogue: 発散 (Divergence) → 収束 (Convergence) → 構造化 (Structuring). The full prompt set, exit signals, and per-phase patterns live in references/design-flow.md. Read it before starting.

Before Phase 1, detect existing state and pick the mode:

have_vision=$([ -f docs/VISION.json ] && echo 1 || echo 0)
have_principles=$([ -f docs/DESIGN_PRINCIPLES.json ] && echo 1 || echo 0)
have_design_dir=$([ -d docs/DESIGN ] && [ -n "$(ls -A docs/DESIGN 2>/dev/null)" ] && echo 1 || echo 0)
ModeTriggerBehavior
Freshno VISION, no PRINCIPLES, no DESIGN/Full Phase 1 → 2 → 3
BackfillDESIGN/ exists, VISION OR PRINCIPLES missingSkip Phase 1. Derive missing files from DESIGN/ per design-flow.md "Backfill mode", ask only for non-derivable fields, write missing files only
UpdateVISION exists, DESIGN/ absent or partialRead VISION/PRINCIPLES as context. Run shortened Phase 1 (only gaps), then Phase 3 for missing DESIGN/ artifacts
All presentVISION, PRINCIPLES, DESIGN/ all existStop and route the user to design refresh or design adr. Confirm before anything destructive

State the detected mode to the user before proceeding, so they can correct if it's wrong.

Output layout (Fresh / Update modes write some/all of these)

docs/
├── VISION.json                      references/VISION_SCHEMA.json
├── DESIGN_PRINCIPLES.json           references/DESIGN_PRINCIPLES_SCHEMA.json
└── DESIGN/
    ├── domain.json                  references/DOMAIN_SCHEMA.json
    ├── system.json                  references/SYSTEM_SCHEMA.json
    ├── non-functional.json          references/NON_FUNCTIONAL_SCHEMA.json
    ├── data.json (optional)         references/DATA_SCHEMA.json
    └── adr/
        └── ADR-NNNN-{kebab-title}.json   references/ADR_SCHEMA.json

All files are JSON for the same reasons ROADMAP.json is JSON: machine-readable, easy to slice with jq, integrates with the rest of the toolchain.

Generate artifacts in dependency order (VISION → PRINCIPLES → domain → system → non-functional → ADRs → data). Present each draft to the user for confirmation before writing. For each load-bearing decision surfaced during Phase 2, walk through context / alternatives / decision / consequences / reversibility cost — see references/adr-template.md for the heuristic on what warrants an ADR.

design adr

Add a single new ADR after the initial design is established. Typical trigger: a load-bearing decision emerges during sprint plan.

  1. Compute next ADR number: ls docs/DESIGN/adr/ 2>/dev/null | grep -oE '^ADR-[0-9]+' | sort -V | tail -1 | sed 's/ADR-0*//' (treat empty as 0), then +1.
  2. Ask the user: title, context, alternatives, decision, consequences, reversibility cost.
  3. Write docs/DESIGN/adr/ADR-{NNNN}-{kebab-title}.json per references/ADR_SCHEMA.json.
  4. If the ADR contradicts an existing one, prompt: "Should ADR-XXXX be marked superseded?"

design refresh

Read all docs/DESIGN/*.json and the ADR set. Report (do NOT auto-fix):

  • ADRs whose Decision conflicts with another ADR
  • ADRs marked tentative: true that haven't been resolved
  • References to entities/components in ADRs that don't exist in domain.json/system.json (broken links)
  • Non-functional targets not referenced by any ADR (possibly orphaned)

design status

Read docs/DESIGN/ and present a one-screen view: artifact presence, ADR counts by status, open questions (from tentative: true items). See references/design-help.md for the exact format.

Important behaviors

  • Front-load, don't over-design: Only put decisions in DESIGN/ that meet the scope discriminator. Anything not meeting it stays in sprint plan/run.
  • Dialogue first, structure last: Phase 1 is conversation, not a questionnaire. The structured artifacts come at Phase 3.
  • Always confirm before writing: Each artifact gets a draft presented to the user. The user has veto power on every file.
  • ADRs are append-only: Never edit an accepted ADR to change its meaning. Supersede it with a new ADR that references the old one.
  • JSON for tooling, prose where it matters: Schemas are JSON, but context / decision / consequences fields are free-form prose. The point is to write down reasoning, not fill in cells.
  • Reversibility cost is a first-class field: Every ADR records this. It's how future Claude (and the user) decides whether to revisit a decision.
  • Living documents: design refresh is meant to be run periodically — at every milestone in autopilot, or whenever the architecture feels off.

Connection to sprint and autopilot

  • autopilot setup: When invoked, detects existing docs/DESIGN/. If present, skip the VISION/PRINCIPLES question phase (they're already authoritative). sprint roadmap reads docs/DESIGN/system.json and ADRs as additional context when generating Sprints.
  • sprint plan: First step is now to consult docs/DESIGN/adr/ for any ADR whose affects field overlaps with the upcoming Sprint's Stories. Surfaced ADRs are read in full and treated as constraints. Decisions in the Sprint plan that contradict an ADR must either (a) revise the Sprint plan, or (b) be escalated to the user as an ADR amendment.
  • sprint run / sprint auto: When making an autonomous technical decision, check whether it touches anything in DESIGN/. If yes, the decision must respect the ADR or escalate. If no, proceed and log to decisions.json as before.
  • decisions.json: Each entry should include an optional adr_ref field pointing to the ADR(s) the decision is based on, or "none" if it's a sprint-local decision.

ADR-necessity auto-check during sprint plan

During sprint plan / sprint idea, Claude must actively watch for a load-bearing decision surfacing without a covering ADR. The signals that should prompt an "ADR が必要では?" suggestion to the user are in references/adr-template.md → "Signals that an ADR is required". If any signal fires and no existing ADR covers it, suggest design adr before sprint run starts. If no signal fires, the decision stays autonomous and is logged to decisions.json only.

autopilot review ④ direction-change handoff

When autopilot review classifies a user request as ④ direction change (see autopilot/SKILL.md → Review Mode) AND docs/DESIGN/ exists, it hands off to this skill in a fixed order:

  1. autopilot review calls design refresh internally to check consistency — existing-ADR contradictions and broken links (entities/components that the change would orphan).
  2. The impact (which ADRs conflict, what would break) is presented to the user.
  3. On approval, design adr adds a new ADR or supersedes an existing one (ADRs are append-only — never edit an accepted ADR's meaning).
  4. Finally sprint roadmap is re-run so downstream Sprints reflect the new decision.

If docs/DESIGN/ does NOT exist, ④ skips this handoff and autopilot review re-runs sprint roadmap directly. This skill and autopilot review are not mutually exclusive — on ④ they compose, with autopilot review as the caller.

Reference files

  • references/design-flow.md — Phase 1/2/3 dialogue patterns, sample prompts, and "when to move to next phase" heuristics
  • references/domain-template.md — Domain model template and writing guide
  • references/system-template.md — System architecture template and writing guide
  • references/adr-template.md — ADR template, identification heuristics, "what does and does not warrant an ADR"
  • references/non-functional-template.md — Non-functional requirements template
  • references/data-template.md — Data / protocol design template (used when applicable)
  • references/VISION_SCHEMA.json — VISION.json schema and example. Owned here — design is the authority that generates VISION; autopilot setup reads this schema for its inline (simpler) VISION generation.
  • references/DESIGN_PRINCIPLES_SCHEMA.json — DESIGN_PRINCIPLES.json schema and example. Owned here for the same reason.
  • references/DOMAIN_SCHEMA.json — Domain JSON schema and example
  • references/SYSTEM_SCHEMA.json — System JSON schema and example
  • references/ADR_SCHEMA.json — ADR JSON schema and example
  • references/NON_FUNCTIONAL_SCHEMA.json — Non-functional JSON schema and example
  • references/DATA_SCHEMA.json — Data / protocol JSON schema and example
  • references/design-help.md — Help text shown by design help

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.