Architecture diagrams

Skill sananthanarayan/skilldrop/skills/architecture-diagrams

Generate architecture diagrams (Mermaid, PlantUML, C4) from a written description of a system. Supports AWS/Azure/GCP cloud topologies, microservice landscapes, sequence flows, container diagrams, and ER models. Use whenever the user asks for an architecture diagram, system sketch, flow diagram, or visualization of a design.From its SKILL.md

Install

npx -y skills add sananthanarayan/skilldrop --skill architecture-diagrams

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.3 KB, as published. Nobody here has run it

architecture-diagrams

You help the user turn a written system description into a clean, renderable architecture diagram.

How to respond

Clarify only what blocks correctness. Before drawing, you may ask 1–2 short questions if the description is missing something load-bearing (e.g., "Is auth synchronous or via a sidecar?"). Don't pepper the user with questions for taste preferences — pick a reasonable default and call it out.

Pick the right notation. Use this rough mapping unless the user requests otherwise:

User's intent	Use
Cloud architecture (AWS/Azure/GCP) — boxes, arrows, services	Mermaid `flowchart` or `graph`
Request flow across services / call order matters	Mermaid `sequenceDiagram`
Strategic / multi-level view (context → container → component)	C4 (PlantUML !include c4)
Data model, tables, relationships	Mermaid `erDiagram`
State machine / workflow	Mermaid `stateDiagram-v2`
Class / type hierarchy	Mermaid `classDiagram`
Looks-pretty UML-style for slides	PlantUML

Output the diagram in a fenced code block with the correct language tag (```mermaid, ```plantuml). Then add 2–4 bullet points underneath explaining the key design choices ("Why two ECS services and not one?") so the diagram is reviewable, not just renderable.
Offer next steps, e.g., "Want me to export this as SVG via the Mermaid CLI?" or "Want me to push this into a Figma file? (use the figma-diagrams skill)".

Useful references in this skill

When you need a starting shape, copy from one of the templates rather than inventing notation from scratch — it cuts down on syntax errors and keeps style consistent across diagrams.

templates/mermaid-flowchart.md — basic boxes-and-arrows starter
templates/mermaid-sequence.md — sequenceDiagram with actors and async messages
templates/mermaid-aws.md — AWS-flavoured flowchart using emojis as service icons
templates/c4-container.puml — C4 container diagram skeleton (PlantUML)

Worked examples to learn from:

examples/aws-three-tier.md — three-tier web app on AWS, Mermaid flowchart
examples/microservices-sequence.md — order-placement flow across 4 services
examples/c4-container-saas.md — SaaS app, C4 container level

Quality bar

A good diagram from this skill should:

Fit on one screen. If you have more than ~15 nodes, split into two diagrams (e.g., "Context" and "Container") rather than cramming everything in.
Show direction of data flow, not just connections. Arrows should mean something.
Label every arrow that crosses a trust boundary or a network hop.
Use subgraphs / groups to make zones explicit (VPC, public/private subnets, account boundaries, on-prem vs cloud).
Be valid syntax. Mentally trace through the Mermaid/PlantUML once before responding. Common breakers: unescaped ( ) < > inside labels, missing end for subgraphs, mixing graph types.

What this skill does NOT do

It doesn't render to PNG/SVG itself. To render, suggest the user use the Mermaid Live Editor (https://mermaid.live), the Mermaid CLI (mmdc), or the VS Code Mermaid preview.
It doesn't push to Figma directly. For that, hand off to the figma-diagrams skill.
It doesn't generate Visio/Lucid native files.

Anti-patterns to avoid

❌ Inventing service names ("ServiceA", "ServiceB"). Use the user's vocabulary or ask.
❌ Putting every box at the top level. Group by concern.
❌ Mermaid flowchart with 30+ nodes — split it.
❌ Using a sequence diagram when the user asked "what does the system look like" — that's a structural question, use a flowchart or C4.