Pencil

pencil — pencil.dev integration layer

This skill is the integration layer between a screen spec and a real pencil.dev screen. ux-design (or a user) hands it a spec; it drives the Pencil MCP server to create/update the corresponding design on Pencil's infinite canvas, then hands back a reference to the artifact.

ux-design  →  [screen spec]  →  pencil (this skill)  →  Pencil MCP  →  .pen screen + screenshot ref

Honesty contract. Pencil's MCP runs locally and its design files are .pen files in the workspace (verified from docs). A hosted shareable URL is not documented — do not promise one. Return whatever the MCP actually gives back (file path, screen/element id, screenshot). See references/capability-map.md for what is verified vs. unverified.

Core rules

• Discover, don't hardcode. Find the Pencil MCP tools at runtime (Step 1). Tool names below are the documented set, but always confirm against what the host actually exposes — schemas drift.
• Degrade gracefully — never fail hard. No Pencil MCP connected → say so plainly and emit the textual spec as the deliverable. A partial canvas still beats a hard error.
• Treat the spec as the source of truth. Map every spec field to a design operation; report any field you could not realize on the canvas.
• No secrets in chat. Pencil auth is handled by the host/extension; never ask the user to paste tokens.

References (load only what the step needs)

Workflow (follow in order)

Step 1 — Discover the Pencil MCP at runtime

Do not assume the tool names. Detect what's actually connected:

1. If a tool-search facility exists (e.g. ToolSearch), query for pencil / batch_design / get_editor_state to surface Pencil MCP tools and their real schemas.
2. Otherwise, inspect the available MCP tools the host exposes (in Claude Code/Codex, MCP tools are namespaced like mcp__pencil__<tool>; the user can run /mcp to confirm Pencil is listed).
3. Match what you find against the expected capability map in references/capability-map.md.

If no Pencil tool is found → jump to Step 5 (degrade gracefully). Do not invent calls.

Step 2 — Ingest & normalize the screen spec

Accept the spec from ux-design or the user. Normalize it to: screen name, layout (structure/regions/grid), components (with hierarchy), states (default/empty/loading/error/…), and content (copy, sample data). If any of these is missing, fill sensible defaults and note the assumption — don't block. Read references/spec-to-screen.md for the field→operation mapping.

Step 3 — Read current canvas context (idempotent updates)

Before writing, read the editor/canvas state so you create-or-update instead of duplicating:

• Use the discovered read tool (documented: get_editor_state for active file/selection, and batch_get to search existing elements/components by name/pattern).
• If a screen with this name already exists, plan an update; otherwise plan a create.

Step 4 — Generate / update the screen, then verify

• Apply the spec via the discovered write tool (documented: batch_design — insert/update/ move/replace/delete operations; can also generate images). Build the layout, place components in hierarchy, set content, and represent each state (e.g. as separate frames/variants — see references/spec-to-screen.md).
• Verify visually with the discovered screenshot tool (documented: get_screenshot) and the layout checker (documented: snapshot_layout) to catch overlaps/positioning issues. Iterate once if the render diverges from the spec.
• Sync theme/tokens only if the spec demands it (documented: get_variables / set_variables).

TODO: FILL WHEN PENCIL MCP CONNECTED — confirm the exact operation verbs and required parameters of batch_design (e.g. the shape of an "insert frame" / "insert component" op) against the live schema before relying on them. The names are documented; the precise argument objects are not fully published — read them from the runtime tool schema in Step 1.

Step 5 — Return the artifact (or degrade)

If the MCP ran: return what Pencil actually produced —

• the screen / frame reference (the .pen file path and/or the element/screen id),
• the screenshot from get_screenshot when available,
• a short note of any spec field that couldn't be realized.

TODO: FILL WHEN PENCIL MCP CONNECTED — if a future Pencil version exposes a hosted/shareable URL for a screen, surface it here as the primary deliverable. As of the documented version, no such URL exists; do not fabricate a link — return the .pen reference + screenshot instead.

If no MCP was connected (graceful degradation): state clearly "No Pencil MCP server is connected, so I did not create a real screen." Then emit the normalized textual spec (the Step 2 output) as the deliverable so ux-design/the user still gets value, plus one line on how to connect Pencil (see README.md → "Connect the Pencil MCP"). Never throw a hard error.

Output format

Return: Status (created / updated / degraded-textual) · Artifact (.pen path + screen id, or the textual spec) · Screenshot (if any) · Unrealized spec fields (if any) · Next step.