I tried creating a "GCP Architecture Diagram Skill" with Claude Code — The fundamental differences in icon formats revealed through porting an AWS skill

Introduction

I previously created a custom skill for Claude Code that automatically generates AWS architecture diagrams in Draw.io format. It's a skill where you simply say "draw an AWS architecture diagram" and a .drawio file with accurate icons is output.

Since the AWS version was convenient, I decided to "build the same thing for GCP as well."

To get straight to the point: GCP's Draw.io icons work fundamentally differently from AWS icons, and a simple port won't cut it. While AWS icons only need a single line of shape reference, GCP icons use a method where Base64-encoded SVG data is embedded inline in the style attribute. I'll explain how I dealt with this difference.

Background: How the AWS Skill Works

First, let me briefly explain how the existing AWS skill operates.

Directory Structure

.claude/skills/aws-architecture-diagram/
├── SKILL.md                    # Main instruction file
├── references/
│   ├── aws-icons-compute.md    # Icon definitions for EC2, Lambda, ECS, etc.
│   ├── aws-icons-networking.md # VPC, CloudFront, Route 53, etc.
│   ├── layout-guidelines.md    # Layout rules
│   └── ...（7 files）
└── templates/
    └── base.drawio.xml         # Draw.io skeleton template

AWS Icon Notation

AWS Draw.io icons can be specified with short shape references:

<mxCell style="...shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;"
        vertex="1" parent="grp-subnet">
  <mxGeometry width="48" height="48" as="geometry" />
</mxCell>

The key part is resIcon=mxgraph.aws4.lambda. Since this is a reference to the AWS stencil library built into Draw.io, you just need to know the icon name. This is easy for LLMs to handle, and the reference files remain lightweight.

The GCP Icon Problem: Inline SVG Approach

When I investigated Draw.io's source code to build the GCP version, I found a fundamental difference.

GCP Icon Notation

<mxCell style="...shape=image;image=data:image/svg+xml,PHN2ZyB4bWxucz0i..."
        vertex="1" parent="grp-region">
  <mxGeometry width="42" height="42" as="geometry" />
</mxCell>

image=data:image/svg+xml,PHN2Gy... — this is the Base64-encoded SVG data itself. The Draw.io GCP2 library, rather than using stencil references like AWS, embeds the SVG image of each icon directly in the style attribute.

What This Means for LLMs

In other words, it is impossible for an LLM to generate GCP icon style strings from "memory" or "guessing". If even a single character of the Base64-encoded SVG is wrong, the icon will be broken and won't display.

Researching Industry Approaches

I looked into whether there were any prior examples of building a "GCP Draw.io skill."

Ruban Siva / Google Cloud Article

In a format close to the official Google Cloud blog, an approach combining Draw.io and MCP to automatically generate GCP architecture diagrams was introduced. The key was building a component library in advance and copying accurate style strings from it.

Agents365 / drawio-skill

A Draw.io skill published on GitHub that includes shapesearch.py with over 10,000 shape definitions. However, there was the concern of adding a Python dependency, and the coverage of GCP icons was unclear.

The Approach I Adopted

Based on both research findings, I determined that the same pattern as the AWS version — storing entire style strings in pre-extracted reference files — was the most reliable approach. The LLM only needs to copy and paste style strings from the reference files, so it doesn't need to "understand" Base64 SVG.

Implementation: Extracting Icons from Draw.io Source

Where the SVG Data Comes From

Draw.io's GCP icons are stored in two files in the jgraph/drawio GitHub repository:

• Sidebar-GCP2.js (2432 lines) — 163 modern GCP icons (inline SVG format)
• gcp2.xml — approximately 200 stencil shapes (generic icons)

The contents of Sidebar-GCP2.js are a set of functions that register icons for each palette:

// addGCP2IconsComputePalette, addGCP2IconsNetworkingPalette, ...
this.createVertexTemplateEntry(
  'editableCssRules=.*;sketch=0;html=1;...image=data:image/svg+xml,PHN2Gy...',
  42, 42, 'Compute Engine', null, null, null, ...
);

From each createVertexTemplateEntry call, we just need to extract the style string, width, height, and label.

Extraction Script

Using a Python script, I parsed Sidebar-GCP2.js and extracted 163 icons across 16 categories:

PALETTES = {
    "addGCP2IconsAIAndMachineLearningPalette": ("gcp-icons-ai-ml.md", "AI / Machine Learning"),
    "addGCP2IconsComputePalette": ("gcp-icons-compute.md", "Compute"),
    "addGCP2IconsNetworkingPalette": ("gcp-icons-networking.md", "Networking"),
    # ... 16 palettes
}

Entries are extracted from each palette function using regular expressions and written to category-specific Markdown files. The output format was aligned with the AWS version:

### Cloud Run

- **Width**: 34
- **Height**: 42
- **Style**: `editableCssRules=.*;sketch=0;html=1;...image=data:image/svg+xml,PHN2Gy...`

Style strings are stored completely as-is, without any modification. No line breaks or indentation are added. Changing even a single character would break the icons.

Structure of the Completed Skill

The final directory structure is as follows:

