Imported from qzstatick/barber (
AGENTS.md). Install upstream withnpx skills add qzstatick/barber. Copyright stays with the author.
pencil-dev-skill: Project Context
This is the canonical project-context file. All AI coding tools (Claude Code, OpenAI Codex,
Cursor, etc.) should read this file for project context. Platform-specific files (CLAUDE.md)
are thin pointers to this file.
Project Purpose
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.
This repository is a standalone, platform-agnostic AI coding skill plugin that teaches
AI coding tools how to work with pencil.dev design files (.pen format)
via the Pencil MCP server.
Core artifact: skills/pencil-design/SKILL.md, the platform-agnostic skill content.
Platform adapters: .claude-plugin/plugin.json, .cursor-plugin/plugin.json,
.codex-plugin/plugin.json, and gemini-extension.json are the minimum files required
by each platform's installer; they exist only so users on those platforms can run a
one-line install command. They are not the substance of the project.
Naming Conventions
Three names appear in this project, each scoped to a different layer:
| Name | Scope | Where it appears |
|---|---|---|
pencil-skill |
GitHub repo name | Repo URL, clone URL |
pencil-dev-skill |
Plugin package name | plugin.json, marketplace listings |
pencil-design |
Skill name | SKILL.md frontmatter, skill activation triggers |
This is intentional: the repo is the deliverable, the plugin is the package, and the skill is the capability the AI invokes.
Repository Structure
skills/pencil-design/ # The platform-agnostic core
SKILL.md # The skill: YAML frontmatter + instructions (v0.8.0)
references/ # On-demand references loaded by the skill
mcp-tools.md # Cookbook for all 9 MCP tools + composite recipes
states.md # Component states + screen-level fault states + onboarding/settings states
flows.md # Transitions between screens (modal, validation, back-stack, onboarding, settings, search)
accessibility.md # ARIA, focus order, APCA, ARIA live regions, keyboard shortcuts, WCAG 2.2
modern-patterns.md # Container queries, fluid type, AI-UI, animation timing, command palette, perceived perf
pencil-cli.md # Full Pencil CLI reference + When CLI vs MCP table
pen-schema.md # .pen file JSON schema reference (v2.14)
batch-design-grammar.md # batch_design JavaScript API (Insert/Copy/Update/Replace/Move/Delete/SetVariables/Generate/FindEmptySpace)
advanced-canvas.md # v2.14 canvas features: shader fills, mesh gradients, script nodes, ellipse arcs/donuts, prompt/context nodes
component-anatomy.md # Reading component structure: slots, descendants paths, state activation
composition-patterns.md # Compound components, slot design, variant naming, status workflow
file-architecture.md # Cover frame, section regions, hierarchical naming, multi-.pen layouts
forms.md # Submit behaviour, validation, error display, autofill, mobile inputs
interactions.md # Keyboard, focus, hit targets, loading timing, destructive actions, URL-as-state
visual-hierarchy.md # Six levers, eye-flow patterns, whitespace, density strategy
layout-patterns.md # Hero variations, feature sections beyond three-card grid, pricing, dashboards, settings, list-detail, empty pages (cited 2025/2026 exemplars)
iteration-patterns.md # Failure-mode rescues (too busy/sparse/generic/un-premium), self-critique gate, reference-image translation, three-iteration limit
microcopy.md # Voice/tone framework, action-specific CTAs, error message anatomy, empty/success/confirmation copy, loading copy, localisation
mobile-patterns.md # Safe areas, sheets vs modals, sheet detents, gestures, haptics, tab bars, native conventions per platform
iconography.md # Stroke weight, sizing, semantic icons, accessibility (aria-hidden vs accessible name), family consistency
performance-design.md # Network budgets, Core Web Vitals (LCP/CLS/INP), virtualisation, image and font optimisation, theme-color
industry-patterns.md # 8 industry families with 15-20 rules each + completeness pressure tests for SaaS / Website / Mobile
data-viz.md # 25-chart selection matrix, colour-blind palettes (Okabe-Ito, ColorBrewer, Viridis), dashboard tiles, anti-patterns
style-catalogue.md # 30+ named UI styles (menu) organised by family with mood, when-to-use, anti-pattern, exemplars
colour-palettes.md # 40+ palette recipes (menu) tagged by industry/mood; recipes point to Tailwind/Radix/IBM Carbon/Material 3/Apple HIG
font-pairings.md # 30+ typography pairings (menu); recipes point to Google Fonts/Vercel/GitHub/commercial foundries
codex-tools.md # OpenAI 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 # Project a11y standards (WCAG/APCA, keyboard, screen reader)
empty-states.md # Per-surface empty state catalogue with copy templates
file-architecture.md # Project .pen file structure and naming conventions
forms.md # Form conventions (validation, error display, save patterns)
micro-interactions.md # Per-interaction motion specs
navigation.md # Primary nav patterns, workspace switcher, mobile tab bar
onboarding.md # First-run experience (sample-data vs blank slate)
search.md # Search shape (instant / submit / hybrid), filters, URL state
visual-style.md # Project's chosen style identity (style + palette + font picks)
examples/ # 15 worked examples with real MCP tool sequences (one level deep)
example-login-screen.md # Greenfield auth screen
example-import-library.md # Import .lib.pen library + instantiate components
example-error-screen.md # 404 + offline page pair
example-form-flow.md # Multi-step signup with email verification
example-component-deep-dive.md # Full read→understand→instantiate cycle
example-style-selection.md # Catalogue (style + palette + fonts) → SetVariables → tokens commit → starter components
example-settings-page.md # Settings with sidebar nav, autosave + explicit-save for high-stakes
example-dashboard.md # KPI cards + chart tile + recent-activity table
example-marketing-page.md # Marketing page avoiding three-card grid (asymmetric hero, bento features)
example-mobile-app.md # Mobile app with bottom tab bar, sheet detents, safe areas, haptics
example-data-visualization.md # Multi-chart dashboard with colour-blind-safe palettes
example-onboarding-flow.md # Three-step onboarding with progress, skip, sample-data routing
example-component-variants.md # Complete Button family with all variants and states
example-pricing-table.md # Three-tier pricing with highlighted recommended tier
example-file-cover-and-sections.md # .pen file with Cover frame, section regions, hierarchical naming
# Platform install adapters (required by each platform's installer)
.claude-plugin/plugin.json # Claude Code plugin manifest
.claude-plugin/marketplace.json # Claude Code marketplace listing (single-plugin marketplace)
.cursor-plugin/plugin.json # Cursor plugin manifest (Cursor 2.5+)
.codex-plugin/plugin.json # OpenAI Codex plugin manifest
gemini-extension.json # Gemini CLI extension manifest
# Project context files
AGENTS.md # This file — canonical, platform-agnostic
CLAUDE.md # Thin pointer to AGENTS.md (for Claude Code)
HARNESSES.md # Cross-platform skill capability matrix (frontmatter, directories, substitution)
# Public-facing
README.md
LICENSE
# Repo hygiene
.gitignore # Includes secret patterns
.gitattributes # Cross-platform line-ending normalization
.gitleaks.toml # Secret-scanning config
# Quality tooling
tools/
skill-lint.py # OWASP Agentic Skills Top 10 lint (CI + pre-commit)
test_skill_lint.py # 40 unit tests for skill-lint
requirements.txt # pip deps for Dependabot
# Documentation
SECURITY.md # Security policy + OWASP AST compliance map (repo root)
docs/
CONTRIBUTING.md
CODE_OF_CONDUCT.md
CHANGELOG.md
# GitHub repo configuration
.github/
PULL_REQUEST_TEMPLATE.md
ISSUE_TEMPLATE/
CODEOWNERS
dependabot.yml
workflows/
secret-scan.yml # gitleaks on push + PR
skill-lint.yml # skill-lint + unit tests on push + PR
.pre-commit-config.yaml # Local gate: skill-lint + gitleaks + hygiene
Platform Support
| Platform | Plugin install | Folder-copy target |
|---|---|---|
| Claude Code | /plugin marketplace add Nisus74/pencil-skill, then /plugin install pencil-dev-skill@pencil-dev-skill (manifest at .claude-plugin/plugin.json) |
~/.claude/skills/ or .claude/skills/ |
| Google Gemini CLI | gemini-extension.json at repo root |
~/.gemini/skills/ or .gemini/skills/ (alias .agents/skills/) |
| Cursor (2.5+) | /add-plugin pointing at github.com/Nisus74/pencil-skill (manifest at .cursor-plugin/plugin.json) |
.cursor/skills/ (Cursor also reads AGENTS.md from project root) |
| OpenAI Codex | codex plugin marketplace add Nisus74/pencil-skill, then codex plugin add pencil-dev-skill@pencil-dev-skill (Codex reads the repo's legacy-compatible .claude-plugin/marketplace.json; plugin manifest at .codex-plugin/plugin.json) |
~/.codex/skills/ |
| Copilot CLI | (no plugin manifest) | ~/.copilot/skills/ (alias ~/.agents/skills/) or project .github/skills/ |
All platforms also accept a SKILL.md in their respective skills directory; folder copy works universally.
Deployment and customisation
The full per-platform install instructions live in README.md. At a glance:
- Plugin install is the right default. Users editing only the design-system scaffolds are unaffected by
/plugin update, because the skill copies those scaffolds out into the user's project (e.g.docs/design/). - Folder copy suits users who want to own the skill files from day one. They edit anything, fetch updates by re-downloading and merging by hand.
- Fork + install suits users who want both: full edit access and an automatic update path. Install your fork as a plugin; rebase against upstream when you want changes.
Don't edit files inside a plugin install directory (e.g. ~/.claude/plugins/.../skills/pencil-design/); the next /plugin update will overwrite them.
Plugin System Rules
- The Claude Code plugin manifest MUST live at
.claude-plugin/plugin.json - The Claude Code marketplace listing MUST live at
.claude-plugin/marketplace.json. This makes the repo installable via/plugin marketplace add Nisus74/pencil-skillfollowed by/plugin install pencil-dev-skill@pencil-dev-skill - The Cursor plugin manifest MUST live at
.cursor-plugin/plugin.json(Cursor 2.5+) - The Codex plugin manifest MUST live at
.codex-plugin/plugin.json gemini-extension.jsonMUST live at the repo root (Gemini CLI requirement).claude-plugin/plugin.json,.cursor-plugin/plugin.json, andgemini-extension.jsonMUST carry apermissionsblock matching SKILL.md (enforced bytools/skill-lint.py)skills/MUST be at the repo root- Each skill is a subdirectory under
skills/containing oneSKILL.md - The YAML frontmatter
descriptionfield controls when the skill activates, so edit it carefully - Skills may have a
references/subdirectory for supplementary docs loaded on demand
The Pencil MCP Server
.pen files are JSON conforming to a published schema (Document with version,
themes, imports, variables, children). They are version-controllable like
any code file. While they can technically be read with file tools, all reading
and writing in this project goes through the Pencil MCP server. It gives you
schema validation, live screenshots, and stays in sync with the running editor:
The server exposes nine tools. Tokens (SetVariables), empty-space search (FindEmptySpace), and
image generation (Generate) are JavaScript functions invoked inside a batch_design snippet, not
standalone tools.
| Tool | Purpose |
|---|---|
get_editor_state |
Get current document state + schema (call with include_schema: true first) |
get_guidelines |
Retrieve design guidelines (guides + style archetypes) |
batch_get |
Read multiple nodes |
batch_design |
Write / modify design nodes (JS snippet: Insert/Copy/Update/Replace/Move/Delete/SetVariables/Generate/FindEmptySpace) |
snapshot_layout |
Capture layout state |
get_screenshot |
Visual screenshot of the design |
get_variables |
Read design tokens / variables |
export_nodes |
Export nodes to image / PDF files |
export_html |
Export nodes to HTML (Tailwind or CSS) |
There is no open_document tool (the user opens files in the editor), and no
set_variables / find_empty_space_on_canvas / search_all_unique_properties /
replace_all_matching_properties tools (the first two became batch_design functions; bulk
property work is now a batch_get + Update-loop pattern).
Writing the Skill
When writing or editing skills/pencil-design/SKILL.md:
- The
descriptionfrontmatter field is the trigger mechanism, so include exact phrases users say - Keep
SKILL.mdunder ~5,000 words; move detailed references toreferences/ - Use progressive disclosure: core workflow in
SKILL.md, edge cases inreferences/ - Always route
.penreads/writes through the Pencil MCP tools. Schema validation, screenshots, and live-editor sync depend on it - Document tool sequencing (e.g., call
get_editor_statebeforebatch_design) - Keep instructions platform-agnostic. Use generic verbs ("read", "write", "search")
rather than tool names where possible. When tool names are necessary, default to the
Claude Code names and rely on
references/<platform>-tools.mdfor mappings.
CI / Hooks
| Hook | Trigger | Purpose |
|---|---|---|
.github/workflows/secret-scan.yml |
push, PR | Runs gitleaks; blocks merge if secrets are detected |
.github/workflows/skill-lint.yml |
push, PR | Runs tools/skill-lint.py (OWASP Agentic Skills Top 10) and unit tests |
.pre-commit-config.yaml |
local git commit |
Same skill-lint + gitleaks + basic hygiene; install with pip install pre-commit && pre-commit install |
The OWASP AST compliance map lives in SECURITY.md.
Version Bumping
Follow semantic versioning. Bump the version field in four places, keeping them in sync: .claude-plugin/plugin.json, .cursor-plugin/plugin.json, .codex-plugin/plugin.json, and the skills/pencil-design/SKILL.md frontmatter. (gemini-extension.json does not declare a version field.)
When the project owner authorises a release, bump the version field in four places, keeping them in sync: .claude-plugin/plugin.json, .claude-plugin/marketplace.json (inside the plugins[] entry), .cursor-plugin/plugin.json, and .codex-plugin/plugin.json. Follow semantic versioning:
- PATCH (
0.x.y): Content fixes, typos, clarifications - MINOR (
0.y.0): New capability documented, new trigger phrases added - MAJOR (
x.0.0): Breaking restructuring of the skill workflow
After bumping, replace the [Unreleased] heading in docs/CHANGELOG.md with the new version and date.
Testing the Skill Locally
Claude Code:
# From repo root
/plugin install .
# Then describe a pencil task; verify pencil-design skill triggers
Gemini CLI:
# Install the extension; AGENTS.md loads automatically as project context
# Describe a pencil task; the skill activates via the description trigger
OpenAI Codex:
codex plugin marketplace add Nisus74/pencil-skill
codex plugin add pencil-dev-skill@pencil-dev-skill
# Then describe a pencil task; verify pencil-design skill triggers
Copilot CLI:
# Skills are auto-discovered from skills/ — no install step needed
Links
- GitHub repo: https://github.com/Nisus74/pencil-skill
- pencil.dev: https://pencil.dev
- HARNESSES.md: cross-platform skill capability matrix (frontmatter support, directory conventions, substitution syntax) — consult when adding a new platform manifest or auditing existing ones