Teach your AI coding tool to design in pencil.dev. Works with Claude Code, Cursor, and Codex.
Unofficial community plugin. This project is not affiliated with or endorsed by the Pencil.dev team. For the Pencil editor, MCP server, and official documentation, visit pencil.dev. Issues with this skill belong in this repo; issues with the Pencil editor or MCP server belong with the Pencil.dev team.
Star the repo if it helps you, or buy me a coffee or lunch to support ongoing maintenance.
Pencil.dev is a collaborative design tool for creating web and mobile interfaces via the Pencil MCP server. This skill teaches AI coding tools how to work with .pen design files.
- Guides the AI through a seven-step design workflow: detect host, orient, load guidelines, plan, execute, verify, report
- Teaches all 13 Pencil MCP tools with worked invocations, cost cheatsheet, and composite recipes
- Provides 2026 design depth: user flows, component and screen states, full accessibility coverage, and modern patterns (container queries, fluid type, AI-UI affordances)
- Ships 15 worked examples showing real MCP tool sequences from scratch
- Includes per-platform tool-name mappings so the same skill works everywhere
Status:
0.8.0, pre-release. Nothing is shipped until the owner cuts a release.
After installing this skill:
- Generate complete UI designs from natural language ("design a dashboard") without manual tool hunting
- Speed up design iteration by delegating pattern work to AI while you focus on unique decisions
- Maintain design consistency across components and screens
- Work cross-platform with the same skill on Claude Code, Cursor, or Codex
- Customise the skill for your team's workflow via folder copy or fork-and-install
You'll need three things:
- An AI coding tool: Claude Code, Cursor, or OpenAI Codex
- Pencil MCP server: Configure it in your tool (how to set up Pencil)
- A Pencil.dev workspace: Create one free at pencil.dev (no credit card required)
New to Pencil.dev? It's a browser-based design tool. You don't install it; you open it in your browser and create
.penfiles there. This skill helps your AI tool work with those files.
Most people want plugin install. If you plan to customise the skill's instructions for your team, use folder copy or fork + install instead.
Claude Code: two install paths, pick either.
Direct install:
/plugin install github:Nisus74/pencil-skillOr via the marketplace listing (lets you pin and update via marketplace commands):
/plugin marketplace add github:Nisus74/pencil-skill
/plugin install pencil-dev-skillCursor 2.5+: in the editor, run /add-plugin and point it at github.com/Nisus74/pencil-skill.
Codex: use folder copy below. The Codex public plugin directory isn't available yet for third-party plugins.
Download skills/pencil-design/ and drop it into the skills directory your tool reads.
Quickest method:
npx degit github:Nisus74/pencil-skill/skills/pencil-design <target>/pencil-designOr with git:
git clone --depth=1 https://github.com/Nisus74/pencil-skill.git /tmp/pencil-skill
cp -r /tmp/pencil-skill/skills/pencil-design <target>/pencil-designWhere <target> lives:
| Tool | Path |
|---|---|
| Claude Code | ~/.claude/skills/ or .claude/skills/ |
| Cursor | .cursor/skills/ |
| Codex | ~/.codex/skills/ |
To update, re-run the same degit or cp command. If you've edited the files locally, diff and merge by hand.
Available for Claude Code and Cursor.
- Fork Nisus74/pencil-skill on GitHub.
- Install your fork as a plugin:
- Claude Code:
/plugin install github:<your-handle>/pencil-skill - Cursor:
/add-pluginpointing atgithub.com/<your-handle>/pencil-skill
- Claude Code:
- Edit your fork, commit, and push. The next plugin update pulls your changes.
- To pull upstream changes, rebase your fork against
Nisus74/pencil-skill.
For Codex and Copilot CLI, use folder copy. The end result is the same; you just don't get an automatic update path.
| One command | Edit freely | Auto-updates | |
|---|---|---|---|
| Plugin install | yes | no | yes |
| Folder copy | yes | yes | manual |
| Fork + install | yes (after forking) | yes | yes (after rebasing) |
Note: Don't edit files inside a plugin install directory. The next update overwrites them. To customise the skill itself, use folder copy or fork + install.
Once installed, the skill activates automatically when you describe a pencil.dev task:
- "Design a login screen in pencil"
- "Open my .pen file and show me the layout"
- "Generate a dashboard UI in pencil.dev"
- "Use the pencil MCP to update the button colour"
- "Edit the pencil design and change the header"
The AI will handle opening files, reading your design system, generating components, and even taking screenshots to verify the work.
The skill content (SKILL.md, the references, the worked examples) tells the AI how to work. To rewrite it for your team's workflow, use folder copy or fork-and-install. Editing files inside a plugin install directory won't stick — the next update overwrites them.
Questions? Open a GitHub issue or check the Q&A discussions.
Bug report? Include the exact prompt you used, what you expected, and what happened instead. Screenshots help.
Want to contribute? Read docs/CONTRIBUTING.md for the full guide. Short version: fork, branch from main, make your change, run the pre-commit checks, open a PR with before/after examples.
The substance of this project is platform-agnostic. Platform-specific files exist only as install adapters:
skills/pencil-design/
SKILL.md # Core skill — YAML frontmatter + instructions
references/ # 50 reference files loaded on demand
mcp-tools.md # Cookbook for all 13 MCP tools
batch-design-grammar.md # batch_design op syntax reference
pen-schema.md # .pen file schema reference
pencil-cli.md # Full Pencil CLI reference + When CLI vs MCP table
states.md # Component states + screen fault states
flows.md # Screen transitions (modal, validation, back-stack)
accessibility.md # ARIA, focus, RTL, prefers-*, dynamic type
modern-patterns.md # Container queries, fluid type, AI-UI, perceived perf
component-anatomy.md # Reading component structure: slots, descendants, states
visual-hierarchy.md, layout-patterns.md, typography.md,
colour-palettes.md, font-pairings.md, data-viz.md, … # Design-depth references
style-catalogue.md, industry-patterns.md, … # Menu-style catalogues
amplify.md, pare.md, trim.md, soften.md, … # Sub-command references
codex-tools.md # Codex tool name mappings
assets/
design-system/ # Optional design-system reference templates
README.md # Agent loading guide
CUSTOMISING.md # Plain-English guide for non-technical editors
accessibility.md, empty-states.md, file-architecture.md,
forms.md, micro-interactions.md, navigation.md,
onboarding.md, search.md, visual-style.md
examples/ # 15 worked examples with real MCP sequences
example-login-screen.md
example-dashboard.md
example-marketing-page.md
example-form-flow.md
(and 11 more)
evals/
evals.json
AGENTS.md # Canonical project context (cross-platform)
tools/
skill-lint.py # OWASP agentic skills lint (CI + pre-commit)
test_skill_lint.py # Lint unit tests
.claude-plugin/
plugin.json # Claude Code plugin manifest
marketplace.json # Claude Code marketplace listing
.cursor-plugin/plugin.json # Cursor plugin manifest
.codex-plugin/plugin.json # Codex plugin manifest
See AGENTS.md for the full developer guide.
MIT. See LICENSE.
