mcpbeat

Common Architecture Diagramming

hoangnguyen0403/common-architecture-diagramming

Standards for creating clear, audience-appropriate C4 and UML architecture diagrams with Mermaid. Use when producing system context diagrams, container views, sequence diagrams, or updating ARCHITECTURE.md files.

3k tokens
context cost
the whole folder, loaded on every use
8
files
instructions only
0
copies elsewhere
how many repositories repackaged it
536
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/HoangNguyen0403/agent-skills-standard --skill common-architecture-diagramming

What comes with it

9 977 bytes besides the instruction
evals/evals.json
references/best-practices.md
references/c4-model.md
references/checklist.md
references/cloud-architecture.md
references/diagram-selection.md
references/implementation.md

The instruction itself

6 sections, as written by the author

Architecture Diagramming Standard

Priority: P1 (HIGH)

Guidelines

  • Use C4 Model: Context -> Container -> Component -> Code.
  • Audience-Centric: Tailor abstraction (Execs vs. Devs).
  • Select Type: Sequence (Protocol), ERD (Data), State (Lifecycle), Cloud (Infra). See Selection.
  • Explicit Labels: Label every arrow (e.g., "Uses", "HTTPS").
  • Consistent Notation: Cylinders=DB, Rectangles=Systems, Dashed=Async.
  • Metadata: Title, Date, Version, Author.
  • Legend Mandatory: Define all shapes/colors/styles.
  • Direction: graph LR (Flow) or graph TD (Hierarchy).
  • Deployment: Map containers to infrastructure.
  • Governance: CRITICAL: Review best-practices.md before starting.

Workflow

  • Name audience and the decision the diagram must support.
  • Pick one level: context for external actors, container for deployable systems, component for one container; never mix levels.
  • Pick notation: sequence for a request protocol, ERD for data ownership, state for lifecycle, deployment for infrastructure.
  • Draw only decision-relevant nodes; label every relationship with protocol or event.
  • Add title, scope/date/version, legend, and one review question for the intended audience.

See implementation examples for C4 container diagram in Mermaid.

Anti-Patterns

  • Mixed Levels: DB columns in System Context.
  • Unlabeled Arrows: Ambiguous relations.
  • Mystery Shapes: Undefined in Legend.
  • Dead Ends: Unconnected nodes.
  • Clutter: >20 nodes/diagram.
  • Acronyms: Undefined abbreviations.

References

  • Diagram Selection
  • Cloud Architecture
  • C4 Model Guide
  • Checklist
  • Best Practices

How to use it

Copy the folder

Take hoangnguyen0403/common-architecture-diagramming from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.