Architecture Diagramming Standard skill
Draws architecture diagrams as editable draw.io files with a fixed house style, C4 levels, evidence-tagged shapes, and optional multi-view identity checks.
by HoangNguyen0403·MIT license·★ 569 Stars on the repo·GitHub ↗
Use now
npx degit HoangNguyen0403/agent-skills-standard/.agents/skills/common/common-architecture-diagramming#develop ~/.claude/skills/common-architecture-diagrammingChecked ·commit develop
Files of Architecture Diagramming Standard
SKILL.md
Show the full text93 lines
Architecture Diagramming Standard
Priority: P1 (HIGH)
Pipeline
Never hand-write mxGraph XML. Write a spec; the scripts own every visual decision, so diagrams stay identical across authors, repositories, and sessions.
- Write
spec.json— schema in diagram-spec.md. For an ERD, generate it:python3 scripts/schema_to_spec.py db/schema.sql --title "<System> — ERD" -o spec.json python3 scripts/validate_spec.py spec.jsonpython3 scripts/render_drawio.py spec.json -o docs/architecture/<slug>.drawio --strict(exit 2 = a layout finding; change the spec, per layout-rules.md)- For related views, optionally validate view-manifest.md:
python3 scripts/validate_manifest.py view-manifest.json - Export the image: a draw.io MCP tool if the session has one, else
python3 scripts/export_drawio.py docs/architecture/<slug>.drawio -f png -o docs/architecture/<slug>.png, else ship the.drawioand say the image was not exported. See export paths. - Inspect the exported image at normal reading size; strict validation cannot prove labels and edges are legible. Fix the spec and re-export before handoff.
The JSON spec is the semantic source of truth; .drawio is the editable presentation and the
image is a copy for a deck. Generated XML records its own baseline; regeneration protects
manual edits by default. Use --acknowledge-manual-edits only after returning semantic changes to the spec.
Guidelines
- Name the audience and the decision before drawing anything.
- One C4 level per diagram: context, container, or component, never mixed.
- Pick the type from the message, not from habit. See diagram-selection.md.
- Evidence and confidence are separate. Code citations are documented evidence, not runtime
observations; use
assumedorunverifiedfor honest design uncertainty. - Put the number on the box.
metriccarries the load or SLO that sized the node,constraintsays why it exists; never invent either. - Label every edge with its protocol or event; use
style: asyncfor events. - Cloud icons only where verified.
gcp:*andaws:*are official icons; every other vendor is acloud:*kind with the service named insublabel. No Azure logos exist in the bundle, so Azure is alwayscloud:*. - Exec audience caps at 12 nodes. Past that, split by level or by flow.
- Legend and title block are generated. Do not remove or duplicate them.
- Refine in the spec, not by mutating generated XML. Regeneration preserves files with a valid own baseline, but refuses hand mutation until explicitly acknowledged.
Anti-Patterns
- No hand-written XML: Write the spec, run the renderer.
- No invented boxes: Omit what the evidence does not support.
- No mixed levels: Table columns never appear in a context diagram.
- No unlabeled arrows: State the protocol or the event.
- No mystery acronyms: Expand every abbreviation on first use.
- No orphan nodes: Connect it or cut it.
Red Flags
| Thought | Reality |
|---|---|
| "It is one box, I will write the XML" | The renderer owns style, legend, and title block. Use it. |
| "Close enough, I will guess this service" | Guesses ship as facts. Omit the evidence and let it render UNVERIFIED. |
| "Managers want the whole system on one page" | Past 12 nodes they stop reading. Split it. |
References
- Diagram spec · View manifest · Style catalog · House style
- Source extraction · Exec readability
- C4 model · Cloud · Best practices
- Layout rules · Checklist · Export paths and Mermaid fallback
- Runnable examples:
assets/fixtures/<type>.spec.json, one per diagram type, plus schema samples underassets/fixtures/schemas/. - Batch or delegated drawing:
specialist-solution-diagrammer.
| 1 | |
| 2 | name common-architecture-diagramming |
| 3 | description Draws architecture diagrams as editable draw.io files with a fixed house style, C4 levels, evidence-tagged shapes, and optional multi-view identity checks. Use when producing a system context, container, component, deployment, data flow, sequence, state, or ERD, or redrawing an ASCII or Mermaid one. |
| 4 | metadata |
| 5 | triggers |
| 6 | files |
| 7 | - "ARCHITECTURE.md" |
| 8 | - "**/*.drawio" |
| 9 | - "**/*.mermaid" |
| 10 | - "docs/architecture/**" |
| 11 | keywords |
| 12 | - diagram |
| 13 | - c4 |
| 14 | - drawio |
| 15 | - mermaid |
| 16 | - erd |
| 17 | - entity relationship |
| 18 | - schema diagram |
| 19 | - aws |
| 20 | - architecture diagram |
| 21 | - solution architecture |
| 22 | - system context |
| 23 | - deployment diagram |
| 24 | |
| 25 | # Architecture Diagramming Standard |
| 26 | |
| 27 | ## **Priority: P1 (HIGH)** |
| 28 | |
| 29 | ## Pipeline |
| 30 | |
| 31 | Never hand-write mxGraph XML. Write a spec; the scripts own every visual decision, |
| 32 | so diagrams stay identical across authors, repositories, and sessions. |
| 33 | |
| 34 | Write `spec.json` — schema in [diagram-spec.md]. For an ERD, |
| 35 | generate it: `python3 scripts/schema_to_spec.py db/schema.sql --title "<System> — ERD" -o spec.json` |
| 36 | `python3 scripts/validate_spec.py spec.json` |
| 37 | `python3 scripts/render_drawio.py spec.json -o docs/architecture/<slug>.drawio --strict` |
| 38 | (exit 2 = a layout finding; change the spec, per [layout-rules.md]) |
| 39 | For related views, optionally validate [view-manifest.md]: |
| 40 | `python3 scripts/validate_manifest.py view-manifest.json` |
| 41 | Export the image: a draw.io MCP tool if the session has one, else |
| 42 | `python3 scripts/export_drawio.py docs/architecture/<slug>.drawio -f png -o docs/architecture/<slug>.png`, |
| 43 | else ship the `.drawio` and say the image was not exported. See [export paths]. |
| 44 | Inspect the exported image at normal reading size; strict validation cannot prove labels and edges are legible. Fix the spec and re-export before handoff. |
| 45 | |
| 46 | The JSON spec is the semantic source of truth; `.drawio` is the editable presentation and the |
| 47 | image is a copy for a deck. Generated XML records its own baseline; regeneration protects |
| 48 | manual edits by default. Use `--acknowledge-manual-edits` only after returning semantic changes to the spec. |
| 49 | |
| 50 | ## Guidelines |
| 51 | |
| 52 | **Name the audience and the decision** before drawing anything. |
| 53 | **One C4 level per diagram**: context, container, or component, never mixed. |
| 54 | **Pick the type from the message**, not from habit. See [diagram-selection.md]. |
| 55 | **Evidence and confidence are separate.** Code citations are documented evidence, not runtime |
| 56 | observations; use `assumed` or `unverified` for honest design uncertainty. |
| 57 | **Put the number on the box.** `metric` carries the load or SLO that sized the node, |
| 58 | `constraint` says why it exists; never invent either. |
| 59 | **Label every edge** with its protocol or event; use `style: async` for events. |
| 60 | **Cloud icons only where verified.** `gcp:*` and `aws:*` are official icons; every other |
| 61 | vendor is a `cloud:*` kind with the service named in `sublabel`. No Azure logos exist in |
| 62 | the bundle, so Azure is always `cloud:*`. |
| 63 | **Exec audience caps at 12 nodes.** Past that, split by level or by flow. |
| 64 | **Legend and title block are generated.** Do not remove or duplicate them. |
| 65 | **Refine in the spec, not by mutating generated XML.** Regeneration preserves files with a |
| 66 | valid own baseline, but refuses hand mutation until explicitly acknowledged. |
| 67 | |
| 68 | ## Anti-Patterns |
| 69 | |
| 70 | **No hand-written XML**: Write the spec, run the renderer. |
| 71 | **No invented boxes**: Omit what the evidence does not support. |
| 72 | **No mixed levels**: Table columns never appear in a context diagram. |
| 73 | **No unlabeled arrows**: State the protocol or the event. |
| 74 | **No mystery acronyms**: Expand every abbreviation on first use. |
| 75 | **No orphan nodes**: Connect it or cut it. |
| 76 | |
| 77 | ## Red Flags |
| 78 | |
| 79 | | Thought | Reality | |
| 80 | |---------|---------| |
| 81 | | "It is one box, I will write the XML" | The renderer owns style, legend, and title block. Use it. | |
| 82 | | "Close enough, I will guess this service" | Guesses ship as facts. Omit the evidence and let it render UNVERIFIED. | |
| 83 | | "Managers want the whole system on one page" | Past 12 nodes they stop reading. Split it. | |
| 84 | |
| 85 | ## References |
| 86 | |
| 87 | [Diagram spec] · [View manifest] · [Style catalog] · [House style] |
| 88 | [Source extraction] · [Exec readability] |
| 89 | [C4 model] · [Cloud] · [Best practices] |
| 90 | [Layout rules] · [Checklist] · [Export paths and Mermaid fallback] |
| 91 | Runnable examples: `assets/fixtures/<type>.spec.json`, one per diagram type, plus schema samples under `assets/fixtures/schemas/`. |
| 92 | Batch or delegated drawing: `specialist-solution-diagrammer`. |
| 93 |
Discussion
Alternatives
Diagram designCreate branded architecture, architecture delta, IT current-state, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, radar/spider, polar chart (polar/radial lollipop), loop/flywheel, nested, tree, org chart, layer stack, Venn, pyramid/funnel, treemap and marimekko, heatmap, bar and dumbbell, waterfall, line (slopegraph, ridgeline, streamgraph, bump), Gantt and scatter charts (bubble, beeswarm), high-level, process, medallion, data flow, DP integration, DP security matrix, Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, or database schema diagrams as HTML/SVG/PNG, with .drawio, Mermaid, and .excalidraw import, plus lifecycle phase maps, block decomposition trees, and onboarding guidance.Review architectureReview a PR against the Pascal architectural rules — package boundaries (core/viewer/editor/nodes), the registry-driven composition model (def.geometry / def.renderer / def.system), legacy-dispatch regressions, the slots + world-scale-UV convention for new nodes/geometry, hook hygiene (useEditor/useScene/useViewer), and selector performance. Use when the user asks to review a PR, audit a branch, or check that changes respect the codebase's architecture.Draw.io Architecture StudioCreate and edit draw.io/diagrams.net diagrams as editable `.drawio` files. Covers architecture, UML/ERD/sequence, BPMN, network, and swimlane views authored from a description or converted from code, IaC, SQL, and API schemas, plus sync, query, test, review, export, and publish of existing diagrams. Use when the user asks for draw.io/diagrams.net or an editable diagram; prefer Mermaid/PlantUML when diagrams-as-code is enough.LLM Wiki — Knowledge Distillation PatternThe foundational knowledge distillation pattern for building and maintaining an AI-powered Obsidian wiki. Based on Andrej Karpathy's LLM Wiki architecture. Use this skill whenever the user wants to understand the wiki pattern, set up a new knowledge base, or needs guidance on the three-layer architecture (raw sources → wiki → schema). Also use when discussing knowledge management strategy, wiki structure decisions, or how to organize distilled knowledge. This is the "theory" skill — other skills handle specific operations (ingesting, querying, linting).
Browse more free Claude skills or everything in Development.