| name | pencil-agent-skill |
| description | Use the Pencil Workbench to create and edit vector graphics, including illustrations, diagrams, and UI components, with human review. |
Use this skill when you are working with the Pencil Agentic App, the Pencil Workbench, or tools named pencil_*.
System Of Record
- Pencil middleware tools are the persistence path. Do not claim a design is saved, imported, exported, reviewed, archived, or versioned until the matching tool succeeds.
- Prefer the current Workbench document from
env.pencilDocumentId or pencilContextJson.
- Mutating Pencil core tools update the working copy. They do not create a version. Use
pencil_save_version for durable review checkpoints.
- Use
pencil_create_sample_document when the user wants a realistic starting case or asks to verify the app with real dashboard data.
Workbench Context
Workbench state variables may include:
pencilDocumentId: selected document.pencilVersionId: selected version.pencilNodeId: selected node.pencilSelectionJson: compact selection context.pencilContextJson: compact document, version, and graph context.pencilDirty: local dirty state.
When context is present, parse it before choosing tools. Only create a new document when no current document exists or the user explicitly asks for a new one.
File Import And Export
- Import
.fig and .pen with pencil_import_file.
- Pass
/workspace/..., workspace-relative paths, or portable file references directly.
- Export with
pencil_export_file. Return the workspace path/reference, MIME type, size, and sha256.
- Do not return large base64 payloads to the user.
Node Editing
- Before creating a new design, call
pencil_list_typography_presets, choose one preset for the content and language, and use only its returned managed font family names. Do not invent font URLs.
- Call
pencil_get_document before modifying existing user-edited documents.
- Call
pencil_get_node before targeted edits to a selected node.
- Use selected
pencil_* core tools for layout, style, structure, variables, analysis, and node reads/writes.
- For complex pages, render a small empty root frame first, then add one major region per
pencil_render call with parent_id and insert_index. Keep the returned node ids for targeted follow-up work.
- Use
replace_id to replace one placeholder or incorrect region. Do not regenerate an already successful page merely because another region failed.
- When using
pencil_render, write OpenPencil JSX with flex="col" or flex="row" for auto-layout direction. Use gap, p/px/py/pt/pr/pb/pl, w/h, bg, rounded, stroke, and strokeWidth props. Do not use flow for auto-layout direction; flow is reserved for reading direction.
- If
pencil_render returns success=false, recoverable=true, and a renderDraftId, call pencil_render_patch. Pass the returned revision and replace only the smallest uniquely matching oldText fragment. Never resend the complete JSX while an active draft is available.
- A failed render draft does not modify the document. A successful patch commits exactly one new working-copy revision.
- For complex auto-layout changes, prefer
pencil_set_layout and pencil_set_layout_child, then read the document summary before saving a version.
- Always pass
documentId.
- Keep
changeSummary short and operational.
Failure Recovery
If an import, export, graph edit, or save fails:
- For a recoverable render diagnostic, repair its retained source with
pencil_render_patch before reporting a terminal failure.
- Record unrecoverable failures with
pencil_report_failure.
- Tell the user what failed and whether it is recoverable.
- Suggest a concrete next step, such as reloading the document, saving the current working copy, or retrying with a smaller target selection.
