pencil-designlisted

# Pencil Design (general-purpose) Hard-won notes for working with `.pen` files via the Pencil MCP server (`mcp__pencil__*`) or the headless `pencil` npm CLI. Project-specific skills (e.g. cuttlefish's `pencil-design`) override this one inside their own repo and add brand rules, component inventories, and design-system paths on top — this skill is the floor that applies everywhere. If a project-specific `pencil-design` skill exists, prefer it. This skill is intentionally generic. ## Reading .pen files - `.pen` files are encrypted JSON. **Never** use `Read`, `Grep`, or `cat` on them — you get binary garbage and waste a tool turn. - ALWAYS use `mcp__pencil__batch_get` to inspect node structure. - Use `mcp__pencil__get_screenshot` to visually verify the result. - `mcp__pencil__get_editor_state` lists open documents, available reusable components, and selection. ## Saving new .pen files (the gotcha that always bites) `mcp__pencil__open_document` on a non-existent path opens the file **in the desktop editor's memory only** — it does NOT create the file on disk. Existing files auto-save on edits, but **new files never touch disk until you Cmd+S**. The MCP has no save tool. Workaround — trigger Cmd+S via AppleScript after the first edit batch: ```bash osascript -e 'tell application "Pencil" to activate' osascript -e 'tell application "System Events" to keystroke "s" using command down' ``` After saving, verify with `ls` before committing — otherwise pre-commit fails with `no