home / skills / nickcrew / claude-cortex / system-design

system-design skill

safe

This skill helps you design system architecture, APIs, and data models with structured workflows, validation, and clear documentation outputs.

npx playbooks add skill nickcrew/claude-cortex --skill system-design

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---
name: system-design
description: Use when designing system architecture, APIs, components, or data models - provides a structured design workflow with validation and documentation outputs.
---

# System Design

## Overview
Create clear system, API, component, or data model designs with explicit requirements, constraints, and validation steps.

## When to Use
- Designing system architecture or components
- Specifying APIs or data models
- Producing design docs or diagrams

Avoid when:
- You only need implementation tasks (use implementation-workflow)

## Quick Reference

| Task | Load reference |
| --- | --- |
| System design workflow | `skills/system-design/references/system.md` |

## Workflow
1. Gather requirements and constraints.
2. Load the system design reference.
3. Define structure, interfaces, and data flows.
4. Validate against constraints and best practices.
5. Deliver spec/diagram/code artifacts.

## Output
- Design spec or diagram
- Validation notes and follow-ups

## Common Mistakes
- Designing without constraints
- Mixing implementation details with spec scope

Overview

This skill helps you design system architecture, APIs, components, and data models using a structured workflow that produces validated specifications and diagrams. It emphasizes clear requirements, explicit constraints, and deliverable artifacts such as specs, interface definitions, and validation notes.

How this skill works

You start by gathering requirements and constraints, then load a compact system-design reference to align scope and standards. The skill defines structure, interfaces, and data flows, runs validation checks against constraints and best practices, and outputs a spec, diagram, and follow-up actions. Validation notes call out trade-offs, risks, and recommended next steps.

When to use it

Designing system architecture or decomposing components
Specifying APIs, interface contracts, or data models
Producing architecture docs, sequence diagrams, or component diagrams
Validating a proposed design against constraints like latency, security, or cost
Preparing handoff artifacts for implementation teams

Best practices

Start with explicit requirements and non-functional constraints before proposing structure
Keep design decisions technology-agnostic at the spec stage; record implementation options separately
Model clear interfaces and data contracts with examples and edge-case behaviors
Run validation checks for scalability, security, cost, and operational concerns
Produce concise diagrams and a one-page summary for stakeholder alignment

Example use cases

Designing a microservices architecture with service boundaries and API contracts
Specifying a REST or gRPC API with request/response schemas and error models
Defining a data model and migration strategy for a new feature
Validating an existing design for compliance with latency and throughput constraints
Creating a handoff package: spec, diagram, validation notes, and next steps

FAQ

Will the skill produce code?

It produces design artifacts and optional scaffold examples, but not full implementation; use an implementation-focused workflow for code tasks.

How does validation work?

Validation checks the design against stated constraints and best practices, highlighting risks, bottlenecks, and suggested mitigations.