.claude/skills/gcp-architecture-diagram/
├── SKILL.md                              # Main instruction file (212 lines)
├── templates/
│   └── base.drawio.xml                   # Draw.io template (shared with AWS version)
└── references/
    ├── layout-guidelines.md              # GCP-specific layout rules
    ├── gcp-icons-common.md               # Zones, paths, GCP logo, generic icons
    ├── gcp-icons-compute.md              # Compute Engine, GKE, etc. (11 icons)
    ├── gcp-icons-serverless.md           # Cloud Functions, Cloud Run, etc. (5 icons)
    ├── gcp-icons-databases.md            # Cloud SQL, Spanner, etc. (9 icons)
    ├── gcp-icons-storage.md              # Cloud Storage, Filestore, etc. (4 icons)
    ├── gcp-icons-networking.md           # VPC, Load Balancing, etc. (19 icons)
    ├── gcp-icons-data-analytics.md       # BigQuery, Dataflow, etc. (16 icons)
    ├── gcp-icons-ai-ml.md                # Vertex AI, AutoML, etc. (29 icons)
    ├── gcp-icons-security.md             # IAM, KMS, Chronicle, etc. (10 icons)
    ├── gcp-icons-operations.md           # Logging, Monitoring, etc. (17 icons)
    ├── gcp-icons-cicd.md                 # Cloud Build, Artifact Registry, etc. (15 icons)
    ├── gcp-icons-integration.md          # Eventarc, Workflows, etc. (7 icons)
    ├── gcp-icons-api-management.md       # Apigee, Endpoints, etc. (5 icons)
    ├── gcp-icons-migration.md            # Transfer Appliance, etc. (7 icons)
    ├── gcp-icons-hybrid-multicloud.md    # Anthos, etc. (4 icons)
    ├── gcp-icons-iot.md                  # Cloud IoT Core (1 icon)
    └── gcp-icons-opensource.md            # OSS-related icons (4 icons)

Total: 20 files, 163 icons, approximately 380KB

The AWS version had 7 reference files, so the GCP version significantly increased to 18 reference files. This is because the GCP2 library has more fine-grained category divisions.

Key Design Differences from the AWS Version

Container Nesting Hierarchy

In GCP, the project is the top-level container, with the VPC Network inside it. In AWS, Cloud is the outermost layer and VPC sits under Region.

Container Styles

AWS has individual shapes for each group, but GCP represents everything using the common shape shape=mxgraph.gcp2.zones, simply changing the fillColor:

Edge Colors

AWS tends to use orange tones, but GCP uses Google brand colors:

Managed Services Pattern

GCP managed services (BigQuery, Vertex AI, Cloud Storage, etc.) exist outside the VPC. To visually represent this, I designed a Two-box layout pattern:

+--- Google Cloud Project --------------------------------+
|                                                          |
|  +--- VPC Network ---+   +--- Managed Services --------+|
|  | GKE, Compute     |   | Cloud SQL, BigQuery,         ||
|  | Engine, etc.     | →  | Vertex AI, Cloud Storage    ||
|  +-------------------+   | (GCP-managed, outside VPC)  ||
|                           +-----------------------------+|
+----------------------------------------------------------+

User-deployed resources go in the VPC box, and GCP managed services are placed in the Managed Services box with a dashed border. Arrows connect directly from source to target, and details about Private Google Access and Private Service Connect are documented in a companion guide.

Testing: Three-Tier Serverless Architecture

As a functional test of the skill, I generated a simple three-tier configuration:

Users → Cloud Load Balancing → Cloud Run → Cloud SQL / Cloud Storage

Points confirmed in the generated Draw.io file:

1. Icon rendering — GCP color icons for Cloud Load Balancing, Cloud Run, Cloud SQL, and Cloud Storage display correctly
2. Container nesting — Project (gray) → VPC (blue) → Region (green) are correctly nested
3. GCP logo — A small Google Cloud logo appears in the upper left of the project container
4. Edges — Orthogonal routing arrows in Google Blue (#4284F3) connect correctly

Points of Care

SKILL.md Design

I used the AWS version's SKILL.md as a base and added GCP-specific elements:

• 15 rules — Verbatim copying of style strings, accurate size specifications, GCP logo placement, etc.
• Non-Technical Audience Mode — Edges with step numbers (①②③④) allow generating diagrams for non-technical audiences
• Managed Services pattern — A layout pattern that visualizes the boundary between VPC resources and managed services

Unified Reference File Format

I used the same format for the AWS and GCP versions, making it easier for the LLM to learn as a "pattern":

### Service Name

- **Width**: 42
- **Height**: 42
- **Style**: `complete style string...`

Whether the content of the style string is a shape reference or Base64 SVG makes no difference to the LLM — it's just "something to copy and paste."

Cell ID Conventions

For maintainability, I defined a convention for giving descriptive IDs to drawing elements:

• Groups: grp-project, grp-vpc, grp-region, grp-zone-a
• Icons: svc-gke, svc-cloud-sql, svc-bigquery
• Edges: edge-1, edge-2
• Logo: logo-gcp

What I Learned

The Same Pattern Can Be Applied to Different Providers

While the icon formats for AWS and GCP are fundamentally different, the skill design pattern of "copying style strings from reference files" could be applied to both. All the LLM needs to do is "read the right file and copy the right value." There's no need to "understand" Base64 SVG.

Investigating the Icon Format Is Important

When building a Draw.io skill, you should first check the icon format of the target library. The reference file design differs greatly between stencil reference types (AWS, Azure) and inline SVG types (GCP). Reading the Sidebar-series JS files in Draw.io's GitHub repository (jgraph/drawio) is the most reliable approach.

Never Touch the SVG Data

The Base64 SVG data of GCP icons must never be modified — not during extraction, not when storing in reference files. Adding line breaks, re-encoding, trimming — all of these lead to broken icons. "Don't touch it" is the rule.

Summary

I built a skill where simply saying "draw a GCP architecture diagram" in Claude Code outputs an accurate Draw.io file. There was a technical barrier in the difference between AWS and GCP icon formats (shape references vs. inline SVG), but I resolved it by pre-extracting SVG data from Draw.io's source code and storing it in reference files.

With a skill set of 20 files, 163 icons, and approximately 380KB, nearly all major GCP services are covered. By aligning the design pattern with the AWS version, the same technique should be applicable when building an Azure version in the future.