The diagrams generated with AI needed 20–30 minutes of manual cleanup. Colored backgrounds on group boxes, broken icons, inconsistent flow direction, edge labels overlapping services. At that point, I might as well have drawn it from scratch.
I wanted a draft I could hand to a client the same day. So I built a skill (a markdown file with rules and reference data) that teaches the AI my specific layout and styling rules. It works in both Claude Code and Kiro CLI. No runtime dependencies, no MCP server.
What was wrong with raw generation
Claude Code and Kiro CLI can produce draw.io XML out of the box. The output opens in draw.io. But "opens" and "looks professional" are different things.
Here's what raw generation actually produces:
Colored backgrounds on groups. AWS Cloud boxes had blue fills, VPC boxes had green fills. Real AWS diagrams use transparent groups with just a border.
Inconsistent flow direction. Sometimes left-to-right, sometimes top-to-bottom, sometimes random. No two diagrams followed the same convention.
Icon pattern confusion. draw.io has two icon patterns with opposite strokeColor rules. In my generations, the AI mixed them up roughly one in four times, producing empty colored squares. The repo calls this out as the single biggest cause of broken icons in AI-generated diagrams.
Edge labels on top of icons. Orthogonal routing with no explicit exit/entry points meant lines went through other services.
No spacing discipline. Icons crammed together with 50px gaps, or scattered across a huge canvas with no rhythm.
Each one is a 30-second fix on its own. Doing all of them on every diagram adds up to that 20–30 minute tax.
The two-pattern rule
draw.io's AWS library (mxgraph.aws4.*) has two icon types that require opposite styling:
Service-level: strokeColor=#ffffff (white, required)
Resource-level: strokeColor=none (required)
Mix these up and you get empty squares or invisible glyphs. The icon names look interchangeable but they're not. I extracted all 270+ names from draw.io's source code (Sidebar-AWS4.js) and documented which pattern each one uses.
Five rounds of refinement
The first version got icons right but layouts were still mediocre. Each round came from opening the generated diagram in draw.io and noting what I'd manually fix, then encoding that fix as a rule.
Round 1: Icons. Extracted 270+ icon names, documented the two patterns, added a "never guess, always look up" rule.
Round 2: Layout. Increased spacing from 150px to 220px horizontal. Added explicit exit/entry points on edges. Removed edge labels that were redundant with icon labels.
Round 3: Edge routing. Changed from rounded=0 to rounded=1 (sharp corners to smooth curves). Added explicit exitX/exitY/entryX/entryY for vertical connections. This stopped lines from routing through other icons.
Rounds 4 and 5 were about restraint and structure. The AI was labeling every edge with obvious things, "Write" on an AWS Lambda to Amazon DynamoDB connection, so I added a "when NOT to label" rule and a 1–2 word cap. Then a title block, a full-canvas background rectangle for clean PNG export, and an audience-mode toggle (technical vs non-technical) to control detail level.
After five rounds, the skill enforces: left-to-right flow with 220px+ horizontal spacing, no colored backgrounds on any group container, verified icon names only (from 8 category reference files), and explicit edge routing so lines don't cross icons.
Example output
"Create an event-driven order processing architecture with Amazon SQS, AWS Lambda, Amazon DynamoDB, and Amazon EventBridge"
"Create a real-time IoT analytics pipeline with Amazon Kinesis, AWS Lambda, Amazon S3 data lake, and Amazon DynamoDB"
"Create a 3-tier web application with Amazon CloudFront, Application Load Balancer, Amazon ECS on AWS Fargate, Amazon Aurora, and Amazon ElastiCache"
Icons render. Flow is left-to-right. No colored backgrounds, no overlapping edges. I can adjust these in under 5 minutes instead of 30.
Install
Claude Code:
/plugin marketplace add vidanov/aws-architecture-diagram-skill
/plugin install aws-architecture-diagram@vidanov-skills
Kiro CLI:
mkdir -p ~/.kiro/skills/aws-architecture-diagram
cp kiro/SKILL.md ~/.kiro/skills/aws-architecture-diagram/SKILL.md
cp -r references ~/.kiro/skills/aws-architecture-diagram/references
Once installed, try this prompt to verify it works:
"Create a serverless API with Amazon API Gateway, AWS Lambda, and Amazon DynamoDB"
You should get a clean left-to-right diagram with correct icons and no colored backgrounds.
What's next
The current output is good. Not perfect. I still adjust things manually. The next step is multiple diagram styles for the same architecture: a technical view for engineers, a simplified view for business stakeholders. Same system, different audience, different drawing.
Try it on your next architecture review. If the generated diagram needs fixes I haven't covered, open an issue. The skill improves from real usage, not theory.
The project was built with Kiro CLI.
