# Excalidraw Agent > Integrate and automate Excalidraw in React and Next.js apps, convert Mermaid to .excalidraw scenes, merge/normalize .excalidrawlib libraries, and troubleshoot Excalidraw runtime issues. Use when users mention Excalidraw, Mermaid diagrams, .excalidraw or .excalidrawlib files, Excalidraw API props/methods, export/import flows, or host-app collaboration wiring. - Skill: `diegosouzapw/excalidraw-agent` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add diegosouzapw/excalidraw-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/excalidraw-agent/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: diegosouzapw (https://skillmd.com/u/diegosouzapw) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/diegosouzapw/excalidraw-agent --- # Excalidraw Agent ## Overview Use this skill to deliver end-to-end Excalidraw work in host apps: integration, API-driven scene updates, Mermaid conversion, library operations, export/import pipelines, collaboration patterns, and runtime diagnostics. Prefer this workflow: triage the task, load only the relevant reference file, execute using deterministic scripts when possible, validate output, and report exact outcomes. ## Core Workflow 1. Triage the request type. 2. Load only the required reference file(s) from `references/`. 3. Run environment check when scripts are involved: - `scripts/check_env.sh` 4. Execute the task path. 5. Validate the result (script checks + structural checks + behavior checks). 6. Report what changed, what was verified, and remaining risks. ## Task Triage - Installation or framework embedding: load `references/excalidraw-install-and-integration.md` - Props and imperative API usage: load `references/excalidraw-props-and-api.md` - Serialization, restore, and export/import: load `references/excalidraw-utils-restore-export.md` - Editor composition (`MainMenu`, `Sidebar`, `WelcomeScreen`, `Footer`): load `references/excalidraw-ui-composition.md` - Mermaid conversion workflows: load `references/excalidraw-mermaid-conversion.md` - Collaboration architecture and remote update behavior: load `references/excalidraw-collaboration-pattern.md` - Account-linked import/publish via authenticated browser session: load `references/excalidraw-account-linking.md` - Client setup/portability across Codex, Claude Code, Cursor, and Zed: load `references/excalidraw-client-compatibility.md` - Runtime or build failures: load `references/excalidraw-troubleshooting.md` - Skills protocol constraints and metadata behavior: load `references/agent-skills-protocol-notes.md` ## Hard Integration Requirements Apply these on every Excalidraw integration unless the user explicitly asks otherwise: 1. Import Excalidraw stylesheet: - `import "@excalidraw/excalidraw/index.css";` 2. Render in a container with non-zero height and width. 3. Use `excalidrawAPI` callback for imperative control; do not use removed legacy `ref` API patterns. 4. For Next.js, disable SSR for Excalidraw rendering via dynamic import. 5. If self-hosting fonts/assets, set `window.EXCALIDRAW_ASSET_PATH` correctly. ## Script Interfaces Run scripts from this skill root or by absolute path. - `scripts/check_env.sh` - `scripts/mermaid_to_scene.mjs --input --output --font-size --regenerate-ids --pretty ` - `scripts/scene_lint.mjs --input --strict-diagram ` - `scripts/library_merge.mjs --base --other --output --default-status ` - `scripts/import_to_excalidraw.sh --input --destination --kind --mode --session --output-dir --timeout-sec --dry-run --close-on-complete --pwcli ` - `scripts/self_test.sh` ## Deterministic Execution Notes - Scripts resolve Excalidraw dependencies from `process.cwd()` first, then from the skill directory. - Recommended runtime is Node + pnpm. - For conversions and merges, run from a project directory where `@excalidraw/excalidraw` and `@excalidraw/mermaid-to-excalidraw` are available, or install them in a temporary working directory first. - If `@excalidraw/excalidraw` cannot be loaded in the active Node runtime, scripts emit a warning and apply deterministic fallback normalization so workflows continue. - The account-link import script supports multiple agent environments by resolving Playwright in this order: 1. explicit `--pwcli` or `PWCLI` 2. known wrapper paths under `~/.codex`, `~/.claude`, `~/.cursor`, and `~/.config/zed` 3. global `playwright-cli` 4. `npx --yes --package @playwright/mcp playwright-cli` - API-level account linking is not available in this skill. Account linking is implemented as authenticated UI import on `excalidraw.com` or `plus.excalidraw.com`. ## Multi-Agent Compatibility - Core Agent Skills contract is `SKILL.md` + optional `references/`, `scripts/`, and `assets/`. - `agents/openai.yaml` is optional metadata for Codex UX and can be ignored by other clients. - This skill is designed to be portable: all operational instructions are rooted in `SKILL.md`, script paths are skill-root relative, and account-link import can run with any Playwright CLI provider via `--pwcli`. - For client-specific setup and invocation patterns, load `references/excalidraw-client-compatibility.md`. ## Execution Paths ### 1) Embed Excalidraw in a Host App 1. Load `references/excalidraw-install-and-integration.md`. 2. Implement base integration for React/Next.js/Preact as needed. 3. Confirm CSS import and non-zero container dimensions. 4. Validate editor rendering and input behavior. ### 2) Implement API-Driven Scene or UI Behavior 1. Load `references/excalidraw-props-and-api.md`. 2. Use `excalidrawAPI` callback to capture API instance. 3. Use `updateScene` and `captureUpdate` semantics intentionally: - local undoable updates: `IMMEDIATELY` - async grouped updates: `EVENTUALLY` - remote/collab updates: `NEVER` 4. Verify behavior via event subscriptions (`onChange`, pointer handlers). ### 3) Convert Mermaid to `.excalidraw` 1. Load `references/excalidraw-mermaid-conversion.md`. 2. Run conversion: - `node scripts/mermaid_to_scene.mjs --input diagram.mmd --output diagram.excalidraw --font-size 16 --regenerate-ids true --pretty true` 3. Validate output: - `node scripts/scene_lint.mjs --input diagram.excalidraw --strict-diagram true` 4. If parser fallback behavior appears, report which nodes were downgraded. 5. If import layout is unreadable (for example tall single-column collapse), simplify labels/graph, reconvert, and expect a manual arrangement pass in Excalidraw. ### 4) Merge and Normalize Libraries 1. Load `references/excalidraw-utils-restore-export.md`. 2. Merge: - `node scripts/library_merge.mjs --base lib-a.excalidrawlib --other lib-b.excalidrawlib --output merged.excalidrawlib --default-status unpublished` 3. Confirm merged output contains normalized `libraryItems` and expected dedupe behavior. ### 5) Build Collaboration Glue 1. Load `references/excalidraw-collaboration-pattern.md`. 2. Keep transport and persistence in host app; keep editor as client state surface. 3. Apply remote updates with non-undo capture behavior. 4. Verify collaborator map rendering and local-vs-remote conflict handling. ### 6) Troubleshoot Runtime Failures 1. Load `references/excalidraw-troubleshooting.md`. 2. Diagnose by category: SSR/build, CSS/layout, browser quirks, asset path, env flags. 3. Validate fixed state with a minimal reproducible integration. ### 7) Link Generated Content to Excalidraw Account 1. Load `references/excalidraw-account-linking.md`. 2. Run import script in headed mode for interactive login: - `bash scripts/import_to_excalidraw.sh --input diagram.excalidraw --destination plus --mode headed` 3. Complete manual login/MFA at checkpoint. 4. Let script run deterministic import strategy sequence and UI assertions. 5. Confirm persistence checkpoint for `plus` destination. 6. Collect screenshot proof path and `RESULT_JSON` output. ### 8) Configure Skill for a Specific Agent Client 1. Load `references/excalidraw-client-compatibility.md`. 2. Place or symlink the skill directory into the client's skill root. 3. Validate script execution from that environment: - `bash scripts/check_env.sh` - `bash scripts/import_to_excalidraw.sh --input assets/examples/scene-minimal.excalidraw --dry-run true` 4. If Playwright is not discovered automatically, set `--pwcli` explicitly. 5. Confirm the client can load `SKILL.md` and access `references/` and `scripts/`. ## Validation Checklist - Skill metadata and structure validate cleanly. - Script CLIs run with documented flags. - Converted scenes parse and lint successfully. - Merged libraries are normalized and readable by Excalidraw tooling. - Recommendations reference the correct framework constraints (React/Next/Preact). - Cross-client setup guidance is present and does not assume a single agent runtime. ## Skill Maintenance - Keep `SKILL.md` concise and procedural. - Keep deep details in `references/`. - Keep references one hop from `SKILL.md`. - Re-run validation after edits: - `python /scripts/quick_validate.py ` - `skills-ref validate `