I built a system to automatically generate AWS architecture diagrams using Claude Code's skills feature

Introduction

"Create an AWS architecture diagram" — wouldn't it be convenient if a single phrase like this could generate a Draw.io file with the correct icons, correct colors, and correct layout?

I created aws-architecture-diagram using Claude Code's Skills feature to automatically generate AWS architecture diagrams.

https://github.com/oharu121/oharu-commands-skills-gems/tree/main/skills/aws-architecture-diagram

This article covers why I chose to build this as a skill, what problems I solved and how, and the philosophy behind skill design.

What Are Claude Code "Skills"?

Claude Code has a skills feature that gives Claude specialized knowledge for specific tasks by placing definition files in the .claude/skills/ directory.

.claude/skills/<skill-name>/
├── SKILL.md          # Workflow definition
├── references/       # Reference data
└── templates/        # Templates

Skills are not mere prompt templates. Because they can hold multiple reference files, they allow large amounts of reference data that wouldn't fit in a context window to be loaded on demand. This is the decisive difference from "commands."

Why Did AWS Architecture Diagrams Need a Skill?

The Problem: Incorrect Icons

When you ask an LLM to generate an AWS architecture diagram in Draw.io, the icons are almost certainly going to break. The reason is clear: Draw.io's AWS icons use a proprietary shape name system called mxgraph.aws4.*, and without knowing the exact shape names, the correct icons won't display.

For example, the Amazon Bedrock icon is mxgraph.aws4.bedrock. You might guess "bedrock" in some cases, but AWS Certificate Manager is certificate_manager_3, CloudWatch is cloudwatch_2 — names with version numbers are commonplace.

What makes it even trickier is the existence of two types of icon patterns.

Two Icon Patterns

Draw.io's AWS icons come in two patterns: service-level icons (resourceIcon) and resource-level icons (dedicated shape).

Service-level icons (resourceIcon) are the familiar icons with a colored background and a white glyph on top.

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;
fillColor=#ED7100;strokeColor=#ffffff;

Here, strokeColor=#ffffff is required. Forgetting it causes the glyph to not display in white, breaking the icon. This was the biggest pitfall.

Resource-level icons (dedicated shape) are individual silhouette-style shapes.

shape=mxgraph.aws4.lambda_function;
fillColor=#ED7100;strokeColor=none;

For these, it's strokeColor=none. Since the strokeColor values are opposite for the two patterns, mixing them up will reliably break icons.

The Authoritative Source for Icon Data

The most critical issue was where to get the correct shape names. AWS's official documentation does not list shape names for Draw.io.

The answer was in the Draw.io source code.

In the jgraph/drawio repository, the file src/main/webapp/js/diagramly/sidebar/Sidebar-AWS4.js (approximately 234KB, over 2500 lines) contains the palette definitions for all AWS icons. I extracted the shape names and display names for every category and every icon from this file.

Categories and Official Colors

The official colors confirmed from the Draw.io source are as follows:

Since mixing colors across categories violates AWS's official design guidelines, I defined a rule in the skill: "strictly match fillColor to its category."

Skill Structure

The final skill directory structure looks like this:

.claude/skills/aws-architecture-diagram/
├── SKILL.md                              # Workflow definition (5 steps + 12 rules)
├── references/
│   ├── aws-icons-compute.md              # Compute & Containers (41 icons)
│   ├── aws-icons-storage-database.md     # Storage & Database (38 icons)
│   ├── aws-icons-networking.md           # Networking & CDN (68 icons)
│   ├── aws-icons-app-integration.md      # App Integration & Mgmt (52 icons)
│   ├── aws-icons-analytics-ml.md         # Analytics & AI/ML (70 icons)
│   ├── aws-icons-security.md             # Security (61 icons)
│   ├── aws-icons-common.md               # General resources, Groups, Arrows
│   └── layout-guidelines.md              # Layout rules
└── templates/
    └── base.drawio.xml                   # Minimal Draw.io skeleton

The key point is splitting the reference files by category. Combining all icon data into one file would make it enormous, but by splitting it into categories, Claude only needs to load the files it actually needs.

SKILL.md Workflow

SKILL.md, the core of the skill, defines a 5-step workflow.

Step 1: Understanding and Confirming the Request

- Identify which AWS services are needed
- Determine the architecture pattern
- **Assess the audience**: technical vs non-technical
- **Ask the user** for language preference (English or 日本語)

The skill first confirms the language. This is because label length and layout fit differ between Japanese and English.

I also included audience assessment in the first step. The level of label detail and edge descriptions differ significantly between technical and managerial audiences.

Step 2: Looking Up Icons

**CRITICAL**: Always look up icons before generating XML. Never guess icon names.

This rule is the most important. "Don't guess — look it up." Because LLMs confidently output incorrect shape names, I enforce reading the reference files without exception.

Steps 3–4: Layout → XML Generation

Placement is determined according to layout guidelines, and the diagram is assembled based on the template XML.

Step 5: Output Two Files

The skill generates not just a .drawio file, but also a companion guide (Markdown) alongside it.

