openpencil/packages/pen-ai-skills/README.md

@zseven-w/pen-ai-skills

AI prompt skill engine for OpenPencil — phase-driven prompt loading with intent matching, token budgets, and design memory.

Install

npm install @zseven-w/pen-ai-skills
# or
bun add @zseven-w/pen-ai-skills

Overview

When an LLM generates designs for OpenPencil, it needs context: PenNode schema, layout rules, semantic roles, icon names, style guides, and more. Loading everything at once wastes tokens. This package solves that with phase-based skill resolution — only the relevant prompts are loaded for each stage of the design workflow.

User message ──► resolveSkills(phase, message, options)
                      │
                      ├─ Phase filter (planning / generation / validation / maintenance)
                      ├─ Intent matching (landing page? dashboard? form? mobile app?)
                      ├─ Flag-based activation (hasDesignMd? hasVariables?)
                      ├─ Priority sorting (higher priority = selected first)
                      └─ Token budget trimming (cap per phase)
                      │
                      ▼
               AgentContext { skills[], memory, budget }

Quick Start

import { resolveSkills } from '@zseven-w/pen-ai-skills';

// Generation phase — user wants a landing page
const ctx = resolveSkills('generation', 'design a SaaS landing page', {
  flags: { hasDesignMd: false, hasVariables: true },
});

// ctx.skills contains the relevant prompts
for (const skill of ctx.skills) {
  console.log(`${skill.meta.name} (${skill.tokenCount} tokens)`);
  // schema (800 tokens)
  // layout (600 tokens)
  // landing-page (400 tokens)
  // ...
}

// Budget tracking
console.log(`${ctx.budget.used} / ${ctx.budget.max} tokens used`);

Phases

Phase	Budget	Purpose
planning	4,000	Analyze requirements, plan sections, choose style
generation	8,000	Generate PenNode trees with full design knowledge
validation	3,000	Check layout, spacing, accessibility, best practices
maintenance	5,000	Edit existing nodes, delete, reparent, modify properties

Skill Categories

Base Skills

Core design principles and workflow guides. Always loaded for their phase.

Domain Skills

Activated by intent matching — keywords in the user message trigger specialized knowledge:

Skill	Triggers
Landing page	landing, marketing, homepage
Dashboard	dashboard, admin, analytics
Form UI	form, login, signup, input
Mobile app	mobile, app, screen, ios, android
CJK typography	chinese, japanese, korean, CJK characters

Knowledge Skills

Reference material loaded by priority until the token budget is exhausted:

• Role definitions — semantic roles (button, input, card, navbar) and their auto-defaults
• Icon catalog — Lucide/Feather icon naming conventions
• Design examples — complete component patterns in DSL
• Copywriting — headline length, CTA text, placeholder copy rules
• Code generation guides — React, Vue, Svelte, Flutter, SwiftUI, Compose, React Native, HTML

Design Memory

Track context across multi-turn generation sessions:

Document Context

import { createDesignContext, contextToPromptString } from '@zseven-w/pen-ai-skills';

const ctx = createDesignContext('/path/to/doc.op');
// Accumulates: palette, typography, spacing, aesthetic, page structure

const prompt = contextToPromptString(ctx);
// "Design system: palette #2563EB, #F8FAFC; font Space Grotesk / Inter; ..."

Generation History

import { createHistoryEntry, getRecentEntries } from '@zseven-w/pen-ai-skills';

const entry = createHistoryEntry({
  documentPath: '/path/to/doc.op',
  prompt: 'design a pricing section',
  phase: 'generation',
  skillsUsed: ['schema', 'layout', 'landing-page'],
  nodeCount: 28,
  sectionTypes: ['pricing'],
});

// Feed recent history back to prevent repetitive designs
const recent = getRecentEntries(allEntries, 5);

Diagnostics

Detect common design issues in generated output:

import { detectAllIssues } from '@zseven-w/pen-ai-skills';

const issues = detectAllIssues(document);
// [{ severity: 'warning', category: 'invisible-container', nodeId: 'frame-7', message: '...' }]

Detector	Catches
Invisible containers	Frames with no fill, stroke, or visual children
Empty paths	Path nodes with no d attribute
Text explicit heights	Text nodes with hardcoded pixel height (causes overflow)
Sibling inconsistencies	Siblings with mixed width strategies in the same layout

Adding a Skill

Create a Markdown file in skills/ with YAML frontmatter:

---
name: my-custom-skill
description: Guidelines for designing checkout flows
phase: [generation, validation]
trigger:
  keywords: [checkout, cart, payment, purchase]
priority: 8
budget: 1500
category: domain
---

## Checkout Flow Design Rules

1. Always show order summary alongside the form
2. Use a single-column layout for payment fields
3. ...

The Vite plugin auto-compiles skills into a TypeScript registry on save during development.

Style Guide

Parse and apply external style guides:

import { parseStyleGuideFile, buildStyleMapping } from '@zseven-w/pen-ai-skills';

const guide = parseStyleGuideFile(markdownContent);
const mappings = buildStyleMapping(guide);
// [{ property: 'fill', from: '#000', to: '$text-primary' }, ...]

License

MIT