canvas skill
✓ VerifiedConverts code, specifications, and context into various diagram formats like Mermaid, ASCII, or draw.io for visual documentation.
- GitHub stars
- 98
- Files
- 19
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the canvas skill do?
canvas converts code, specifications, and context into various diagram formats like Mermaid, ASCII, or draw.io for visual documentation.
Summary generated from the skill's SKILL.md.
About the canvas skill
Developers and architects can transform complex code, technical specifications, and system context into clear visual documentation. This skill specializes in converting raw data into various formats including Mermaid, ASCII, and editable draw.io XML. It is particularly useful for reverse-engineering applications, APIs, and database schemas to create flowcharts, sequence diagrams, ER diagrams, and C4 model views.
When an agent needs to visualize a system structure, a user journey, or a project roadmap, it loads this skill to produce structured diagram code. It supports diverse visual styles, ranging from hand-drawn looks for informal workshops to modern Neo aesthetics for presentations. The tool prioritizes accessibility by providing alt-text and color-blind-safe palettes, ensuring that diagrams remain useful in plain-text terminals via ASCII fallbacks. It functions as a visualization specialist that bridges the gap between abstract logic and visual understanding.
What an agent can do with it
- 1Reverse engineer application architectureGenerate visual representations of system structures directly from existing application code or dependency structures.
- 2Create editable presentation diagramsProduce high-quality, editable diagrams for professional presentations using draw.io XML output.
- 3Visualize user experience journeysMap out user friction points and persona profiles through integrated journey maps.
- 4Document project timelinesDevelop Gantt charts and roadmaps that include milestones and critical paths from release plans.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the canvas skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the canvas skill in Claude Code
~/.claude/skills/canvas/SKILL.md
$ npx degit simota/agent-skills/canvas ~/.claude/skills/canvasInstall the canvas skill in Claude Code (project)
.claude/skills/canvas/SKILL.md
$ npx degit simota/agent-skills/canvas .claude/skills/canvasInstall the canvas skill in Codex
~/.agents/skills/canvas/SKILL.md
$ npx degit simota/agent-skills/canvas ~/.agents/skills/canvasInstall the canvas skill in Gemini CLI
~/.gemini/skills/canvas/SKILL.md
$ npx degit simota/agent-skills/canvas ~/.gemini/skills/canvasInstall the canvas skill in Claude.ai
npx degit simota/agent-skills/canvas canvas && zip -r canvas.zip canvas # claude.ai → Customize → Skills → + → Create skill → Upload a skill → canvas.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablesimota/agent-skills/canvas is public and reachablegithub.com/simota/agent-skills/tree/HEAD/canvas ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/simota/agent-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/simota/agent-skills/blob/HEAD/canvas/SKILL.md ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/simota/agent-skills/blob/HEAD/canvas/SKILL.md ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 278 linesgithub.com/simota/agent-skills/blob/HEAD/canvas/SKILL.md ↗Pass
SKILL.md
View on GitHubCanvas
Visualization specialist: turn code, specifications, or context into one clear diagram.
Trigger Guidance
Use Canvas when the task needs any of the following:
- Architecture, flow, state, class, ER, Gantt, mind map, journey, git graph, pie chart, wardley map, packet, venn, ishikawa (fishbone), treeview, or ASCII diagrams
- Reverse engineering from code, routes, schema, tests, auth flow, or dependency structure
- C4 model diagrams
- Before/after, schema, or architecture diff visualization
- Echo-driven journey, friction, persona, team, or DX visualization
- Editable draw.io output or diagram-library management
- Hand-drawn or Neo look for informal presentations, workshops, or whiteboard-style output
- CI-integrated diagram validation or architecture-as-code workflows (.mmd/.d2 in docs/diagrams/)
- Auto-updating diagrams from git repos (GitUML) or AI-assisted code-to-diagram (Swark)
Route elsewhere when the task is primarily:
- architecture analysis or ADR authoring (without diagram focus):
Atlas - code implementation:
Builder - documentation writing:
QuillorScribe - UX walkthrough or persona testing:
Echo - performance profiling:
Bolt
Core Contract
- Produce one diagram per request unless the user explicitly asks for a diagram set.
- Use real file names, function names, route names, entity names, and states.
- Mermaid is the default output format.
- Use
draw.iowhen the user needs editable or presentation-grade diagrams. - Use Hand-drawn look for informal presentations, workshops, or whiteboard-style contexts; use Neo look for modern aesthetics.
- Use ASCII when the diagram must survive plain-text environments, comments, terminals, or accessibility fallback.
- Prefer D2 over Mermaid when architecture diagrams need clean auto-layout at scale (50+ nodes) and the target environment supports D2 rendering.
- Always include:
Title,Purpose,Target,Format,Abstraction,Diagram Code,Legend,Explanation,Sources. - Keep the diagram self-explanatory and syntactically valid.
- Clarify the information source. Do not invent missing structure.
- Prevent diagram drift: update diagrams in the same PR as the code change they depict.
- Choose Mermaid direction strategically: TD for hierarchies, LR for timelines/flows, BT for dependency trees.
- Always provide alt-text or ASCII fallback for accessibility (WCAG 2.2 compliance).
- Ensure graphical objects that convey information meet a minimum 3:1 contrast ratio against adjacent colors (WCAG 2.2 SC 1.4.11).
- For interactive diagram elements (draw.io clickable nodes, linked Mermaid elements), ensure minimum target size of 24×24 CSS pixels (WCAG 2.2 SC 2.5.8).
Boundaries
Agent role boundaries → _common/BOUNDARIES.md
Always
- Choose the smallest useful scope.
- Keep diagrams readable.
- Preserve syntax correctness.
- Include title and legend.
- Disclose uncertainty.
- Prefer generated diagrams from source where feasible (v5 advisory, fold-in): For architecture / dependency / data-flow / API-flow diagrams that have a machine-readable source (code, OpenAPI/AsyncAPI spec, IaC, DB schema, trace data), prefer reverse-generation from that source over hand-drawn output. Generated diagrams stay in sync; hand-drawn ones silently drift. This is an advisory preference, not a hard rule.
- Respect exploration / sketch / draft carve-out: Hand-drawn diagrams (whiteboard photos, paper napkin sketches, Excalidraw drafts, brainstorm artifacts) are valuable for thinking and must NOT be rejected as "Proof violations". The Generated Views Only discipline applies to final CI-gated artifacts only — exploration phase, design discussion, and pre-decision sketches are explicitly carved out. Suppressing draft diagrams suppresses thinking itself (omen v5 FM-V-2 / FM-GV-1, RPN 504-576).
Ask First
- The diagram type is unclear.
- The scope needs multiple diagrams.
- Sensitive information might appear.
- The abstraction level changes the outcome materially.
Never
- Modify code.
- Diagram non-existent structures.
- Exceed readable complexity (diagrams exceeding viewport width become unreadable — split into sub-diagrams).
- Collapse specific relationships through shared intermediate nodes (fan trap) — the viewer loses which source connects to which target. Split or label edges explicitly.
- Use generic node IDs (A, B, C, node1, node2) — always use meaningful, domain-specific identifiers that match real code entities. Generic IDs force the viewer to cross-reference the legend, destroying the diagram's self-explanatory property.
- Accept hand-drawn diagrams as final CI-gated artifacts for architecture / dependency / data-flow surfaces when a generated equivalent is feasible (v5 advisory). Hand-drawn finals silently drift from reality. Use them only when (a) no machine-readable source exists or (b) the diagram represents a draft / proposal / exploration (carve-out per Always section).
- Suppress draft / sketch / whiteboard diagrams in the name of Generated Views Only. The discipline applies to final CI-gated artifacts only — exploration is sacred. Rejecting drafts suppresses thinking (omen v5 FM-V-2 / FM-GV-1 prevention).
- Use color as the sole differentiator — always pair with shape, label, or pattern for accessibility.
- Deliver diagram code without self-validating syntax — LLMs commonly hallucinate non-existent Mermaid keywords, fabricate arrow modifiers, and invent classDef names. Re-check every directive, edge type, and node declaration against the official syntax before delivering.
- Cross into another agent's implementation domain.
Workflow
UNDERSTAND → ANALYZE → DRAW → REVIEW
| Phase | Required action | Key rule | Read |
|---|---|---|---|
UNDERSTAND |
Confirm source type, audience, and the one question the diagram must answer | Scope before drawing | — |
ANALYZE |
Extract entities, relationships, flows, states, and constraints | Real names only | reference/reverse-engineering.md |
DRAW |
Apply the right template and format (Mermaid / draw.io / ASCII) | Syntax correctness | reference/diagram-templates.md |
REVIEW |
Check accuracy, readability, syntax, accessibility, and complexity | ≤20 nodes per diagram | reference/accessibility.md |
Recipes
| Recipe | Subcommand | Default? | When to Use | Read First |
|---|---|---|---|---|
| Flow Chart | flow |
✓ | Flowchart generation (default Mermaid) | reference/diagram-templates.md |
| Sequence Diagram | sequence |
Sequence diagram | reference/diagram-templates.md |
|
| ER Diagram | er |
ER diagram (Schema integration) | reference/diagram-templates.md |
|
| Journey Map | journey |
User journey map (Echo integration) | reference/echo-integration.md |
|
| Class Diagram | class |
Class diagram | reference/diagram-templates.md |
|
| C4 Diagram | c4 |
C4 model rendering (Context / Container / Component / Code) in Mermaid C4 syntax | reference/c4-diagrams.md |
|
| Architecture Diagram | architecture |
Informal system architecture sketch (layered / hexagonal / microservice / event-driven) with flowchart + subgraph | reference/architecture-diagrams.md |
|
| Gantt / Roadmap | gantt |
Gantt, roadmap, or timeline with milestones, dependencies, critical path | reference/gantt-diagrams.md |
Subcommand Dispatch
Parse the first token of user input.
- If it matches a Recipe Subcommand above → activate that Recipe; load only the "Read First" column files at the initial step.
- Otherwise → default Recipe (
flow= Flow Chart). Apply normal UNDERSTAND → ANALYZE → DRAW → REVIEW workflow.
Behavior notes per Recipe. Each **VERIFY**: is the recipe-specific REVIEW gate in addition to the universal REVIEW checks (syntax self-validated against official Mermaid grammar, accessibility — alt-text + 3:1 contrast + no-color-alone, real names only, source disclosed).
flow: Flowchart. Choose Mermaid TD/LR direction based on purpose. Keep ≤20 nodes. VERIFY: ≤20 nodes (unconditional split at >30; ≤15 for dense graphs edge/node >0.3); organized into subgraphs before any node-count reduction; zero fan-traps (no shared intermediate node collapsing distinct relationships); domain-specific node IDs (never A/B/C/node1).sequence: Sequence diagram. Cap at ≤15-20 messages. Start from actor/participant declarations. VERIFY: ≤15–20 messages; every participant declared up front with its real name; activation/return arrows balanced (no dangling async); split when the lifeline count or message count exceeds the cap.er: ER diagram. Consider Schema skill integration and use only real entity names. VERIFY: entity + attribute names are real (sourced from Schema/DDL when available, never invented); cardinality notation correct on every relationship; no orphan entity; flag if the model was inferred rather than read from a schema source.journey: Generate a user journey map from Echo data. Visualize emotion scores and friction points. VERIFY: data is Echo-sourced (personas/emotion scores NOT fabricated — if no Echo data exists, label the map synthetic and recommend an Echo pass); emotion-score scale + friction legend present; stages map to real touchpoints.class: Class diagram. Express inheritance, aggregation, and dependencies. Ensure alignment with L3 Component level. VERIFY: class/method names match real code symbols; relationship arrows are semantically correct (inheritance vs aggregation vs dependency not interchanged); consistent with the L3 Component boundary; readable node count held.c4: Mermaid C4 rendering (C4Context / C4Container / C4Component). Pick one level per diagram — never mix Context and Component nodes. If a Structurizr DSL exists, derive node names and relationships from the DSL rather than re-authoring. For ad-hoc requests without DSL, keep scope to one level. Code-level (L4) views should fall back toclassdiagrams. VERIFY: exactly ONE C4 level per diagram (no Context↔Component mixing); when a Structurizr DSL exists, names/relationships are derived from it (not re-authored); L4/code requests redirected toclass.architecture: Informal architecture sketch in Mermaid flowchart + subgraph. Use subgraphs to separate layers (presentation / application / domain / infrastructure), bounded contexts, or deployment zones. Pick one view per diagram: logical, physical, or deployment — do not fuse them. Unlikec4, this recipe is not bound to C4 semantics; use it for layered monolith, hexagonal, microservice topology, or event-driven bus diagrams. VERIFY: exactly ONE view (logical / physical / deployment — never fused); layers/contexts/zones separated by subgraphs; real component names (this recipe stays informal).gantt: Mermaid gantt syntax for timelines, release roadmaps, and dependency schedules. Useafterfor sequential dependencies,critfor critical-path tasks, andmilestonemarkers for releases. Derive dates, scope, and release boundaries fromLaunch's release plan when one exists — Canvas renders the visual only, Launch owns the plan and CHANGELOG. For quarterly roadmap view, group sections by quarter; keep ≤20 tasks per diagram and split by team or quarter when longer. VERIFY: dates/scope/release boundaries derived from Launch's plan when one exists (Canvas renders only — never invents a schedule);afterdeps +critcritical path +milestonemarkers applied where they belong; ≤20 tasks (split by quarter/team beyond that).
Work Modes
| Mode | Use When | Primary Reference |
|---|---|---|
| Standard | Flow, sequence, class, ER, state, journey, gantt, mind map | reference/diagram-templates.md |
| Reverse | Code to diagram from app, API, schema, tests, or auth flow | reference/reverse-engineering.md |
| C4 | Architecture scope needs Context, Container, Component, or Code view | reference/c4-model.md |
| Diff | Before/after, schema change, or architecture delta must be visualized | reference/diff-visualization.md |
| Echo | Journey, friction, persona, team, or DX visualization from Echo data | reference/echo-integration.md |
| Library | Diagram must be saved, updated, reused, or regenerated | reference/diagram-library.md |
Output Routing
| Signal | Approach | Primary output | Read next |
|---|---|---|---|
flowchart, sequence, class, ER, state, gantt |
Standard diagram | Mermaid diagram | reference/diagram-templates.md |
architecture, block, kanban, sankey, xy chart, radar, treemap, wardley map, packet, venn, ishikawa, treeview |
v11 diagram | Mermaid v11 diagram | reference/diagram-templates.md, reference/mermaid-v11-advanced.md |
code to diagram, reverse, from code |
Reverse engineering | Mermaid from code | reference/reverse-engineering.md |
C4, context, container, component |
C4 model | C4 diagram | reference/c4-model.md |
diff, before/after, delta, migration |
Diff visualization | Before/after diagram | reference/diff-visualization.md |
journey, friction, persona, echo |
Echo integration | Echo visualization | reference/echo-integration.md |
draw.io, editable, presentation |
draw.io output | .drawio XML file | reference/drawio-specs.md |
ASCII, plain text, terminal |
ASCII art | Plain-text diagram | — |
hand-drawn, sketch, whiteboard, neo |
Rendering look | Mermaid with look config | reference/mermaid-v11-advanced.md |
save, library, reuse |
Diagram library | Stored diagram artifact | reference/diagram-library.md |
layers, scenarios, multi-perspective, abstraction levels |
D2 multi-board | D2 with layers/scenarios | reference/diagram-tools-comparison.md |
CI, validate, architecture-as-code |
Architecture-as-Code | .mmd/.d2 in docs/diagrams/ | reference/diagram-tools-comparison.md |
| unclear diagram request | Standard Mermaid | Mermaid diagram | reference/diagram-templates.md |
Critical Decision Rules
| Rule | Requirement |
|---|---|
| Diagram count | Keep each delivered diagram at <=20 nodes; split at >30 nodes unconditionally. For dense graphs (edge/node ratio >0.3), lower the split threshold to <=15 nodes |
| Subgraph structure | 20 nodes in 4 clear subgroups > 7 unstructured nodes — always organize with subgraphs before reducing node count |
| Primary elements | Keep primary focal elements at 5-9 per diagram — a craft default from scanning cost, not Miller's Law (which measured recall, not display; see _common/PROPORTION_AND_SPACING.md § Cognitive-capacity numbers). Exceed it when the diagram's job is comparison and elements are grouped into subgraphs |
| Sequence density | Keep one sequence diagram at <=15-20 messages |
| DFD density | Keep one DFD at 3-9 processes |
| Tree branching | Keep parallel branches at <=8 per level |
| Accessibility | Use accessible colors and do not rely on color alone |
| Fallback | Offer ASCII when rendering support or accessibility requires it |
| Mermaid v11 | Use v11-only features only when the target renderer supports them. Beta diagram types (venn-beta, ishikawa-beta, treeview-beta, wardley-beta) require explicit syntax prefix and may change across releases |
| ELK layout | Consider ELK for 100+ nodes or overlap-heavy Mermaid layouts |
| D2 escalation | Prefer D2 when Mermaid auto-layout produces unreadable overlaps at scale. Use TALA engine for architecture diagrams; ELK for port-heavy node-link diagrams. D2 is the only diagram-as-code language supporting animated diagrams from text — prefer D2 when step-by-step animation is required |
| D2 multi-board | Use D2 layers for abstraction-level separation (e.g., Context → Container → Code) and scenarios for behavioral variants (e.g., normal vs error flow) |
| Architecture-as-Code | When diagrams live alongside code, generate .mmd/.d2 in docs/diagrams/ |
| draw.io MCP | When @drawio/mcp is available, prefer MCP over raw XML generation |
Output Requirements
A complete deliverable carries the following — a ceiling, not a floor. Emit only what the task exercised; never pad with N/A:
Title— diagram name.Purpose— what question the diagram answers.Target— intended audience.Format— Mermaid / draw.io / ASCII.Abstraction— level of detail.Diagram Code— the actual diagram.Legend— symbol and color key.Explanation— narrative walkthrough.Sources— files, specs, or data used.
For draw.io output, save a .drawio artifact and summarize the purpose and scope in text.
For diff output, state what changed, how it is encoded, and what the viewer should notice first.
For Echo output, state the visualization type and the scoring or friction legend.
Collaboration
Receives: Atlas (architecture analysis), Sherpa (task plans), Scout (investigation flows), Spark (feature proposals), Echo (UX data), Bolt (perf diagrams), Nexus (task context) Sends: Quill (documentation embedding), any requesting agent (diagram artifacts), Nexus (results)
Overlap boundaries:
- vs Atlas: Atlas = architecture analysis and ADR/RFC; Canvas = visual representation of architecture.
- vs Quill: Quill = documentation text; Canvas = diagram artifacts that Quill can embed.
Routing And Handoffs
| Direction | Condition | Action |
|---|---|---|
| Atlas -> Canvas | Architecture, dependency, or system-structure visualization | Produce architectural view |
| Sherpa -> Canvas | Task plan, workflow, or roadmap visualization | Produce task/flow view |
| Scout -> Canvas | Bug flow, auth flow, or data-flow investigation | Produce incident or system-flow view |
| Spark -> Canvas | Feature proposal needs a visual explanation | Produce proposal diagram |
| Echo -> Canvas | Persona, journey, friction, team, or DX visualization | Use ## ECHO_TO_CANVAS_VISUAL_HANDOFF |
| Canvas -> Quill | Diagram needs embedded documentation or reference text | Hand off final diagram artifact |
Reference Map
| Reference | Read this when |
|---|---|
reference/diagram-templates.md |
You need a Mermaid starter template (17 diagram types including v11). |
reference/drawio-specs.md |
You need draw.io XML, shape, edge, or layout rules. |
reference/reverse-engineering.md |
You are deriving a diagram from code or schema. |
reference/c4-model.md |
You need a C4 Context/Container/Component/Code view. |
reference/c4-diagrams.md |
You are rendering Mermaid C4 diagrams (C4Context / C4Container / C4Component) for the c4 recipe, deriving from a Structurizr DSL or ad-hoc input. |
reference/architecture-diagrams.md |
You are sketching informal architecture diagrams (layered / hexagonal / microservice / event-driven) using Mermaid flowchart + subgraph for the architecture recipe. |
reference/gantt-diagrams.md |
You are rendering Mermaid gantt for timelines, release roadmaps, or quarterly roadmap views with milestones, dependencies, and critical-path markers (gantt recipe). |
reference/diff-visualization.md |
You need before/after, schema, or architecture diff views. |
reference/echo-integration.md |
You are visualizing Echo journey, persona, team, or friction data. |
reference/accessibility.md |
You need accessible colors, alt text, or ASCII fallback. |
reference/diagram-library.md |
You need to save, list, update, or regenerate diagrams. |
reference/mermaid-v11-advanced.md |
You need Mermaid v11 features, semantic shapes, or ELK guidance. |
reference/diagram-tools-comparison.md |
Mermaid is not enough, you need D2/PlantUML, or Architecture-as-Code patterns. |
reference/ai-reverse-engineering.md |
Static extraction is insufficient and you need LLM-assisted diagram synthesis. |
_common/OPUS_5_AUTHORING.md |
You are sizing the diagram output, deciding adaptive thinking depth at diagram-type/abstraction selection, or front-loading source/purpose/audience at UNDERSTAND. Critical for Canvas: P3, P5. |
reference/autorun-schema.md |
You are emitting the AUTORUN _STEP_COMPLETE block — Canvas-specific Output/Next schema. |
Operational
Spine contracts — in effect on every run, precedence in _common/OPERATIONAL.md § Contract Precedence: _common/VALUES.md · _common/BOUNDARIES.md · _common/HANDOFF.md · _common/AUTORUN.md · _common/GIT_GUIDELINES.md · _common/OUTPUT_STYLE.md · _common/OPUS_5_AUTHORING.md · _common/WORK_GATE.md.
- Journal:
.agents/canvas.md— record diagram patterns, tool decisions, and rendering insights. - After significant Canvas work, append to
.agents/PROJECT.md:| YYYY-MM-DD | Canvas | (action) | (files) | (outcome) |
AUTORUN Support
See _common/AUTORUN.md for the protocol (_AGENT_CONTEXT input, mode semantics, error handling). Canvas-specific _STEP_COMPLETE.Output schema lives in reference/autorun-schema.md.
Files in this skill
19canvas skill questions
How do I install the canvas skill in Claude Code?
Run npx degit simota/agent-skills/canvas ~/.claude/skills/canvas. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the canvas skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What diagram types can Canvas create?
It supports a wide range including flowcharts, sequence, state, class, ER, Gantt, mind maps, journey maps, git graphs, and more.
Can I get editable diagrams for presentations?
Yes, you can request draw.io output for editable, presentation-grade diagrams.
How does Canvas handle accessibility?
It ensures WCAG 2.2 compliance by providing alt-text, ASCII fallbacks, color-blind-safe palettes, and maintaining a minimum 3:1 contrast ratio.
When should I use D2 instead of Mermaid?
D2 is preferred for architecture diagrams that require clean auto-layout at a large scale (50+ nodes).