How do I install the Common Architecture Diagramming skill?

Run npx skillmds@latest add hoangnguyen0403/common-architecture-diagramming-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Common Architecture Diagramming safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Common Architecture Diagramming?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Common Architecture Diagramming free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Common Architecture Diagramming?

HoangNguyen0403 (@hoangnguyen0403) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Common Architecture Diagramming by hoangnguyen0403

Name: Common Architecture Diagramming
Author: HoangNguyen0403

Common Architecture Diagramming

Draw architecture diagrams as editable draw.io files with a fixed house style, C4 levels, and evidence-tagged shapes. Use when producing a system context, container, deployment, data flow, sequence, or state diagram, or redrawing an ASCII or Mermaid one.

HoangNguyen0403 Updated Sep 21, 2026 542 repo stars

File contents

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.json
python3 scripts/render_drawio.py spec.json -o docs/architecture/<slug>.drawio --strict (exit 2 = a layout finding; change the spec, per layout-rules.md)
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 .drawio and say the image was not exported. See export paths.

Commit the .drawio as the source of truth; the image is a copy for a deck.

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 per node as path:line. A node with no evidence renders dashed and marked UNVERIFIED — leave the flag showing rather than asserting a guess.
Put the number on the box. metric carries the load or SLO that sized the node, constraint says why it exists; never invent either.
Label every edge with its protocol or event; use style: async for events.
Cloud icons only where verified. gcp:* and aws:* are official icons; every other vendor is a cloud:* kind with the service named in sublabel. No Azure logos exist in the bundle, so Azure is always cloud:*.
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 draw.io, not in XML. Re-running the renderer overwrites layout tweaks.

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 · 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 under assets/fixtures/schemas/.
Batch or delegated drawing: specialist-solution-diagrammer.

---name: common-architecture-diagramming-2description: Draw architecture diagrams as editable draw.io files with a fixed house style, C4 levels, and evidence-tagged shapes. Use when producing a system context, container, deployment, data flow, sequence, or state diagram, or redrawing an ASCII or Mermaid one.---# Architecture Diagramming Standard## **Priority: P1 (HIGH)**## PipelineNever hand-write mxGraph XML. Write a spec; the scripts own every visual decision,so diagrams stay identical across authors, repositories, and sessions.1. Write `spec.json` — schema in [diagram-spec.md](references/diagram-spec.md). For an ERD, generate it: `python3 scripts/schema_to_spec.py db/schema.sql --title "<System> — ERD" -o spec.json`2. `python3 scripts/validate_spec.py spec.json`3. `python3 scripts/render_drawio.py spec.json -o docs/architecture/<slug>.drawio --strict` (exit 2 = a layout finding; change the spec, per [layout-rules.md](references/layout-rules.md))4. 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 `.drawio` and say the image was not exported. See [export paths](references/mermaid-fallback.md).Commit the `.drawio` as the source of truth; the image is a copy for a deck.## 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](references/diagram-selection.md).- **Evidence per node** as `path:line`. A node with no evidence renders dashed and marked UNVERIFIED — leave the flag showing rather than asserting a guess.- **Put the number on the box.** `metric` carries the load or SLO that sized the node, `constraint` says why it exists; never invent either.- **Label every edge** with its protocol or event; use `style: async` for events.- **Cloud icons only where verified.** `gcp:*` and `aws:*` are official icons; every other vendor is a `cloud:*` kind with the service named in `sublabel`. No Azure logos exist in the bundle, so Azure is always `cloud:*`.- **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 draw.io, not in XML.** Re-running the renderer overwrites layout tweaks.## 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](references/diagram-spec.md) · [Style catalog](references/style-catalog.md) · [House style](references/house-style.md)- [Source extraction](references/source-extraction.md) · [Exec readability](references/exec-readability.md)- [C4 model](references/c4-model.md) · [Cloud](references/cloud-architecture.md) · [Best practices](references/best-practices.md)- [Layout rules](references/layout-rules.md) · [Checklist](references/checklist.md) · [Export paths and Mermaid fallback](references/mermaid-fallback.md)- Runnable examples: `assets/fixtures/<type>.spec.json`, one per diagram type, plus schema samples under `assets/fixtures/schemas/`.- Batch or delegated drawing: `specialist-solution-diagrammer`.

Frequently asked questions