docs/
├── rag-helpdesk-architecture.drawio   # Draw.io diagram
└── rag-helpdesk-architecture.md       # Reading guide

File names use a kebab-case slug that describes the diagram's content. Rather than a generic name like architecture.drawio, using a descriptive name like rag-helpdesk-architecture prevents confusion when there are multiple diagrams.

The companion guide includes the following:

• Overview: What this architecture does (1-2 sentences)
• Component list: The role of each AWS service and the reason it was chosen
• Data flow explanation: Detailed descriptions corresponding to the step numbers in the diagram
• Design decisions: Supplementary notes on why serverless, why this DB, etc.
• Cost & scaling notes (optional): Useful information for planning

The diagram is for "conveying the big picture at a glance," while the guide is for "explaining why things are the way they are." Together as a set, they enable people who see the diagram to make judgments and hold discussions on their own.

Non-Technical Mode: Step Numbers and Swim Lanes

The first challenge I hit when actually using the skill was: "This diagram doesn't communicate to non-engineers."

A technically accurate diagram and a diagram that communicates to stakeholders are two different things. So I added a Non-Technical Audience Mode to the skill.

Step-Numbered Edges

Instead of technical labels (HTTPS, REST API, etc.), circled numbers indicate the order of flow.

• Flow A: ① → ② → ③ → ④ (white circled numbers)
• Flow B: ❶ → ❷ → ❸ → ❹ (black circled numbers)

When there are multiple flows, different styles of circled numbers are used to visually distinguish them.

Simplified Labels

The key is to express what is being done in a single phrase. How it is technically implemented is not the role of this diagram.

Swim Lanes and Flow Summaries

When there are multiple data flows, the overall flow is described in the lane headers.

Data processing flow: ① Retrieve ticket → ② Store data → ③ Convert for AI → ④ Index

Readers can grasp the big picture just by reading the lane headers, then check the details in the diagram — a two-level information design.

The PNG Export Trap

When exporting a Draw.io diagram as PNG, areas outside groups or containers get a black background. If you've placed legends or titles outside a group, they end up sitting on a black background in the exported PNG, making it very hard to read.

The solution is simple: place a light gray (#F5F5F5) rectangle covering the entire diagram at the very back.

rounded=1;whiteSpace=wrap;fillColor=#F5F5F5;strokeColor=#E0E0E0;arcSize=2;

By keeping the title, swim lanes, and legend all within this background rectangle, you get a readable diagram no matter what export settings you use.

Skill Design Philosophy

Here I summarize the principles of Claude Code skill design that became clear through the process of building this skill.

1. Don't Let the LLM Guess Reference Data

LLMs are good at producing "plausible-sounding answers," but that doesn't work for things like Draw.io shape names where a single wrong character means nothing works at all. Prepare accurate data as reference files and write in the rules that they must always be read. This was the most important design decision.

2. Extract Mechanically from Authoritative Sources

Manually listing icon data leads to omissions and errors. In this case, I extracted data mechanically from the Draw.io repository's Sidebar-AWS4.js using a Python script. The extraction script itself is not included in the skill. What the skill needs is only the extraction results (reference data); the extraction method is temporary.

3. Write Rules Specifically

Not "use icons correctly" but "use strokeColor=#ffffff." Not "keep the layout tidy" but "icon spacing is 80-120px, group padding is 30px." Only rules that include specific numbers or code snippets are reliably followed by LLMs.

4. Update the Skill After Actually Using It

The skill I designed initially and the skill after actually creating diagrams with it are very different. Non-Technical Audience Mode, the PNG export fix, the recommendation for a single AWS Cloud group — all of these were rules added from the experience of using the skill to create diagrams.

A skill is not something you build once and finish; it's something you grow by using it.

5. Split Reference Data by Category

Putting all data in one file strains the context window. By splitting into categories, when you want to "create a diagram with Lambda," you only need to read aws-icons-compute.md, which is efficient.

How to Use

With the skill placed in your repository, simply instruct Claude Code as follows:

Create an architecture diagram for a RAG system.
Use Bedrock, OpenSearch, Lambda, S3, and API Gateway.
Make it easy to understand for non-technical people.

Claude will first ask about language. After that, it will automatically look up icons from the reference files and generate two files — a Draw.io file and a companion guide — following the layout guidelines.

✅ docs/rag-helpdesk-architecture.drawio  — Open in Draw.io to review
✅ docs/rag-helpdesk-architecture.md      — Guide for reading the diagram

Summary

Using Claude Code's skills feature, I systematized the automatic generation of AWS architecture diagrams.

The key points were:

1. Mechanically extracting icon data from an authoritative source (the Draw.io repository)
2. Organizing it by category as reference files, forcing lookup rather than guessing
3. Feeding experience from actual use back into the skill, adding non-technical audience mode and PNG export fixes
4. Generating not just the diagram but also a guide, covering both "understandable at a glance" and "understandable when read"

A single phrase — "create an architecture diagram" — produces a correctly-iconned diagram paired with a reading guide. This experience makes it worth the effort to invest in skill design.
The skill's source code is publicly available on GitHub. Feel free to customize it to fit your own project.