--- title: "AI dev Skill | zenit Zig UI Docs" description: "A development manual for Claude Code and other AI agents. With it installed, an agent writing zenit UI reaches for existing components first, styles with…" url: https://ui.surf/zenit/docs/guide/ai-skill language: en alternate_zh: https://ui.surf/zenit/zh/docs/guide/ai-skill.md alternate_es: https://ui.surf/zenit/es/docs/guide/ai-skill.md alternate_ja: https://ui.surf/zenit/ja/docs/guide/ai-skill.md alternate_ko: https://ui.surf/zenit/ko/docs/guide/ai-skill.md alternate_fr: https://ui.surf/zenit/fr/docs/guide/ai-skill.md alternate_de: https://ui.surf/zenit/de/docs/guide/ai-skill.md project: zenit v0.1.0-alpha (Zig 0.15.2, macOS) source: https://github.com/version-next/zenit --- # The zenit UI dev Skill A development manual for Claude Code and other AI agents. With it installed, an agent writing zenit UI reaches for existing components first, styles with tokens and recipes, manages state on zenit’s lifetimes, and builds and screenshots its own work before handing it over. ## Download The archive is a standard Agent Skill folder: a short `SKILL.md` entry point holding rules and decision tables, with details split into `references/` that the agent reads only when needed. [Download the Skill.zip · 54 KB](https://ui.surf/zenit/downloads/zenit-ui-dev.zip)[View SKILL.md](https://ui.surf/zenit/downloads/zenit-ui-dev.SKILL.md) zenit-ui-dev/ SKILL.md9.6 KB references/ app-architecture.md7.2 KB components.md8.3 KB macos-native.md8.2 KB pencil-design.md7.8 KB performance.md4.1 KB pitfalls.md8.5 KB project-setup.md8.0 KB state-reactivity.md7.8 KB styling.md5.8 KB ui-tree-layout.md6.1 KB verification.md5.7 KB tools/ design\_diff.ts20.6 KB png.ts3.5 KB shot.ts3.7 KB ## Install 1. **Put it in a skills folder** For yourself, use `~/.claude/skills/` (every project). For a team, commit it to the repo’s `.claude/skills/` so everyone who clones gets it. 2. **Restart the agent session** Claude Code scans skills at session start. Open a new session; `/skills` should list `zenit-ui-dev`. 3. **Ask as usual** Any zenit UI task loads it automatically; you can also say “use the zenit-ui-dev skill”. After downloading, unzip it into your user folder (every project): Unzip into ```zig ~/.claude/skills/ └── zenit-ui-dev/ ├── SKILL.md ├── references/ └── tools/ ``` Or unzip it into the project and commit it (shared with the team): Unzip into ```zig .claude/skills/ └── zenit-ui-dev/ ├── SKILL.md ├── references/ └── tools/ ``` ```sh # Codex and other agents that read AGENTS.md: unpack into the repo and reference it unzip -oq zenit-ui-dev.zip -d .agents/skills echo '- zenit UI: read .agents/skills/zenit-ui-dev/SKILL.md before writing UI code' >> AGENTS.md ``` > NOTE > > **Update it with zenit.** zenit may break its API before 1.0. After upgrading zenit, download the Skill again over the old folder. The Skill records the zenit version it targets, and an agent that finds the project’s API differs trusts the source code. ## What’s inside | File | Contents | | --- | --- | | `SKILL.md` | Entry point: triggers, workflow, hard rules, decision tables and which reference to read when | | `references/app-architecture.md` | Large-app layering, from a production editor: state, views, commands, services | | `references/components.md` | The ui.widgets catalog, both mount forms, a table mapping design elements to components | | `references/macos-native.md` | Menus, shortcuts, file dialogs, clipboard, drag and drop, multi-window, IME | | `references/pencil-design.md` | Pencil (pen.dev) designs: read values over MCP, field mapping, numeric screenshot diff | | `references/performance.md` | Virtual lists, dirty levels, large text, background threads and the main thread | | `references/pitfalls.md` | Symptom, cause and fix entries, collected from zenit and production-app fix history | | `references/project-setup.md` | New project, build.zig / build.zig.zon, .app packaging, forwarding build options | | `references/state-reactivity.md` | bindState / cx.on, Signal / Memo / Effect, Scope lifetime and cleanup | | `references/styling.md` | The Token, styles.zig and recipe layers, themes, the ui.arb escape hatch | | `references/ui-tree-layout.md` | Nodes, flex layout, sizing, updating nodes, visibility, coordinates | | `references/verification.md` | The agent self-check loop: build, screenshot, E2E harness, DevTools, logs | | `tools/design_diff.ts` | Numeric diff of design PNG vs app screenshot, with actionable hints | | `tools/png.ts` | Zero-dependency PNG decoder used by design\_diff | | `tools/shot.ts` | Screenshot any zenit app over file RPC (Retina) | **Components before hand-rolling** Maps each design element to an existing ui.widgets component, so the agent doesn’t rebuild a Button out of boxes. **Lifetimes done right** Rules for bindState, pub deinit, Scope cleanup and page switches. They directly fix the most common leaks, double frees and dangling pointers. **Look before handing over** Has the agent build, run, screenshot and check against the request instead of stopping at “it compiles”. **Pitfalls from a real app** A list of issues drawn from a production app’s fix history, each with its cause and the right approach. ## Recommended: design in Pencil [Pencilpen.dev](https://www.pen.dev/) RECOMMENDED WORKFLOW · PENCIL + SKILL Pair it with Pencil: design, then build with AI We recommend designing in [Pencil](https://www.pen.dev/) and letting your agent build it with this Skill. Flex layout, spacing, radii, type sizes and lucide icons in a .pen file sit close to zenit’s model; the Skill includes a field mapping and a design\_diff tool so the agent ports by the numbers rather than by eye. [About Pencil](https://www.pen.dev/) 1. 01.penPencil design 2. 02MCPAgent reads exact values 3. 03zigzenit code from widgets + tokens 4. 04diffNumeric diff against the design 1. **Connect the Pencil MCP** Enable Pencil’s MCP server in your agent and open the .pen file. The Skill only reads .pen through the MCP, which resolves design variables and computed sizes. A faithful port needs both. 2. **Read values, not pixels** The agent first pulls gap, padding, radius, type size and color with `Get(nodeId, { resolveVariables: true })`, then maps them onto zenit: `fill_container -> .fill()`, `chevron-down -> ui.icons.chevron_down`. 3. **Diff until it matches** Export the design at scale 2, capture the real window with `tools/shot.ts`, and `tools/design_diff.ts` reports offset, size delta, a heat map and palette drift; the agent fixes from the hints, about 5 s per round. ```sh SKILL=~/.claude/skills/zenit-ui-dev bun $SKILL/tools/design_diff.ts --self-test ZENIT_E2E_FILE_RPC_DIR=$RPCDIR bun $SKILL/tools/shot.ts /tmp/actual.png bun $SKILL/tools/design_diff.ts /tmp/design/.png /tmp/actual.png ``` ## Using it No special syntax. Describe the UI or the problem; here are a few prompts that work well: ``` Read the "Settings" frame from the open .pen file with the Pencil MCP, rebuild it in zenit as a settings window, and hand it back once design_diff scores above 90. Add a settings window to this app with zenit: a category list on the left, a form on the right, changes applied live. Move the hand-written styles in src/views/sidebar.zig into styles.zig + a recipe. Scrolling stutters when the file tree has 50,000 nodes. Find the cause, fix it, and show me a screenshot afterwards. ``` > TIP > > **Say how to check it.** Add “show me a screenshot” or “verify with E2E” to the request and the agent follows the Skill’s self-check loop, so what you get back has actually been looked at. ## Where it comes from The rules come from two projects: the zenit framework itself (public API, examples, component catalog, test tooling) and a production macOS editor built on zenit (large-app layering, native integration and fix history). Code samples are taken from compiling code in those repos where possible and match this manual. Sources live in the site repo under `skill/zenit-ui-dev/` and are packed at build time by `scripts/pack-skill.mjs`. You can also [read SKILL.md](https://ui.surf/zenit/downloads/zenit-ui-dev.SKILL.md) directly.