DEV Community

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

Posted on

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

#programming #ai #architecture #coding

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.

The skill I built:

  1. Analyzes any codebase (Terraform, Node.js, Python, etc.)

  2. Identifies components, services, and their relationships

  3. Generates valid .excalidraw JSON files

Why and what are the use cases for this Skill ?

Excalidraw has become my go-to for architecture diagrams. A few use cases you can use this Claude Code Skills for:

  • Keep Architecture Diagram up-to-date — No more outdated diagrams. Claude reads your current code and regenerates with full context of what changed.

  • Version-controllable — Commit diagrams alongside code. Diff changes. Review in PRs.

  • Collaboration — .excalidraw files are shared and maintained together with Git with your team, iterate together in real-time on excalidraw.com, or review changes in PRs like any other code artifact.

The .excalidraw format is just JSON — no libraries needed. Claude can generate it directly.

Enhancing the Skill’s features and capabilities:
Some gotchas and learnings:
Proper labels — Initially, I got the shape well but without key input and texts. After few debugging, the skill now teaches Claude to generate .excalidraw files with properly bound text labels. Without this, you get empty boxes. The JSON format requires a specific two-element pattern (shape + text) that isn’t obvious from Excalidraw’s JavaScript API docs.

Elbow arrows — By default LLM won’t really realize the overlapping of arrows and how best place and route them. Straight diagonal arrows look messy when connecting multiple components. The skill generates 90-degree elbow arrows that route cleanly around boxes — much more aesthetic and professional than overlapping straight lines.

Installation

The skill is open source at GitHub

Install in Claude Code:

# Add the marketplace
/plugin marketplace add ooiyeefei/ccc
# Install the skills collection
/plugin install ccc-skills@ccc
# Restart Claude Code
Enter fullscreen mode Exit fullscreen mode

How to Use

After installation, try with preferred prompt or example below:

Use the ccc-skills:excalidraw skill to generate an architecture diagram for this project. Save to docs/architecture.excalidraw
Enter fullscreen mode Exit fullscreen mode

Claude will:

  1. Analyze your codebase

  2. Identify components and relationships

  3. Generate valid .excalidraw JSON

  4. Save to the specified path

Open the file in Excalidraw or VS Code’s Excalidraw extension.

Example: EKS AI/ML Stack

I tested this on one of my sample repo that was built based on AWS AI on EKS blueprint for AI/ML workloads on EKS project (GitHub) — an EKS cluster with Rafay for GPU workload orchestration, Karpenter for autoscaling, and various AI/ML services. (Minor arrow adjustments may be needed occasionally, but the architecture logic and component relationships are accurate out of the box.)

Prompt used:

Use the ccc-skills:excalidraw skill to generate an architecture diagram for this project.
Enter fullscreen mode Exit fullscreen mode

The skill identified the Terraform modules, understood the relationships between VPC → EKS → Node Groups → Karpenter, and generated a clean diagram with proper component grouping.

Try It Out

Got a Terraform stack, microservices repo, or monolith that needs documenting? Give it a shot and let me know what works and what breaks.

Links:

Top comments (0)