Menü
Draw clear, audience-appropriate software architecture diagrams that communicate scope, structure, interfaces, and relationships without mixing abstraction levels.
| name | architecture-diagram-draw |
| description | Draw clear, audience-appropriate software architecture diagrams that communicate scope, structure, interfaces, and relationships without mixing abstraction levels. |
Use this skill to produce software architecture diagrams that are easy to read, accurate enough to support engineering discussion, and scoped to a specific audience and decision.
This skill is for communication first, not for drawing everything that exists. A good architecture diagram should answer a concrete question, at a single abstraction level, with explicit semantics.
Use this skill when the user asks to:
Do not use this skill when the user actually needs:
Always optimize for these outcomes:
Before drawing anything, identify:
If the user does not specify this, infer the most practical audience and state your assumption.
Do not mix business context, service internals, deployment nodes, runtime flow, and data details into one picture unless the user explicitly needs a hybrid view.
Default to a single dominant level per diagram:
Do not try to be comprehensive. Omit details that do not help the target audience answer the central question.
All boxes, colors, borders, arrows, icons, line styles, and group boundaries must have clear semantics.
If semantics are not obvious, add a legend.
Every important relationship should show:
Prefer unidirectional arrows. Avoid ambiguous double-headed arrows unless the user explicitly needs to emphasize two-way communication and you can label both directions clearly.
Use short textual support when the diagram alone may be misread:
Choose a diagram structure that can be updated without pain. Do not create visually impressive but brittle diagrams.
Keep the source editable and make assumptions visible.
Collect or infer the following before drawing:
If information is missing, do not stall unnecessarily. Use this fallback order:
Write one sentence in this form:
This diagram is for [audience] to understand [question / decision].
Examples:
Use this quick mapping:
If the user says “architecture diagram” without specifying, default to:
unless the request clearly points to deployment or runtime behavior.
Clearly identify:
For context diagrams, distinguish between:
Keep only elements necessary for the chosen level.
Good default counts:
If the element list is too long, split the output into multiple diagrams.
Avoid vague names like:
Prefer names that tell the reader what the element is and does.
Examples:
Also include short descriptions when possible.
For each line, define:
Good labels:
Bad labels:
Include technology / protocol labels when they add clarity, such as:
Do not turn the diagram into a tool catalog.
Apply these layout rules:
Every final diagram should have:
Recommended title format:
[Diagram Type] for [System Name]
Examples:
After the diagram, include a short section with:
Run the checklist at the end of this file.
When producing a diagram, use this structure unless the user asks for something else:
A strong output should satisfy all of the following:
One drawing mixes users, services, classes, queues, server nodes, and SQL tables.
Fix: split into separate views.
Trying to include everything “for completeness”.
Fix: optimize for comprehension, not exhaustiveness.
Red boxes, blue boxes, dashed lines, and shaded groups with no legend.
Fix: remove non-semantic styling or explain it.
Names like module, processor, manager, engine, handler, middleware, or system without role clarity.
Fix: rename to concrete responsibilities.
Lines with no direction, no labels, or double-headed arrows hiding two different interactions.
Fix: use single-direction relations and clear labels.
Using a deployment diagram to explain product context, or a component diagram to explain business partners.
Fix: choose the view that matches the question.
Using icons, gradients, logos, or color noise that add visual weight but no information.
Fix: prefer clean, functional visuals.
Forgetting trust boundaries, ownership boundaries, or external interfaces when they are central to the discussion.
Fix: draw and label the relevant boundaries.
The image is shown with no assumptions, no context, and no explanation of what was intentionally omitted.
Fix: add a short textual note.
The output is visually polished but difficult to edit, update, or version.
Fix: prefer source-first representations such as Mermaid, PlantUML, Structurizr DSL, or a clearly structured textual diagram spec.
Omit an element if all of the following are true:
Keep an element if any of the following are true:
Show:
Do not show:
Use when:
Show:
Do not show:
Use when:
Show:
Do not show:
Use when:
Show:
Use when:
Show:
Use when:
When drawing a context-level view, decide whether the user needs:
Focus on:
Prefer labels that read like data or business interactions.
Focus on:
Prefer labels such as HTTPS, gRPC, WebSocket, SMTP, Kafka, S3, VPN, browser, mobile app, batch file, webhook, etc.
If both are important, either:
When the system involves LLMs, agents, tools, memory, orchestrators, or MCP-like capability layers, make sure to separate these concerns clearly:
Common mistake: collapsing “LLM”, “agent”, “orchestrator”, “memory”, and “tools” into one box called AI.
Do not do that.
When the output is for a report, deck, or public-facing explanation:
The diagram should support a story, not just inventory components.
Choose in this order unless the user specifies otherwise:
If the user wants a rendered image, still prefer producing an editable source representation first.
Use this template when replying.
## Goal
[One-sentence goal of the diagram]
## Assumptions
- [...]
## Diagram type
[System Context / Container / Component / Dynamic / Deployment]
## Diagram source
```mermaid
[diagram code]
---
## Final review checklist
Before delivering, verify all items below.
### Goal and audience
- [ ] I know who this diagram is for.
- [ ] I know what question this diagram answers.
- [ ] The chosen diagram type matches that question.
### Scope and abstraction
- [ ] The system in scope is explicit.
- [ ] Out-of-scope items are not accidentally mixed in.
- [ ] The diagram stays at one primary abstraction level.
- [ ] If multiple views are needed, I split them.
### Elements
- [ ] Every important element has a precise name.
- [ ] Important elements have short descriptions where useful.
- [ ] Technology is shown where it adds clarity.
- [ ] Vague buckets were removed or renamed.
### Relationships
- [ ] Every important relationship has direction.
- [ ] Labels are consistent with the direction.
- [ ] Protocols/channels are named when useful.
- [ ] I avoided ambiguous double arrows.
### Visual semantics
- [ ] Colors, borders, line types, and icons have meaning.
- [ ] A legend is included when needed.
- [ ] Layout is readable.
- [ ] Line crossing is minimized.
- [ ] The visual flow is easy to follow.
### Communication quality
- [ ] The diagram can mostly stand on its own.
- [ ] Ambiguities are handled with short text.
- [ ] I stated assumptions.
- [ ] I stated intentional omissions.
- [ ] The result is understandable quickly.
### Maintainability
- [ ] The source format is editable.
- [ ] The diagram is not overfit to this exact moment.
- [ ] Version / date is included if the diagram will be reused.
---
## Compression rule
If the system is too complex for one clean diagram, do not force it.
Compress by using this sequence:
1. remove irrelevant details
2. cluster similar elements
3. split into multiple views
4. move detail into notes/table
5. only then redraw
Never solve complexity by making the diagram denser.
---
## Success criterion
This skill succeeds when the output is not merely “technically correct”, but when a new reader can look at it and quickly answer:
- What is the system?
- What is inside it?
- What is outside it?
- How do the important parts interact?
- What is the main point this diagram is trying to communicate?
A general skill for writing high-quality automated tests. Use it to design and implement stable, maintainable, and diagnosable tests for functions, modules, APIs, components, pages, and critical business workflows.
Add or refine sparse, structured, file-persisted application logs for non-trivial code changes. Use when Agent is proposing an implementation approach, writing a plan, or implementing or modifying complex business logic, critical state transitions, validation or parsing flows, boundary interactions (HTTP, DB, cache, queue, filesystem, subprocess), retries, fallbacks, async jobs, concurrency, or background tasks, because planning is the right time to decide log placement. Reuse the project's existing logging infrastructure whenever possible. Do not use for trivial edits, simple obvious CRUD, blanket "log everything" requests, or low-value noise.
Helps users design, optimize, and review the structure and content of speeches, presentations, and persuasive communication in a wide range of high-stakes scenarios. Applicable situations include, but are not limited to: startup pitches and co-founder recruiting, research presentations and thesis defenses, job talks and academic interviews, product demos and investor pitches, lab meetings and progress updates, public speaking and TEDx-style talks, conference presentations and panel remarks, oral exams and qualifying defenses, expressing viewpoints and persuading others, upward reporting and performance reviews, and internal proposals and solution walkthroughs.
Used for locating, reproducing, validating, and fixing software defects. Applicable when the user asks to "fix a bug," "locate an error," "analyze and fix an error," "reproduce an issue," "find the root cause," and similar scenarios.
Create a structured continuation handoff checkpoint for long coding or technical conversations when context is tight, the user asks to compact, another model will continue the task, or a clean resume point is needed. Preserve exact technical state, decisions, file paths, commands, blockers, failed attempts, validation status, and next steps. Do not use for generic summaries, meeting notes, or polished end-user documentation.
Trigger when the user wants to create a new FastAPI project, add new features, refactor code, or asks about architectural best practices. This skill enforces 2026 clean architecture with SQLModel, Repository Pattern, full async, and production-ready workflow.