I Built AWS Architecture Diagram Auto-Generation 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?

Using Claude Code's Skills feature, I created aws-architecture-diagram, which automatically generates AWS architecture diagrams.

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

In this article, I'll write about why I chose the skill format, what challenges I faced and how I solved them, and the philosophy behind skill design.

What are Claude Code "Skills"?

Claude Code has a skills feature that lets you give 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 can load large amounts of reference data that wouldn't fit in a context window, on demand. This is the decisive difference from "commands."

Why did AWS architecture diagrams need a skill?

Problem: Icons are incorrect

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

For example, the Amazon Bedrock icon is mxgraph.aws4.bedrock. You might be able to guess "bedrock" in some cases, but AWS Certificate Manager is certificate_manager_3 and CloudWatch is cloudwatch_2 — version-numbered names are commonplace.

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

Two icon patterns

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

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

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

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

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

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

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

The authoritative source for icon data

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

The answer was in the Draw.io source code.

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

Categories and official colors

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

Since mixing these colors across categories violates AWS's official design guidelines, I defined a skill rule to "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 reference files by category. Consolidating all icon data into a single file would make it too large, but by dividing it into categories, Claude can load only the files it needs.

The 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 confirms the language first. This is because label length and layout fit differ between Japanese and English.

I also included audience assessment as the first step. The granularity of labels and edge descriptions differ significantly between technical audiences and manager 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 that reference files must always be read.

Steps 3–4: Layout → XML generation

Following the layout guidelines to determine placement, the diagram is assembled based on the template XML.

Step 5: Output two files

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

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

File names use a kebab-case slug that describes the diagram's content. Rather than generic names like architecture.drawio, using descriptive names 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 such as why serverless, why this DB, etc.
• Cost and 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, people who see the diagram can make judgments and have discussions on their own.

Non-technical audience mode: Step numbers and swimlanes

The first challenge I encountered after actually starting to use the skill was, "This diagram doesn't communicate to anyone outside engineering."

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

Step-numbered edges

Instead of technical labels (HTTPS, REST API, etc.), numbered circles 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.

Swimlanes and flow summary

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

Data processing flow: ① Get ticket → ② Save data → ③ AI conversion → ④ Indexing

Readers can grasp the big picture just by reading the lane header, and check the details within the diagram — a two-level information design.

The PNG export trap

When you export a diagram to PNG from Draw.io, areas outside groups or containers become a black background. If you've placed legends or titles outside the group, they will appear on top of a black background in the exported PNG, making them very difficult to read.

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

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

By containing everything — title, swimlanes, legend — within this background rectangle, you get a readable diagram with any export setting.

Philosophy of skill design

Here is a summary of the principles of Claude Code skill design that became clear through the process of creating this skill.

1. Don't let the LLM guess reference data

LLMs are good at producing "plausible-sounding answers," but this doesn't work for things like Draw.io shape names where even a single character error makes it completely non-functional. 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. Mechanically extract from authoritative sources

Manually listing icon data leads to omissions and errors. This time, I mechanically extracted data from 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 "organize the layout," but "icon spacing is 80-120px, group padding is 30px." Only rules with specific numerical values or code snippets will be reliably followed by an LLM.

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, PNG export countermeasures, the recommendation for a single AWS Cloud group — all of these are rules added from the experience of creating diagrams using the skill.

A skill isn't something you create once and leave; it's something you grow while using it.

5. Split reference data by category

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

How to use it

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

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

Claude will first ask about the 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      — Reading guide for the diagram

Summary

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

The key points were as follows.

1. Mechanically extract icon data from an authoritative source (the Draw.io repository)
2. Organize the data as reference files by category, enforcing lookup rather than guessing
3. Feed experience from actual use back into the skill, adding non-technical audience mode and PNG export countermeasures
4. Generate not just diagrams but guides too, covering both "understandable by looking" and "understandable by reading"

A single phrase like "create an architecture diagram" produces a diagram with correct icons and a reading guide as a set — this experience makes it worth the effort to put into skill design.
The skill source code is publicly available on GitHub. Please try customizing it to fit your own project.