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".
- Author
- matteocervelli ↗
- Repository
- llms ↗
- Licence
- MIT
- Last repository change
- 21.05.2026
Assessment and security
- Files in this package
- 17
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
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
- Usage
- Workflow
- /design full Sequence
- Output
- Integration
- Progressive Disclosure Rules
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
| Repository | Score | Licence |
|---|---|---|
| This page · matteocervelli/llms | 100 | MIT |
| cihantopac/markilo | 100 | Apache-2.0 |
| NatikChhabra/claude-arsenal | 100 | MIT |
| AtlasScope/agent-kit | 100 | MIT |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| NathanColosimo/skills | 100 | MIT |
| serpro69/claude-toolbox | 100 | Apache-2.0 |
| serpro69/claude-toolbox | 100 | Apache-2.0 |
| ouestlabs/audio-ui | 100 | MIT |
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,…