Skip to content

Skills · solution-architect

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.

Pack solution-architectTier standardJob Design the systemv0.1.0

npx skilldrop-cli install architecture-diagrams
Other ways to install

With the sibling skills it hands off to:

npx skilldrop-cli install architecture-diagrams --with-related

The whole pack it belongs to:

npx skilldrop-cli install --pack solution-architect

By hand, from a clone of the repo:

cp -R packs/solution-architect/skills/architecture-diagrams ~/.claude/skills/

In Claude Code, with the solution-architect plugin installed, invoke it as:

/solution-architect:architecture-diagrams

Try it

A realistic prompt from the skill's acceptance evals:

Draw the architecture for a checkout service: an API gateway, an orders service, a payments service calling Stripe, and a Postgres primary with a read replica.

What a good result looks like

Example output

Example: Three-tier web app on AWS · the skill's own worked example, source

Worked example

Prompt the user gave: "Draw me a three-tier web app on AWS with an ALB, two ECS services (web + worker), and an RDS Postgres backend."

Response:

flowchart TB
    Internet([🌐 Internet])

    subgraph AWS["☁️ AWS us-east-1"]
        subgraph VPC["🛡️ VPC 10.0.0.0/16"]
            subgraph PubSub["Public subnet"]
                ALB[🔀 Application Load Balancer]
            end
            subgraph PrivSub["Private subnet"]
                Web[📦 ECS web service]
                Worker[📦 ECS worker service]
            end
            subgraph DataSub["Data subnet"]
                RDS[(🐘 RDS Postgres Multi-AZ)]
            end
        end
        SQS{{📨 SQS jobs}}
        S3[(🪣 S3 user uploads)]
    end

    Internet -->|HTTPS 443| ALB
    ALB -->|HTTP 8080| Web
    Web -->|SQL| RDS
    Web -->|enqueue| SQS
    Worker -->|dequeue| SQS
    Worker -->|SQL| RDS
    Web -.signed URLs.-> S3

Design notes:

  • Why two ECS services and not one? Long-running background work (image resize, email, exports) needs its own scaling profile and shouldn't share CPU with request-serving containers.
  • RDS Multi-AZ for automatic failover — single-AZ is fine for dev/test but rarely acceptable in production for a three-tier app.
  • Uploads bypass the API via S3 pre-signed URLs to avoid a 100 MB file streaming through ECS containers.
  • No NAT gateway shown — add one (or VPC endpoints) if the private subnet containers need to reach S3/SQS over the AWS network without a public IP.

Want to extend? Common follow-ups: add CloudFront in front of ALB, add ElastiCache Redis for sessions, add WAF rules, split into multi-region active/passive.

How it's checked

Measured against plain Claude Code (2026-10-23): it met 89% of its checks, against 58% without it, and a blind judge preferred it. How skills are checked

18 assertions across 3 acceptance evals, and 8 trigger queries. Every skill's checks

What the output must do
  • The diagram fits on one screen; beyond roughly 15 nodes it is split into separate Context and Container diagrams rather than crammed
  • Arrows show direction of data flow, not undirected connections
  • Every arrow crossing a trust boundary is labelled
  • The diagram is generated from the written description provided — no components are invented beyond it
  • A named format is produced (Mermaid, PlantUML, or C4) and renders as valid syntax
  • telemetry-diagram.md is saved and contains a single Mermaid diagram with valid-looking syntax and no more than about 20 boxes
  • The diagram visibly separates the operations network, corporate IT and the cloud
  • Includes the described components: PLCs, cellular gateways, MQTT broker, SCADA servers and HMI, historian, data diode, and cloud analytics with dashboards
  • Flags that setpoint recommendations flowing from the cloud back to SCADA contradict the one-way data diode, and does not draw that return path as if it were consistent
  • Does not state 37 stations as fact without noting that the regional table adds up to 41
  • Does not draw the decommissioned Fenwick radio link
  • Does not add components that are not in the description (for example firewalls, VPNs or extra message queues) unless marked as assumptions
  • Delivers a diagram (for example Mermaid or similar renderable text) without first asking questions
  • Shows the steps in the stated order: website order form, spreadsheet, owner's 7am check and text to the kitchen manager, printed and pinned on the kitchen board
  • Does not add steps, systems or people not in the message (for example payment, invoicing, delivery drivers, a CRM)
  • Labels use plain words that new catering staff would understand, with no technical jargon
  • Simple enough for one slide: no more than about 8 boxes
  • Tells the user briefly how to turn the diagram into an image they can put on a slide
When it should and shouldn't activate

Should activate:

  • Draw an architecture diagram for this system
  • Generate a Mermaid diagram of these services
  • Create a C4 container diagram from this description
  • Diagram the sequence flow I just described

Should leave to another skill:

  • Reverse-engineer the architecture from our Terraform and repo
  • Read the frames in our Figma file
  • Threat model this design
  • Write the design doc for this system

Hands off to

Source

SKILL.md · the whole folder on GitHub.