Build BEAUTIFUL Diagrams with Claude Code (Full Workflow)

Key Concepts

• Visual Argumentation: The methodology of using diagrams to explain complex concepts rather than relying on text-heavy or "blocky" layouts.
• Excalidraw (Excal): A virtual whiteboard tool used for creating hand-drawn style diagrams.
• Self-Validation Loop: A process where the AI agent renders its own output, takes a screenshot, analyzes the image, and iterates to fix imperfections.
• Coding Agents: AI tools (e.g., Claude Code) that assist in software development and task automation.
• Skill-Based Prompting: Packaging specific workflows into "skills" that agents can read and execute via documentation (e.g., skill.mmd).

1. The Problem: Visual Limitations of Coding Agents

Coding agents like Claude Code are highly proficient at text-based tasks but struggle with visual communication. Without specific guidance, these agents tend to produce "blocky," uninspired diagrams that fail to convey complex information effectively. The speaker identifies a gap in the current workflow: the lack of an inherent ability for agents to "see" and refine their visual output.

2. The Solution: The Excalidraw Diagram Skill

The speaker has developed a workflow that enables coding agents to "argue visually." By packaging this workflow into a skill, the agent is taught to prioritize structure and labeling over simple block placement.

The Workflow Process:

1. Instruction Set: The agent is provided with a primary instruction set (contained in skill.mmd) that dictates how to structure diagrams for clarity and aesthetic appeal.
2. JSON Generation: The agent generates the necessary JSON files required to render Excalidraw diagrams.
3. Self-Validation Loop: This is the core technical innovation. The agent:
   • Renders the diagram.
   • Takes a screenshot of the output.
   • Analyzes the resulting PNG file.
   • Iterates on the design to correct visual imperfections.

3. Implementation and Setup

The speaker emphasizes that the setup process is streamlined for the user.

• Automated Setup: Users can instruct their coding agent to "set up the Excalidraw diagram skill." Because the agent can read the provided readme file, it can perform the manual installation steps autonomously.
• Customization: The workflow allows for "on-brand" customization, enabling users to define specific color schemes and design preferences that the agent will consistently apply to all generated diagrams.

4. Core Philosophy: Arguing Visually

The central argument presented is that diagrams should serve as an argument for a concept. The speaker notes:

"We don't just want to put things in a bunch of blocks... we want to argue visually; we want the structure and labels to explain the entire concept."

This approach shifts the agent's focus from merely placing shapes on a canvas to creating a logical, visual narrative that aids in understanding complex codebases or PDF documents.

5. Practical Applications and Benefits

• Efficiency: The speaker reports saving "hours and hours every single week" by using this workflow to generate starting points for documentation and explanations.
• Versatility: The tool can be applied to various inputs, including complex codebases and PDF documents, making it a highly flexible utility for developers and technical communicators.
• Iterative Improvement: By utilizing the self-validation loop, the agent produces results that are significantly higher in quality than standard, non-validated AI-generated diagrams.

Conclusion

The integration of a self-validating visual skill into coding agents transforms them from simple code generators into comprehensive communication tools. By teaching agents to "argue visually" and providing them with the capability to critique their own visual output, users can automate the creation of high-quality, on-brand diagrams, drastically reducing the time required for technical documentation and conceptual explanation.