Architecture Design

What it does

When your agent uses it

• Needs to design
• Evaluate system architecture — service boundaries
• Infrastructure topology
• Database selection

Example prompts

• “design the system”
• “how should I architect this”
• “monolith vs microservices”
• “/architecture-design”

Workflow steps

10 steps, taken from the first numbered list in SKILL.md.

1. 1Gather requirements — Identify functional requirements (use cases), non-functional requirements (latency, throughput, availability…
2. 2Run architecture assessment — Analyze the existing project structure to detect current patterns (MVC, layered, hexagonal, microservices…
3. 3Analyze dependencies — Examine the dependency tree for circular dependencies, coupling scores, and outdated packages across npm, Python…
4. 4Select architecture pattern — Use the decision workflows below to match team size, deployment needs, and data boundaries to the right…
5. 5Select database — Match data characteristics, scale requirements, and consistency needs to the appropriate database technology using the…
6. 6Design data model — Produce an ER diagram in Mermaid. Define entity ownership: which module/service writes, others read via API.
7. 7Define API contracts — Specify key endpoints with method, path, request/response shapes, and error codes. Version from day one.
8. 8Generate architecture diagram — Produce a Mermaid C4 or flowchart diagram showing components, data stores, external services, and…
9. 9Write ADRs — Document key decisions using the ADR format below.
10. 10Identify risks — Call out single points of failure, data consistency risks, and scaling bottlenecks with mitigations.

What it can do on your machine

Read from SKILL.md and the folder at commit 4ad31b4. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • firebase

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use firebase, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Architecture Design loads about 2.1k tokens when it runs. Until then it costs about 83 tokens; SKILL.md has 790 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~83

When it runs · the whole SKILL.md, loaded when a task matches

~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from shawnpang/startup-founder-skills at commit 4ad31b4, republished under its MIT licence (© shawnpang). 790 words, ~2,115 tokens.

name

architecture-design

description

When the user needs to design or evaluate system architecture — service boundaries, data models, API contracts, infrastructure topology, database selection, or dependency analysis. Also activate for "design the system", "how should I architect this", "monolith vs microservices", or architecture decision records.

related

tech-stack-eval, security-review, code-review

reads

startup-context

Given your team of 3 and early stage, I recommend a modular monolith.
Domain modules:

1. Auth Module — user accounts, roles, sessions
2. Projects Module — workspaces, projects, permissions
3. Tasks Module — tasks, assignments, comments, activity log
4. Notifications Module — email digests, in-app notifications

Each module gets its own DB schema (auth.*, projects.*) and communicates
through internal function calls with typed interfaces — not HTTP. This
gives you service-like boundaries without deployment complexity.

Architecture Assessment:
  Detected pattern: Layered Architecture (confidence: 85%)
  ✓ controllers/  - Presentation layer
  ✓ services/     - Business logic layer
  ✓ repositories/ - Data access layer

## ADR-001: Use WebSockets for Real-Time Collaboration
- Status: Proposed
- Context: Document editor needs sub-200ms latency for cursor positions
  and concurrent edits across 2-50 users per document.
- Decision: WebSockets via Socket.io with Redis pub/sub for horizontal
  scaling. SSE only supports server-to-client; we need bidirectional
  communication for operational transforms.
- Consequences: Adds WebSocket infrastructure (sticky sessions or Redis
  adapter), ~2KB memory per connection. Team needs OT/CRDT knowledge.
- Alternatives: SSE + POST (simpler but higher edit latency),
  Firebase Realtime DB (vendor lock-in, cost at scale).

© shawnpang, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/architecture-design of shawnpang/startup-founder-skills.

Open the folder on GitHubat commit 4ad31b4