# Excalidraw Generator

> Generate professional diagrams as valid Excalidraw JSON files — flowcharts, architecture, ER diagrams, mind maps, sequence diagrams, wireframes, C4 models, and more. Understands text, code, schemas, or verbal descriptions. Don't use for draw.io/Mermaid output, polished production slide decks, or pixel-perfect brand graphics.

- **Type:** Skill
- **Install:** `agentstack add skill-luongnv89-skills-excalidraw-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [luongnv89](https://agentstack.voostack.com/s/luongnv89)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [luongnv89](https://github.com/luongnv89)
- **Source:** https://github.com/luongnv89/skills/tree/main/skills/excalidraw-generator
- **Website:** https://luongnv.com

## Install

```sh
agentstack add skill-luongnv89-skills-excalidraw-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Excalidraw Diagram Generator

Generate professional diagrams as valid Excalidraw JSON. Every diagram goes through four phases: **Understand** the request, **Propose** options, **Generate** the JSON, and **Validate** before writing the file.

This SKILL.md is intentionally compact to fit the agent's context budget (token-efficient body). Long-form details live in `references/` — read the linked file when you need depth.

## When to Use

Use when the user asks for a diagram, flowchart, architecture sketch, ER/class/sequence diagram, mind map, wireframe, or C4 model and wants the output as an Excalidraw file (or embedded in Markdown via the `excalidraw` fenced block).

## Environment Check

If the Agent tool is available, use the subagent review loop described in `references/style-and-iteration.md` (Subagent Architecture). It provides fresh-context validation and avoids single-pass context overflow.

If the Agent tool is unavailable (e.g., Claude.ai), execute every phase inline and self-review against the 10 checks (less rigorous, but functional).

## Core Workflow

### Phase 1: Understand

Confirm what to draw before generating anything.

- **Clear description** ("draw a flowchart of user authentication"): restate your understanding in one sentence and propose the visualization type.
- **Ambiguous input**: ask targeted questions — main entities/nodes, relationships, flow direction, style preference.
- **Code, data, schemas, or files**: extract structure (code → class/dependency/architecture; SQL → ER; JSON/YAML → architecture/deployment; steps → flowchart/sequence; org data → org chart/tree).

### Phase 2: Propose

Present a plan with selectable options:

1. **Diagram type** — see `references/diagram-types.md` for the catalogue. If multiple fit, present numbered options.
2. **Key elements** — list the nodes/shapes you'll include.
3. **Layout** — propose 2–3 choices (e.g., `(A) Top-to-bottom`, `(B) Left-to-right`, `(C) Radial`).
4. **Style** — see `references/style-and-iteration.md`. Pick rendering style (clean/hand-drawn/sketchy) and color scheme that fits the diagram's purpose. No fixed palette.
5. **Complexity** — small (= min_shape_height`.
5. The container shape's `width` must be `>= longest_line_pixel_width + 20`.

Boundary/container labels (e.g., "System Boundary") must be standalone text with `containerId: null`, positioned near the top-left of the container — never bound to it.

**Fix**: increase the shape's height/width to fit the text and shift elements below it to keep spacing. Always set `lineHeight: 1.25` and `autoResize: true` on text. Never patch individual outputs — fix this skill's instructions if a new failure pattern emerges.

After all checks pass, emit the validation summary (10/10 passed, element counts, binding counts, "all shapes sized to fit", any auto-fixes applied).

## Step Completion Reports

After each phase, output a status block. Templates and check labels for each phase live in `references/step-reports.md`. Result line is `PASS | FAIL | PARTIAL`.

## Expected Output

For "draw a flowchart of the user login process": file `login-flow.excalidraw` containing valid Excalidraw JSON, plus a validation summary in the response. Example fragment:

```json
{
  "type": "excalidraw", "version": 2, "source": "https://excalidraw.com",
  "elements": [
    {"id": "start-1", "type": "ellipse", "x": 300, "y": 40, "width": 120, "height": 56,
     "boundElements": [{"id": "txt-start", "type": "text"}]},
    {"id": "txt-start", "type": "text", "text": "Start", "fontSize": 18, "fontFamily": 1,
     "containerId": "start-1", "lineHeight": 1.25, "autoResize": true}
  ],
  "appState": {"theme": "light", "viewBackgroundColor": "#ffffff"}, "files": {}
}
```

Expected response includes:
```
Validation: 10/10 checks passed
- Elements: 6 shapes, 6 text labels, 5 arrows
- Bindings: 6 text bindings, 10 arrow bindings (all two-way)
- Text fits: all shapes sized to fit their bound text
- No overlaps, no missing fields
```

## Edge Cases

- **30+ elements** — spawn the subagent review loop in `references/style-and-iteration.md`; cap at 3 fix cycles.
- **Text-heavy nodes** — apply Check 10 strictly; bigger shapes, never smaller text.
- **Ambiguous relationships** — ask before guessing; saves a regeneration cycle.
- **"Just do it"** — defaults (hand-drawn, roughness 1, Virgil, best-fit layout); skip the proposal.
- **Iteration on an existing file** — read the file, preserve unchanged IDs, modify only the requested parts, rewrite.

See `references/style-and-iteration.md` for extended edge cases, iteration patterns, and style variants.

## Acceptance Criteria

- [ ] Output file is valid JSON with top-level `type`, `version`, `elements`, `appState`, `files`.
- [ ] Every element has all required fields (per `references/validation-checks.md` Check 2).
- [ ] Text elements have `fontSize >= 16`, `lineHeight: 1.25`, `autoResize: true`.
- [ ] All element IDs are unique.
- [ ] Text-to-shape bindings are two-way (`containerId` ↔ `boundElements`).
- [ ] Arrow bindings are two-way (`startBinding`/`endBinding` ↔ `boundElements`).
- [ ] Every arrow has `points[0] === [0,0]` and length ≥ 2.
- [ ] No bounding boxes overlap by more than 10px (outside groups/frames).
- [ ] Every entity/relationship from the user's request is represented.
- [ ] Every container shape is sized to fit its bound text (Check 10).
- [ ] Validation report (10/10 summary) is included in the response.

## Supported Diagram Types

Full catalogue with layout guidance: `references/diagram-types.md`. Categories: Flow & Process, Architecture, Data & Relationships, Planning, Comparison, Data Viz, UX/Design, Custom. If the request doesn't map cleanly to one type, propose the closest fit and explain why.

## References

- `references/validation-checks.md` — full text of all 10 Phase-4 checks plus fix recipes.
- `references/excalidraw-format.md` — Excalidraw JSON schema and field defaults.
- `references/diagram-types.md` — diagram-type catalogue with layout guidance.
- `references/style-and-iteration.md` — style variants, iteration patterns, subagent architecture, extended edge cases.
- `references/step-reports.md` — step completion report templates per phase.
- `agents/json-generator.md`, `agents/json-validator.md`, `agents/json-fixer.md` — subagent specs for the large-diagram review loop.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [luongnv89](https://github.com/luongnv89)
- **Source:** [luongnv89/skills](https://github.com/luongnv89/skills)
- **License:** MIT
- **Homepage:** https://luongnv.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-luongnv89-skills-excalidraw-generator
- Seller: https://agentstack.voostack.com/s/luongnv89
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.