Skip to content
Skills Library
Programming · Planning

design

/design

Design component architecture, REST API contracts, and data models (Pydantic schemas) before implementation. Use when planning how to build a feature, defining endpoints, or modeling data. Trigger on "design the architecture", "design the API", "data model", "how should I structure this feature".

Repository
llms ↗
Licence
MIT
Last repository change
21.05.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
17
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: reference/schema-examples.py

What it does and when to use it

Design component architecture, REST API contracts, and data models (Pydantic schemas) before implementation. Use when planning how to build a feature, defining endpoints, or modeling data. Trigger on "design the architecture", "design the API", "data model", "how should I structure this feature".

Triggers from the description

design the architecturedesign the APIdata modelhow should I structure this feature
Original author description

Design component architecture, REST API contracts, and data models (Pydantic schemas) before implementation. Use when planning how to build a feature, defining endpoints, or modeling data. Trigger on "design the architecture", "design the API", "data model", "how should I structure this feature".

How it works

  1. Usage
  2. Workflow
  3. /design full Sequence
  4. Output
  5. Integration
  6. Progressive Disclosure Rules
Original SKILL.md headings · 118 lines, 531 words
SKILL.md preview
---
name: design
description: Design component architecture, REST API contracts, and data models (Pydantic schemas) before implementation. Use when planning how to build a feature, defining endpoints, or modeling data. Trigger on "design the architecture", "design the API", "data model", "how should I structure this feature".
allowed-tools: Read, Write, Edit, Grep, Glob
---

# Design — Architecture, API & Data Models

Unified design guidance for feature implementation. Auto-detects context from project files or accepts explicit mode.

## Usage

```
/design                    # Auto-detect from project, show summary
/design architecture       # Component architecture, SOLID, patterns
/design api                # REST API design, auth, rate limiting
/design data               # Pydantic schemas, validators, relationships
/design full               # All three in sequence (architecture → data → API)
```

## Workflow

### Step 1: Determine Mode

Parse `$ARGUMENTS` for explicit mode. If no arguments provided, detect context:

```bash
DETECTED=$(bash "$HOME/.claude/skills/design/lib/design-detector.sh")
```

Map detection results to recommended mode:

- `pydantic,fastapi` → suggest `api` + `data`
- `pydantic` only → suggest `data`
- `fastapi` or `flask` or `django` → suggest `api`
- Generic Python/Node → suggest `architecture`
- Unknown → show all summaries, let user choose

### Step 2: Show Relevant Guidance

Based on detected or explicit mode, use **progressive disclosure**:

**Level 1 — Summary** (default, ~15 lines):
Read and present the summary template for the chosen domain:

- `templates/architecture/summary.md`
- `templates/api/summary.md`
- `templates/data/summary.md`

**Level 2 — Patterns** (on request for more detail, ~50 lines):
Read the patterns template with decision guidance and examples:

- `templates/architecture/patterns.md`
- `templates/api/patterns.md`
- `templates/data/patterns.md`

**Level 3 — Full Reference** (on request for complete SOP):
Read the deep reference documents on demand:

- `reference/architecture-patterns.md` + `reference/component-design-guide.md`
- `reference/api-design-guide.md` + `reference/function-design-patterns.md`
- `reference/data-model-guide.md` + `reference/pydantic-patterns.md`

### Step 3: Handle Multiple Domains

If context suggests multiple domains (e.g., new feature with API + data):

- Show summary for each detected domain
- Let user choose which to dive deeper into
- Or use `/design full` for the complete sequence

### Step 4: No Context Detected

If detection returns "unknown" and no explicit mode:

- Show all three summaries as overview
- List available modes for user to choose

## `/design full` Sequence

When running the full design workflow:

1. **Architecture first**: Component boundaries, layers, patterns, DI
2. **Data models second**: Pydantic schemas based on architecture components
3. **API contracts third**: Endpoints and schemas using data models

Output uses `templates/architecture-doc.md` as the final document template.

## Output

Write documents to `docs/architecture/` in the project root:

| Subcommand             | Output Path                                   |
| ---------------------- | --------------------------------------------- |
| `/design architecture` | `docs/architecture/architecture-{feature}.md` |
| `/design api`          | `docs/architecture/api-{feature}.md`          |
| `/design data`         | `docs/architecture/data-{feature}.md`         |
| `/design full`         | `docs/architecture/{feature}.md` (combined)   |

Use `templates/architecture-doc.md` as the document template with sections:

- Overview, Architecture Pattern, Component Design, Data Model, API Specification
- Data Flows, Module Structure, Error Handling, Configuration
- Testing Strategy, Security Considerations, Performance Considerations

Create `docs/architecture/` if it doesn't exist.

## Integration

**Invoked by**: User directly (`/design`), `/story prp` workflow (design phase)
**Invokes**: Nothing directly — produces architecture docs consumed by `prp-generator`
**Connected skills**:

- `/story create` → requirements → `/design` → architecture doc → `/story prp` → PRP
- `/implementation` consumes design output

## Progressive Disclosure Rules

- **Never** load reference/ docs unless user explicitly asks for full SOP or L3 detail
- **Default** to L1 summary — enough to orient and decide
- **L2 patterns** when user asks "how", "what pattern", "show me examples"
- **L3 full** when user asks for "complete guide", "full reference", or specific deep topic
Files in this package (17)
  • SKILL.md 5 KB
  • api-design-guide.md 15 KB
  • architecture-patterns.md 13 KB
  • reference/api-design-guide.md 12 KB
  • reference/architecture-patterns.md 15 KB
  • reference/component-design-guide.md 15 KB
  • reference/data-model-guide.md 14 KB
  • reference/function-design-patterns.md 15 KB
  • reference/pydantic-patterns.md 20 KB
  • reference/schema-examples.py 12 KB
  • templates/architecture-doc.md 13 KB
  • templates/api/patterns.md 3 KB
  • templates/api/summary.md 1 KB
  • templates/architecture/patterns.md 3 KB
  • templates/architecture/summary.md 1 KB
  • templates/data/patterns.md 3 KB
  • templates/data/summary.md 1 KB

Versions

RepositoryScoreLicence
This page · matteocervelli/llms100MIT
cihantopac/markilo100Apache-2.0
NatikChhabra/claude-arsenal100MIT
AtlasScope/agent-kit100MIT
jeremylongshore/tons-of-skills-marketplace100MIT
NathanColosimo/skills100MIT
serpro69/claude-toolbox100Apache-2.0
serpro69/claude-toolbox100Apache-2.0
ouestlabs/audio-ui100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 52c082873362 (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

  • 100api-design
    Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap.
  • 95api-design
    Use for designing REST/GraphQL API contracts before implementing, and for planning breaking-change version transitions (v1→v2, deprecations). No code edits.
  • 100api-design
    Defines REST and GraphQL API contracts including endpoints, request/response schemas, auth flows, and versioning strategy. Use when designing a new API, reviewing an API spec, or when the user mentions API design, OpenAPI, or endpoint contracts.
  • 100pydantic-models-py
    Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation in Python applications using Pydantic v2.
  • 100pydantic-models-py
    Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation ...
  • 100contract-author
    Generate machine-readable integration contracts (API, data layer, shared types, events) before any implementation begins in a multi-agent build or explicitly requested solo contract design. Use when authoring API contracts, OpenAPI specs, AsyncAPI specs, Pydantic models,…

Feedback and reports

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