pencil-basics_skill

Overview

This skill explains how to work with Pencil MCP design files and tools to read, modify, and generate designs from .pen files. It focuses on safe, recommended workflows using the Pencil MCP API (get_editor_state, batch_get, batch_design, get_screenshot) and on core concepts like node types and the layout system. The guidance emphasizes practical patterns, common operations, and verification steps to avoid corrupting files.

How this skill works

The skill inspects the editor state and reads nodes via batch_get rather than accessing .pen files directly. Changes are applied through batch_design using a small set of operations (I, U, C, R, D, M, G) expressed in a JavaScript-like operations string. After applying changes, use get_screenshot to visually verify results.

When to use it

• Creating a new screen or page from components in a Pencil file
• Reading or enumerating nodes and reusable components with batch_get
• Applying layout, content, or style changes via batch_design operations
• Inserting or generating images into frames using the G operation
• Debugging layout issues and validating fixes with get_screenshot

Best practices

• Call get_editor_state first to confirm active file and selection
• Never read/write .pen files directly; use the MCP tools only
• Limit batch_design to small batches (<= 25 operations) and unique bindings
• Always run get_screenshot after design changes to validate visually
• Use instance path syntax (instanceId/childId) when updating component internals

Example use cases

• Create a new screen: get_editor_state -> batch_get components -> batch_design to assemble -> get_screenshot to confirm
• Update component text: batch_get to locate instance -> batch_design U(instanceId/labelId, {...}) -> get_screenshot
• Duplicate and customize a component: C(sourceId, parentId, { descendants: { labelId: { content: 'New' } } })
• Replace a node type or content: R(oldNodeId, { type: 'text', content: 'Replaced' })
• Apply an AI or stock image into a frame: I(parentId, { type: 'frame', ... }); G(frameId, 'ai'|'stock', 'prompt')