architecture-drawio-diagram for Claude Code and Codex: system diagrams with large logos

architecture-drawio-diagram is a skill that draws system architecture diagrams with large service logos through code, then exports a .drawio file and a PNG. It is a single skill with scripts and examples, published in the book author’s public repository, which has no license file. This post covers the problem it solves, who it suits, how to install it and make the first request, and the requirement that decides whether you get a PNG at all.

What problem it solves

A backend diagram for a blog post has a short life. You draw it by hand, the architecture changes, and now the picture on the page is wrong. Moving every box in a drawing tool feels like too much work for one new service, so the old diagram stays up. The trouble grows with the number of external services, since each one needs a recognizable logo and a place on the canvas.

This skill keeps the drawing in code. A layout script of 20 to 40 lines records the coordinates of each box, logo, and arrow. When the architecture changes, you edit a few coordinate lines and rerun it. The skill also confirms the structure before it draws anything, defining the actors, the entry point, three to five processing steps, the storage and external services, and the exit, in that order. The script then writes the .drawio file, the draw.io desktop CLI renders the PNG, and the PNG gets a visual check for overlapping labels and clipped text before delivery.

Who it fits

The chapter rates five situations. These three cover most decisions.

Situation	Fit	Reason
Backend architecture diagrams for blogs	Good fit	Defaults to PNG at 1200 pixels wide
Flows with many external services	Good fit	Logo nodes take center stage
Concept diagrams without logos	Poor fit	Handled by a text diagram skill

If your picture has no logos in it, start with diagram-design from this series instead. If it is a service architecture and you want automated layout checks, compare it with archify.

Install and first run

Download the claude-playbook repository from GitHub at ggplab/claude-playbook, then copy the skill folder to the path your agent reads.

# Download the claude-playbook repository, then copy the skill folder to the Claude Code path
cp -r claude-playbook/02-skills/architecture-drawio-diagram ~/.claude/skills/

# To use the Codex path
cp -r claude-playbook/02-skills/architecture-drawio-diagram ~/.agents/skills/

# Run the example (inside the skill folder)
python3 example/grading_bot.py

The SKILL.md in the repository is written in Korean, so translate it before use. To run the skill, describe the architecture you want after the slash command.

/architecture-drawio-diagram Draw an architecture where a participant uploads a workflow file through Discord, a Supabase function validates it, and Gemini grades it and posts a reply

What trips people up

Automatic PNG output depends on draw.io desktop, because the script calls its CLI to render. If you skip that install, the diagram does not come out as a picture on its own. The instructions give you two ways around it: create only the .drawio file and export it manually at app.diagrams.net, or switch to Mermaid and give up the logos. Install draw.io desktop first if logos are the reason you picked this skill.

Pillow is the smaller version of the same catch. The skill assumes python3 and pillow, and without pillow the resize step is skipped, so you get only the original-size PNG. Run the bundled example once after installing, and you will find out about both before your own diagram depends on them.

Where this comes from

This post adapts part of chapter 04-05 of The Claude Code & Codex Skills Guidebook. The full chapter covers how to prepare logos and point the script at draw.io, and how to edit the .drawio file by hand while the layout script stays the source of truth, and the book has 52 more skills like this one. Read the full chapter in The Claude Code & Codex Skills Guidebook on Gumroad.