DEV Community

Cover image for Custom Claude Code Skill: Auto-Generating / Updating Architecture Diagrams with Excalidraw
Ooi Yee Fei
Ooi Yee Fei

Posted on • Edited on

Custom Claude Code Skill: Auto-Generating / Updating Architecture Diagrams with Excalidraw

#architecture #programming #coding #ai

I maintain several GCP infrastructure projects with Terraform. Every time I onboard someone or need to explain the architecture, I face the same problem: my diagrams are either outdated or does not even exist.

The Problem

If you use any coding agent you can generally ask Claude or Gemini to scan your codecase and generate architecture diagram anytime. I tried different approaches:
Mermaid diagrams - Great for code-based diagrams, but they get cluttered fast. A Terraform stack with 15+ resources becomes unreadable. And they don't support the freeform layout I need.

Manual Excalidraw - Beautiful, collaborative, easy to share. But I have to manually update it every time infrastructure changes. Which means it's always outdated.

What I wanted: Claude Code analyzes my codebase and generates an Excalidraw diagram automatically. High-level, clean, with proper arrows.

Most importantly, as I continue working on the project, Claude Code can update the diagram, by understanding the up-to-date codebase, comparing against the old diagram which give useful contexts sometimes.

Exploring Solutions

I considered different approaches to make this convenient:

  1. Ad-hoc prompts — Just ask Claude Code when I need an update

  2. Claude Code Skill — Teach Claude the Excalidraw format once, reuse everywhere

  3. Plugin with slash command — /excalidraw to trigger generation

  4. MCP server — More complex, but could watch for file changes

  5. Hooks — Auto-trigger diagram updates after certain git operations

I started with Claude Code Skills — the simplest to implement. Skills are markdown files that teach Claude how to perform specific tasks. No scripts, no servers, just knowledge files. Perfect for experimenting with quality and feasibility before investing in more complex solutions.

Results

Here’s what it generated for an EKS AI/ML Terraform stack — Karpenter, GPU workloads, Rafay orchestration — from a single prompt:

Full Writeup

The full post covers how the skill generates valid .excalidraw JSON with proper labels and elbow arrows, installation, usage commands, and more examples.

Read the full writeup on Build Signals

Links:

Top comments (0)