Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts. Customized for OptivAI Dev OS — the 4-layer AI execution platform.
npx claudepluginhub feedbackloopai-llc/optivai-claude-pluginThis skill uses the workspace's default tool permissions.
Generate `.excalidraw` JSON files that **argue visually**, not just display information.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Generate .excalidraw JSON files that argue visually, not just display information.
Setup: If the user asks you to set up this skill (renderer, dependencies, etc.), see the First-Time Setup section under Render & Validate.
This skill operates within the OptivAI Dev OS repository. The system has a 4-layer architecture:
PLATFORM (devos_platform/devos/) — governance, policy, telemetry, cost
WORKLOADS (workloads/reporting/) — business logic, queries, data contracts
ADAPTERS (adapters/mcp/) — transport + interface (MCP server)
GATEWAY (gateway/) — HTTP API for browser clients
UI (ui/) — Vite + React + Tailwind browser client
docs/architecture/safe-change-engine.md — Defect response, governance, deploy safetydocs/architecture/agent-pipeline.md — AI dev pipeline + permission matrixdocs/architecture/mcp-ecosystem.md — MCP as universal interfacedocs/architecture/tool-contracts.md — Universal tool contract + preview/commit| Lane | What Changes | Gate |
|---|---|---|
| Green | queries, formatters, tests, docs, UI | CI passes → auto-merge |
| Yellow | SQL, contracts, connections, adapters | CI + human approval |
| Red | platform core, prod terraform, IAM, security groups | CI + explicit human approval |
Modules: ECR → ECS Service → ALB → Security Groups → IAM → CloudWatch. All resources prefixed gz-devos-{resource}-{env}.
Output path: All diagrams go to docs/diagrams/ (PNG + source .excalidraw JSON).
All colors and brand-specific styles live in one file: references/color-palette.md. Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything.
To make this skill produce diagrams in your own brand style, edit color-palette.md. Everything else in this file is universal design methodology and Excalidraw best practices.
Diagrams should ARGUE, not DISPLAY.
A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning.
The Isomorphism Test: If you removed all text, would the structure alone communicate the concept? If not, redesign.
The Education Test: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples.
Before designing, determine what level of detail this diagram needs:
Use abstract shapes when:
Use concrete examples when:
For technical diagrams, you MUST include evidence artifacts (see below).
Before drawing anything technical, research the actual specifications.
If you're diagramming a protocol, API, or framework:
Bad: "Protocol" → "Frontend" Good: "MCP tool call → preview_result → human approve → commit_result" with actual JSON shapes
For OptivAI Dev OS diagrams: Read the relevant architecture doc before designing. Use real module names, actual query paths, real Terraform resource names.
Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams.
Types of evidence artifacts (choose what's relevant to your diagram):
| Artifact Type | When to Use | How to Render |
|---|---|---|
| Code snippets | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) |
| Data/JSON examples | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) |
| Event/step sequences | Protocols, workflows, lifecycles | Timeline pattern (line + dots + labels) |
| UI mockups | Showing actual output/results | Nested rectangles mimicking real UI |
| Real input content | Showing what goes IN to a system | Rectangle with sample content visible |
| API/method names | Real function calls, endpoints | Use actual names from docs, not placeholders |
Comprehensive diagrams operate at multiple zoom levels simultaneously.
A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram.
Labeled regions that group related components. For OptivAI Dev OS, natural section boundaries are the 4 layers: Platform, Workloads, Adapters, Gateway, UI.
Evidence artifacts, code snippets, and concrete examples within each section.
For comprehensive diagrams, aim to include all three levels.
Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when they serve a purpose.
| Use a Container When... | Use Free-Floating Text When... |
|---|---|
| It's the focal point of a section | It's a label or description |
| It needs visual grouping with other elements | It's supporting detail or metadata |
| Arrows need to connect to it | It describes something nearby |
| The shape itself carries meaning (decision diamond, etc.) | It's a section title, subtitle, or annotation |
| It represents a distinct "thing" in the system | It's a section title, subtitle, or annotation |
Typography as hierarchy: Use font size, weight, and color to create visual hierarchy without boxes. A 28px title doesn't need a rectangle around it.
Before anything else, determine if this needs to be:
If comprehensive: Read the relevant GZ architecture docs first.
Read the content. For each concept, ask:
For each concept, find the visual pattern that mirrors its behavior:
| If the concept... | Use this pattern |
|---|---|
| Spawns multiple outputs | Fan-out (radial arrows from center) |
| Combines inputs into one | Convergence (funnel, arrows merging) |
| Has hierarchy/nesting | Tree (lines + free-floating text) |
| Is a sequence of steps | Timeline (line + dots + free-floating labels) |
| Loops or improves continuously | Spiral/Cycle (arrow returning to start) |
| Is an abstract state or context | Cloud (overlapping ellipses) |
| Transforms input to output | Assembly line (before → process → after) |
| Compares two things | Side-by-side (parallel with contrast) |
| Separates into phases | Gap/Break (visual separation between sections) |
For multi-concept diagrams: each major concept must use a different visual pattern. No uniform cards or grids.
Before JSON, mentally trace how the eye moves through the diagram. There should be a clear visual story.
Only now create the Excalidraw elements. See below for how to handle large diagrams.
After generating the JSON, you MUST run the render-view-fix loop until the diagram looks right. This is not optional — see the Render & Validate section below for the full process.
For comprehensive or technical diagrams, you MUST build the JSON one section at a time. Do NOT attempt to generate the entire file in a single pass. This is a hard constraint — Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that in one shot.
Phase 1: Build each section
type, version, appState, files) and the first section of elements."platform_rect", "arrow_to_workloads") so cross-section references are readable.Phase 2: Review the whole
After all sections are in place, read through the complete JSON and check:
Phase 3: Render & validate
Now run the render-view-fix loop from the Render & Validate section.
Central element with arrows radiating to multiple targets. Use for: sources, PRDs, root causes, central hubs.
Multiple inputs merging through arrows to single output. Use for: aggregation, funnels, synthesis.
Parent-child branching with connecting lines and free-floating text (no boxes needed).
Elements in sequence with arrow returning to start. Use for: feedback loops, iterative processes.
Overlapping ellipses with varied sizes. Use for: context, memory, conversations, mental states.
Input → Process Box → Output with clear before/after.
Two parallel structures with visual contrast.
Visual whitespace or barrier between sections.
Use lines (type: line, not arrows) as primary structural elements instead of boxes:
| Concept Type | Shape | Why |
|---|---|---|
| Labels, descriptions, details | none (free-floating text) | Typography creates hierarchy |
| Markers on a timeline | small ellipse (10-20px) | Visual anchor, not container |
| Start, trigger, input | ellipse | Soft, origin-like |
| End, output, result | ellipse | Completion, destination |
| Decision, condition | diamond | Classic decision symbol |
| Process, action, step | rectangle | Contained action |
| Abstract state, context | overlapping ellipse | Fuzzy, cloud-like |
Rule: Default to no container. Add shapes only when they carry meaning. Aim for <30% of text elements to be inside containers.
Colors encode information, not decoration. Every color choice should come from references/color-palette.md — the semantic shape colors, text hierarchy colors, and evidence artifact colors are all defined there.
Do not invent new colors. If a concept doesn't fit an existing semantic category, use Primary/Neutral.
roughness: 0 — Default for clean, professional diagramsstrokeWidth: 2 — Standard for shapes and primary arrowsopacity: 100 — Always, for all elementsCRITICAL: The JSON text property contains ONLY readable words.
{
"id": "myElement1",
"text": "Start",
"originalText": "Start"
}
Settings: fontSize: 16, fontFamily: 3, textAlign: "center", verticalAlign: "middle"
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [...],
"appState": {
"viewBackgroundColor": "#ffffff",
"gridSize": 20
},
"files": {}
}
See references/element-templates.md for copy-paste JSON templates for each element type. Pull colors from references/color-palette.md based on each element's semantic purpose.
You cannot judge a diagram from JSON alone. After generating or editing the Excalidraw JSON, you MUST render it to PNG, view the image, and fix what you see — in a loop until it's right.
cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>
This outputs a PNG next to the .excalidraw file. Then use the Read tool on the PNG to actually view it.
After generating the initial JSON, run this cycle:
1. Render & View — Run the render script, then Read the PNG.
2. Audit against your original vision — Compare the rendered result to what you designed in Steps 1-4. Ask:
3. Check for visual defects:
4. Fix — Edit the JSON to address everything you found.
5. Re-render & re-view — Run the render script again and Read the new PNG.
6. Repeat — Keep cycling until the diagram passes both the vision check and the defect check. Typically takes 2-4 iterations.
The loop is done when:
If the render script hasn't been set up yet:
cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium
text contains only readable wordsfontFamily: 3roughness: 0opacity: 100 for all elements