barber

Imported from qzstatick/barber (AGENTS.md). Install upstream with npx 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:

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

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-skill followed 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.json MUST live at the repo root (Gemini CLI requirement)
• .claude-plugin/plugin.json, .cursor-plugin/plugin.json, and gemini-extension.json MUST carry a permissions block matching SKILL.md (enforced by tools/skill-lint.py)
• skills/ MUST be at the repo root
• Each skill is a subdirectory under skills/ containing one SKILL.md
• The YAML frontmatter description field 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.

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:

1. The description frontmatter field is the trigger mechanism, so include exact phrases users say
2. Keep SKILL.md under ~5,000 words; move detailed references to references/
3. Use progressive disclosure: core workflow in SKILL.md, edge cases in references/
4. Always route .pen reads/writes through the Pencil MCP tools. Schema validation, screenshots, and live-editor sync depend on it
5. Document tool sequencing (e.g., call get_editor_state before batch_design)
6. 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.md for mappings.

CI / Hooks

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