pencil-dev-skill

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.

What it does

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 9 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.

What you'll be able to do

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

Prerequisites

You'll need three things:

1. An AI coding tool: Claude Code, Cursor, or OpenAI Codex
2. Pencil MCP server: Configure it in your tool (how to set up Pencil)
3. 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 .pen files there. This skill helps your AI tool work with those files.

Install

Most people want plugin install. If you plan to customise the skill's instructions for your team, use folder copy or fork + install instead.

Plugin install (recommended)

Claude Code: add the marketplace, then install the plugin. This lets you pin and update through the marketplace commands.

/plugin marketplace add Nisus74/pencil-skill
/plugin install pencil-dev-skill@pencil-dev-skill

Cursor 2.5+: in the editor, run /add-plugin and point it at github.com/Nisus74/pencil-skill.

Codex: add the marketplace, then install the plugin. Codex reads the same .claude-plugin/marketplace.json the repo ships.

codex plugin marketplace add Nisus74/pencil-skill
codex plugin add pencil-dev-skill@pencil-dev-skill

Folder copy

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-design

Or 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-design

Where <target> lives:

To update, re-run the same degit or cp command. If you've edited the files locally, diff and merge by hand.

Fork + install

Available for Claude Code, Cursor, and Codex.

1. Fork Nisus74/pencil-skill on GitHub.
2. Install your fork as a plugin:
   • Claude Code: /plugin marketplace add <your-handle>/pencil-skill, then /plugin install pencil-dev-skill@pencil-dev-skill
   • Cursor: /add-plugin pointing at github.com/<your-handle>/pencil-skill
   • Codex: codex plugin marketplace add <your-handle>/pencil-skill, then codex plugin add pencil-dev-skill@pencil-dev-skill
3. Edit your fork, commit, and push. The next plugin update pulls your changes.
4. To pull upstream changes, rebase your fork against Nisus74/pencil-skill.

For Copilot CLI, use folder copy. The end result is the same; you just don't get an automatic update path.

Install Methods Comparison

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.

Usage

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.

Customising the skill

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.

Getting help

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.

Repository Layout

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 9 MCP tools
    batch-design-grammar.md         # batch_design JavaScript API reference
    pen-schema.md                   # .pen file schema reference (v2.14)
    advanced-canvas.md              # Shader fills, mesh gradients, script nodes, arcs/donuts, prompt/context
    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
  design-system/                    # Optional design-system reference templates (one level deep)
    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 (one level deep)
    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.

License

MIT. See LICENSE.