https://github.com/nisus74/pencil-skill
AI coding skill plugin for pencil.dev (.pen) design files via the Pencil MCP server — works with Claude Code, Cursor, Codex, and Gemini CLI
https://github.com/nisus74/pencil-skill
ai-coding claude-code claude-plugin design-tool mcp pencil-dev skill
Last synced: 30 days ago
JSON representation
AI coding skill plugin for pencil.dev (.pen) design files via the Pencil MCP server — works with Claude Code, Cursor, Codex, and Gemini CLI
- Host: GitHub
- URL: https://github.com/nisus74/pencil-skill
- Owner: Nisus74
- License: mit
- Created: 2026-05-03T01:17:00.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-17T05:21:41.000Z (30 days ago)
- Last Synced: 2026-05-17T06:04:40.498Z (30 days ago)
- Topics: ai-coding, claude-code, claude-plugin, design-tool, mcp, pencil-dev, skill
- Language: Python
- Size: 1.34 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: docs/SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# pencil-dev-skill
Teach your AI coding tool to design in [pencil.dev](https://pencil.dev). Works with Claude Code, Cursor, and Codex.
[](https://github.com/Nisus74/pencil-skill/commits/main) [](./LICENSE)
> **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](https://pencil.dev). Issues with this skill belong in [this repo](https://github.com/Nisus74/pencil-skill); issues with the Pencil editor or MCP server belong with the Pencil.dev team.
[Star the repo](https://github.com/Nisus74/pencil-skill) if it helps you, or
[buy me a coffee or lunch](https://www.buymeacoffee.com/Nisus74) 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](https://claude.ai/code), [Cursor](https://cursor.com), or [OpenAI Codex](https://openai.com/codex)
2. **Pencil MCP server:** Configure it in your tool ([how to set up Pencil](https://pencil.dev/docs/setup))
3. **A Pencil.dev workspace:** Create one free at [pencil.dev](https://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:
```bash
/plugin install github:Nisus74/pencil-skill
```
Or via the marketplace listing (lets you pin and update via marketplace commands):
```bash
/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/](skills/pencil-design/) and drop it into the skills directory your tool reads.
Quickest method:
```bash
npx degit github:Nisus74/pencil-skill/skills/pencil-design /pencil-design
```
Or with git:
```bash
git clone --depth=1 https://github.com/Nisus74/pencil-skill.git /tmp/pencil-skill
cp -r /tmp/pencil-skill/skills/pencil-design /pencil-design
```
Where `` 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.
### Fork + install
Available for Claude Code and Cursor.
1. Fork [Nisus74/pencil-skill](https://github.com/Nisus74/pencil-skill) on GitHub.
2. Install your fork as a plugin:
- Claude Code: `/plugin install github:/pencil-skill`
- Cursor: `/add-plugin` pointing at `github.com//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
| | 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.
---
## 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](https://github.com/Nisus74/pencil-skill/issues/new) or check the [Q&A discussions](https://github.com/Nisus74/pencil-skill/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](./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](./AGENTS.md) for the full developer guide.
---
## License
MIT. See [LICENSE](./LICENSE).