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

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: two install paths, pick either.

Direct install:

/plugin install github:Nisus74/pencil-skill

Or via the marketplace listing (lets you pin and update via marketplace commands):

/plugin marketplace add github:Nisus74/pencil-skill
/plugin install pencil-dev-skill

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

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 and Cursor.

1. Fork Nisus74/pencil-skill on GitHub.
2. Install your fork as a plugin:
   • Claude Code: /plugin install github:<your-handle>/pencil-skill
   • Cursor: /add-plugin pointing at github.com/<your-handle>/pencil-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 Codex and 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 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.

License

MIT. See LICENSE.