The Story of How I Achieved Automatic Generation of AWS Architecture Diagrams Using Claude Code's Skill Function

Introduction

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

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

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

In this article, I'll explain why I implemented this as a skill, what challenges I faced and how I solved them, and the philosophy behind skill design.

What is Claude Code's "Skills" Feature?

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 just prompt templates. They can hold multiple reference files, allowing Claude to load large amounts of reference data that wouldn't fit in the context window as needed. This is the crucial difference from "commands."

Why Was a Skill Needed for AWS Architecture Diagrams?

Problem: Incorrect Icons

When asking an LLM to generate AWS diagrams in Draw.io, the icons almost always break. The reason is clear: Draw.io's AWS icons use a proprietary shape naming system (mxgraph.aws4.*), and without knowing the exact shape names, the correct icons won't display.

For example, Amazon Bedrock's icon is mxgraph.aws4.bedrock. While "bedrock" might be easy to guess, AWS Certificate Manager is certificate_manager_3, and CloudWatch is cloudwatch_2, with version numbers commonly appearing in names.

Even more troublesome is the existence of two 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 white glyph.

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

Here, strokeColor=#ffffff is mandatory. Without it, the glyph won't display in white, and the icon collapses. This was the biggest stumbling block.

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

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

These use strokeColor=none. The strokeColor values are opposite in the two patterns, so confusing them guarantees broken icons.

Authoritative Source for Icon Data

Finding the correct shape names was the most critical issue. AWS's official documentation doesn't list Draw.io shape names.

The answer was in Draw.io's source code.

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

Categories and Official Colors

The official colors confirmed from Draw.io's source are:

Mixing these colors between categories contradicts AWS's official design guidelines, so I defined a rule in the skill: "fillColor must strictly correspond to the category."

Skill Structure

The final directory structure of the skill 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 dividing reference files by category. Putting all icon data in a single file would make it too large, but by dividing into categories, Claude can load only the necessary files.

SKILL.md Workflow

The core SKILL.md 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 matters because label length and layout fit differ between Japanese and English.

I also included target audience assessment in the first step. The granularity of labels and edge descriptions differ significantly between diagrams for technicians versus managers.

Step 2: Referencing Icons

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

This rule is most important. "Don't guess, reference." LLMs confidently output incorrect shape names, so I'm forcing it to always read the reference files.

Steps 3-4: Layout → XML Generation

Determine placement according to layout guidelines and build the diagram based on the template XML.

Step 5: Output Two Files

The skill generates not only a .drawio file but also a companion guide (Markdown).

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

File names use kebab-case slugs that represent the diagram's content. Instead of generic names like architecture.drawio, using descriptive names like rag-helpdesk-architecture prevents confusion when there are multiple diagrams.

The companion guide includes:

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

The diagram is for "understanding the overall picture at a glance," while the guide is for "explaining why it's designed this way." Together, they enable viewers to make their own judgments and discussions.

Non-Technical Mode: Step Numbers and Swim Lanes

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

Technically accurate diagrams and diagrams that stakeholders understand are different things. So I added a Non-Technical Audience Mode to the skill.

Numbered Edges

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

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

For multiple flows, different styles of circled numbers are used for visual distinction.

Simplified Labels

The point is to express what is happening in a single phrase. How it's technically implemented isn't the role of this diagram.

Swim Lanes and Flow Overview

For multiple data flows, the lane header includes the overall flow.

Data Processing Flow: ① Get Ticket → ② Store Data → ③ AI Conversion → ④ Indexing

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

The PNG Export Trap

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

The solution is simple: place a light gray (#F5F5F5) rectangle covering the entire diagram in the background.

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

By placing everything—title, swim lanes, legend—inside this background rectangle, you get a readable diagram regardless of export settings.

Skill Design Philosophy

Here are the principles of Claude Code skill design that emerged during the creation of this skill.

1. Don't Let the Model Guess Reference Data

LLMs excel at producing "plausible answers," but this doesn't work for things like Draw.io shape names where being off by even one character makes it completely non-functional. Providing accurate data as reference files and writing "always read this" in the rules was the most important design decision.

2. Extract Mechanically from Authoritative Sources

Manually listing icon data leads to omissions and errors. I used a Python script to mechanically extract from Draw.io repository's Sidebar-AWS4.js. The extraction script itself isn't included in the skill. The skill only needs the extraction results (reference data), and the extraction method is temporary.

3. Write Rules Concretely

Write "use strokeColor=#ffffff" rather than "use icons correctly." Write "icon spacing 80-120px, group padding 30px" rather than "arrange the layout neatly." Only rules with specific values and code snippets are reliably followed by LLMs.

4. Update Skills After Actually Using Them

The skill I initially designed differs greatly from the skill after actually creating diagrams. Non-Technical Audience Mode, PNG export countermeasures, recommendation of a single AWS Cloud group—all these rules were added based on experiences creating diagrams with the skill.

Skills are not one-and-done; they grow through use.

5. Divide Reference Data by Category

Putting all data in one file consumes the context window. By dividing by category, when you want to "create a Lambda diagram," you only need to read aws-icons-compute.md, which is efficient.

How to Use

With the skill placed in your repository, just instruct Claude Code like this:

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

Claude will first ask for your language preference. Then it automatically looks up icons from reference files, follows layout guidelines, and generates two files: a Draw.io file and a companion guide.

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

Summary

I systematized automatic generation of AWS architecture diagrams using Claude Code's skills feature.

The key points were:

1. Mechanically extracting icon data from an authoritative source (Draw.io repository)
2. Organizing into reference files by category, forcing reference rather than guesswork
3. Feeding back experience from actual use into the skill, adding non-technical mode and PNG export countermeasures
4. Generating both diagram and guide to cover both "understand by seeing" and "understand by reading"

Having a diagram with correct icons and a reading guide generated from a single request "Create an architecture diagram"—this experience makes skill design worth the effort.
The skill's source code is available on GitHub. Feel free to customize it for your own projects.