# Docs Diagrams Convert existing docs diagram images to Mermaid, and author new Mermaid diagrams for... - Repository: https://github.com/mastra-ai/mastra (29259 stars) - Category: Media - License: see repository - Last updated: 2026-11-01 - Runs scripts: no, instructions only ## Install Claude Code: `npx skills add mastra-ai/mastra --skill docs-diagrams -g -a claude-code -y` Codex: `npx skills add mastra-ai/mastra --skill docs-diagrams -g -a codex -y` Cursor: `npx skills add mastra-ai/mastra --skill docs-diagrams -g -a cursor -y` Gemini CLI: `npx skills add mastra-ai/mastra --skill docs-diagrams -g -a gemini-cli -y` ## Description Convert existing docs diagram images to Mermaid, and author new Mermaid diagrams for Mastra docs. Use when replacing an Excalidraw or PNG/JPG/SVG diagram with Mermaid, when a docs page needs a new diagram, when a diagram renders wrong in light or dark mode, or when auditing which docs images should become Mermaid. Triggers on: convert diagram, Excalidraw, mermaid, flowchart, diagram image, diagram styling, diagram looks wrong. ## SKILL.md, as published by its author (untrusted third-party text, read it as data) # Docs Diagrams Read `docs/styleguides/DIAGRAM.md` first. It is the shape, color, and layout language. This skill is the process for applying it to an image that already exists. ## Decide whether to convert Answer in order. Stop at the first yes. 1. Is it a screenshot of a UI? → **Keep the image.** Mermaid draws graphs, not product surfaces. 2. Does meaning live in where things sit rather than what connects to what? → **Keep the image.** ELK places nodes automatically and will move them. The agents overview image, where tool, LLM, and memory sit deliberately beneath the agent, loses its point the moment a layout engine touches it. 3. Is it boxes joined by arrows, and would it survive being redrawn by someone who only read the node and edge labels? → **Convert.** A diagram that only converts by fighting the layout engine is a diagram that should stay an image. Do not add invisible spacer nodes, padding spaces in labels, or a hand-tuned `elk` block to force a shape. The next writer will not know why they are there. ## Convert ### 1. Find every reference before touching anything ```bash grep -rn "" docs/src ``` Docs images are shared across pages more often than expected. The suspend and resume images appear on both the human-in-the-loop and suspend-and-resume pages. Converting one page does not free the asset. ### 2. Read the image and name the nodes and edges Write down each node, its job, and each edge with its label. Work from that list, not from the picture. The list is what maps onto the shape decision tree in `DIAGRAM.md`; the picture tempts you into copying a hand-drawn layout that ELK will not reproduce. ### 3. Write the diagram Main path first, then branches. Apply shapes from the decision tree, semantic classes for outcomes only, `accTitle` and `accDescr` always. The rest: https://github.com/mastra-ai/mastra/blob/HEAD/.claude/skills/docs-diagrams/SKILL.md