diagram-design · vstorm-co — Claude Code skill for research diagrams
The diagram-design skill guides research diagram creation on an Excalidraw canvas through MCP. Use it to map comparisons, processes, architectures, or timelines.
MIT ★ 1,125 updated 2026-10-27
npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -a claude-codeWhat diagram-design does
The skill helps decide when research findings call for a diagram: compare options, map a multi-step process, or show how system components relate. It also suggests layouts, from grids for comparisons to radial maps for concepts.
Its workflow uses Excalidraw MCP tools to create and arrange elements, inspect the scene with describe_scene, revise text or placement, and group related items. The guide covers colors, shapes, labels, arrows, and spacing. Avoid create_from_mermaid: the instructions say it produces an invisible result.
The canvas syncs live, so the skill advises against exporting diagrams or sharing links. Excalidraw MCP tools are needed to create and inspect diagram elements.
What it helps with
- compare options in a single diagram
- map the stages of a process
- show system components and their relationships
- arrange research events on a timeline
- turn findings into a concept map
Example prompts for the agent
- Compare the options and show their advantages, limits, and verdict in an Excalidraw diagram.
- Draw the system architecture from the component and relationship descriptions.
- Arrange the research events chronologically as a timeline.
How to install diagram-design
1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -a claude-code2Manually: put the files in place
~/.claude/skills/diagram-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/diagram-design/
1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -a codex2Manually: put the files in place
.agents/skills/diagram-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -a cursor2Manually: put the files in place
.cursor/skills/diagram-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vstorm-co/pydantic-deepagents apps/deepresearch/skills/diagram-design2Manually: put the files in place
.github/skills/diagram-design/SKILL.md1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/vstorm-co/pydantic-deepagents --path apps/deepresearch/skills/diagram-designManually: put the files in place
.devin/skills/diagram-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about diagram-design
How do I install diagram-design in Claude Code?
Run npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -a claude-code, then use ~/.claude/skills/diagram-design/SKILL.md.
What does diagram-design do?
It guides the creation of research diagrams in Excalidraw, covering diagram choice, layout, element creation, inspection, colors, shapes, and arrows.
Why should I avoid create_from_mermaid?
The guide warns that this method produces an invisible result. It recommends batch_create_elements with element JSON instead.
Source text
SKILL.md · MIT
--- name: diagram-design description: Best practices for creating research diagrams with Excalidraw MCP tools --- # Diagram Design Guide for Research ## When to Create Diagrams Create a diagram when your research findings involve: - **Comparing 3+ options** — comparison table or matrix diagram - **Process with 4+ steps** — flowchart or sequence diagram - **System with multiple components** — architecture diagram - **Chronological events** — timeline - **Hierarchical relationships** — tree or mind map - **Data flows** — data flow diagram ## Excalidraw Workflow 1. **Plan the diagram** — decide type, elements, and layout before creating 2. **Create elements** — use `create_element` or `batch_create_elements` 3. **Arrange** — use `align_elements` and `distribute_elements` for clean layout 4. **Inspect** — use `describe_scene` to verify the diagram looks right 5. **Adjust** — use `update_element` to fix positioning or text 6. **Group** — use `group_elements` to lock related items together > **Note:** Do NOT export or share links — the user sees a live embedded canvas that auto-syncs. ## Color Palette Use consistent colors across diagrams: | Purpose | Color | Hex | |---------|-------|-----| | Primary concepts | Blue | #1971c2 | | Positive / supported | Green | #2f9e44 | | Negative / limitations | Red | #e03131 | | Warning / caveats | Orange | #e8590c | | Neutral / context | Gray | #868e96 | | Highlight / focus | Yellow | #f08c00 | ## Layout Patterns - **Top-to-bottom**: Process flows, decision trees, timelines - **Left-to-right**: Comparisons, before/after, pipelines - **Radial / center-out**: Concept maps, mind maps - **Grid**: Feature matrices, comparison tables ## Element Guidelines ### Text - Use short labels (2-4 words per element) - Title font size: 20-24px - Label font size: 14-16px - Add detail in sub-labels, not element titles ### Shapes - **Rectangles**: Processes, components, entities - **Diamonds**: Decision points - **Ellipses**: Start/end points, concepts - **Rectangles with rounded corners**: Groups, categories ### Arrows - **Solid arrows**: Direct relationships, data flow - **Dashed arrows**: Optional paths, indirect relationships - Label arrows to clarify the relationship ### Spacing - 40px minimum between elements - 80px between groups - Consistent spacing within a group ## Diagram Types for Research ### Comparison Diagram ``` [Option A] [Option B] [Option C] | | | [Pros] [Pros] [Pros] [Cons] [Cons] [Cons] | | | └──── [Verdict] ─────────┘ ``` ### Architecture Diagram ``` ┌─────────────────────────────┐ │ [System Name] │ │ ┌──────┐ ┌──────┐ │ │ │Comp A│──│Comp B│ │ │ └──────┘ └──┬───┘ │ │ │ │ │ ┌────▼────┐ │ │ │ Comp C │ │ │ └─────────┘ │ └─────────────────────────────┘ ``` ### Timeline ``` [2020]──[2021]──[2022]──[2023]──[2024]──[2025] │ │ │ │ │ │ Event Event Event Event Event Event ``` ## Tips - Always call `describe_scene` after creating elements to verify layout - Use `batch_create_elements` for efficiency (multiple elements at once) - Group related elements before aligning for cleaner organization - Do NOT export or share links — the live embedded canvas auto-syncs for the user - NEVER use `create_from_mermaid` — it produces invisible results. Always use `batch_create_elements` with element JSON instead
© vstorm-co · MIT · vstorm-co/pydantic-deepagents
Similar skills
All skills for Design →diagram-design by other authors comes first.