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 <mmd|-> --output <scene.excalidraw> --font-size <n> --regenerate-ids <true|false> --pretty <true|false>
• •scripts/scene_lint.mjs --input <scene.excalidraw> --strict-diagram <true|false>
• •scripts/library_merge.mjs --base <a.excalidrawlib> --other <b.excalidrawlib> --output <merged.excalidrawlib> --default-status <published|unpublished>
• •scripts/import_to_excalidraw.sh --input <path> --destination <plus|excalidraw> --kind <auto|scene|library> --mode <headed|headless> --session <name> --output-dir <path> --timeout-sec <n> --dry-run <true|false> --close-on-complete <true|false> --pwcli <path>
• •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 <path-to-skill-creator>/scripts/quick_validate.py <path-to-skill-dir>
  • •skills-ref validate <path-to-skill-dir>