@zvoove/unity-ui 2.20.1 → 2.22.0

package/bin/generate-skills.mjs

@@ -0,0 +1,1916 @@
+#!/usr/bin/env node
+
+/**
+ * Unity UI — Agent Skills Generator
+ *
+ * Generates individual SKILL.md files for each Unity UI component
+ * following the Agent Skills standard (https://agentskills.io).
+ *
+ * Run from a project that has @zvoove/unity-ui installed:
+ *
+ *   npx unity-ui-skills                       → outputs to .claude/skills/
+ *   npx unity-ui-skills --output .cursor      → outputs to .cursor/skills/
+ *   npx unity-ui-skills --output ./my-skills  → outputs to ./my-skills/
+ *
+ * Skills enable progressive disclosure — AI agents scan skill metadata
+ * initially but load full content only when relevant to the current task.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ─── Resolve llms.txt from the installed package ────────────────────────────
+
+function findLlmsTxt() {
+  // 1. Co-located with this bin (inside the published package)
+  const fromBin = path.resolve(__dirname, '..', 'dist', 'llms.txt');
+  if (fs.existsSync(fromBin)) return fromBin;
+
+  // 2. Fallback: llms.txt at the package root (dev / pre-build)
+  const fromRoot = path.resolve(__dirname, '..', 'llms.txt');
+  if (fs.existsSync(fromRoot)) return fromRoot;
+
+  return null;
+}
+
+// ─── CLI args ───────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let outputBase = '.claude';
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '--output' || args[i] === '-o') && args[i + 1]) {
+      outputBase = args[i + 1];
+      i++;
+    }
+    if (args[i] === '--help' || args[i] === '-h') {
+      console.log(`
+Unity UI — Agent Skills Generator
+
+Usage:
+  npx unity-ui-skills [options]
+
+Options:
+  -o, --output <dir>  Base directory for skills output (default: .claude)
+                      Skills will be written to <dir>/skills/unity-ui-*/SKILL.md
+  -h, --help          Show this help message
+
+Examples:
+  npx unity-ui-skills                       # → .claude/skills/
+  npx unity-ui-skills --output .cursor      # → .cursor/skills/
+  npx unity-ui-skills --output ./ai-skills  # → ./ai-skills/skills/
+`);
+      process.exit(0);
+    }
+  }
+
+  return { outputBase };
+}
+
+// ─── Name normalization ─────────────────────────────────────────────────────
+// Maps llms.txt header names → clean skill identifiers.
+const NAME_MAP = {
+  'Avatar & AvatarGroup': 'Avatar',
+  'Radio (RadioGroup + RadioButton)': 'Radio',
+  'Segment (SegmentGroup + SegmentButton)': 'Segment',
+  'Common Icons': '__SKIP__',
+  'File Type Icons': '__SKIP__',
+};
+
+// ─── shadcn/ui equivalence map ──────────────────────────────────────────────
+const SHADCN_MAP = {
+  Accordion: {
+    name: 'Accordion',
+    url: 'https://ui.shadcn.com/docs/components/accordion',
+  },
+  ActionCard: null,
+  Avatar: {
+    name: 'Avatar',
+    url: 'https://ui.shadcn.com/docs/components/avatar',
+  },
+  Badge: { name: 'Badge', url: 'https://ui.shadcn.com/docs/components/badge' },
+  Breadcrumbs: {
+    name: 'Breadcrumb',
+    url: 'https://ui.shadcn.com/docs/components/breadcrumb',
+  },
+  Button: {
+    name: 'Button',
+    url: 'https://ui.shadcn.com/docs/components/button',
+  },
+  Card: { name: 'Card', url: 'https://ui.shadcn.com/docs/components/card' },
+  ChatBubble: null,
+  Checkbox: {
+    name: 'Checkbox',
+    url: 'https://ui.shadcn.com/docs/components/checkbox',
+  },
+  Chip: {
+    name: 'Badge',
+    url: 'https://ui.shadcn.com/docs/components/badge',
+    note: 'shadcn Badge covers simple labels; Unity UI Chip adds interactivity (filter, input, suggestion types).',
+  },
+  CodeBlock: null,
+  ConfirmationCard: {
+    name: 'AlertDialog',
+    url: 'https://ui.shadcn.com/docs/components/alert-dialog',
+    note: 'AlertDialog is the closest equivalent for confirmation flows, but ConfirmationCard is an inline card, not a modal.',
+  },
+  ContentBlock: null,
+  DatePicker: {
+    name: 'DatePicker',
+    url: 'https://ui.shadcn.com/docs/components/date-picker',
+  },
+  Dialog: {
+    name: 'Dialog',
+    url: 'https://ui.shadcn.com/docs/components/dialog',
+  },
+  Divider: {
+    name: 'Separator',
+    url: 'https://ui.shadcn.com/docs/components/separator',
+  },
+  Expandable: {
+    name: 'Collapsible',
+    url: 'https://ui.shadcn.com/docs/components/collapsible',
+  },
+  FormLabel: {
+    name: 'Label',
+    url: 'https://ui.shadcn.com/docs/components/label',
+  },
+  Grid: null,
+  Icon: null,
+  InfoBox: {
+    name: 'Alert',
+    url: 'https://ui.shadcn.com/docs/components/alert',
+  },
+  MessageActions: null,
+  Pagination: {
+    name: 'Pagination',
+    url: 'https://ui.shadcn.com/docs/components/pagination',
+  },
+  PopUpMenu: {
+    name: 'DropdownMenu',
+    url: 'https://ui.shadcn.com/docs/components/dropdown-menu',
+    note: 'Also comparable to ContextMenu when using trigger="right-click".',
+  },
+  ProgressIndicator: {
+    name: 'Progress',
+    url: 'https://ui.shadcn.com/docs/components/progress',
+  },
+  Radio: {
+    name: 'RadioGroup',
+    url: 'https://ui.shadcn.com/docs/components/radio-group',
+  },
+  ScoreCard: null,
+  Segment: {
+    name: 'ToggleGroup',
+    url: 'https://ui.shadcn.com/docs/components/toggle-group',
+  },
+  Select: {
+    name: 'Select',
+    url: 'https://ui.shadcn.com/docs/components/select',
+    note: 'When searchable=true, comparable to Combobox.',
+  },
+  Sheet: { name: 'Sheet', url: 'https://ui.shadcn.com/docs/components/sheet' },
+  SideNavigation: {
+    name: 'Sidebar',
+    url: 'https://ui.shadcn.com/docs/components/sidebar',
+  },
+  Skeleton: {
+    name: 'Skeleton',
+    url: 'https://ui.shadcn.com/docs/components/skeleton',
+  },
+  Snackbar: {
+    name: 'Sonner (Toast)',
+    url: 'https://ui.shadcn.com/docs/components/sonner',
+  },
+  Stack: null,
+  Switch: {
+    name: 'Switch',
+    url: 'https://ui.shadcn.com/docs/components/switch',
+  },
+  Table: {
+    name: 'Table / DataTable',
+    url: 'https://ui.shadcn.com/docs/components/data-table',
+  },
+  Tabs: { name: 'Tabs', url: 'https://ui.shadcn.com/docs/components/tabs' },
+  Tag: {
+    name: 'Badge',
+    url: 'https://ui.shadcn.com/docs/components/badge',
+    note: 'shadcn Badge is the closest match. Unity UI Tag offers more color and tone variants.',
+  },
+  TextField: {
+    name: 'Input',
+    url: 'https://ui.shadcn.com/docs/components/input',
+  },
+  Textarea: {
+    name: 'Textarea',
+    url: 'https://ui.shadcn.com/docs/components/textarea',
+  },
+  Tooltip: {
+    name: 'Tooltip',
+    url: 'https://ui.shadcn.com/docs/components/tooltip',
+  },
+  TopBar: null,
+  Typography: null,
+  Uploader: null,
+  useBreakpoint: null,
+  useClickOutside: null,
+};
+
+// ─── MUI equivalence map ─────────────────────────────────────────────────────
+const MUI_BASE = 'https://mui.com/material-ui/react-';
+const MUI_X_BASE = 'https://mui.com/x/react-';
+
+const MUI_MAP = {
+  Accordion: { name: 'Accordion', url: `${MUI_BASE}accordion/` },
+  ActionCard: null,
+  Avatar: { name: 'Avatar', url: `${MUI_BASE}avatar/` },
+  Badge: { name: 'Badge', url: `${MUI_BASE}badge/` },
+  Breadcrumbs: { name: 'Breadcrumbs', url: `${MUI_BASE}breadcrumbs/` },
+  Button: { name: 'Button', url: `${MUI_BASE}button/` },
+  Card: { name: 'Card', url: `${MUI_BASE}card/` },
+  ChatBubble: null,
+  Checkbox: { name: 'Checkbox', url: `${MUI_BASE}checkbox/` },
+  Chip: { name: 'Chip', url: `${MUI_BASE}chip/` },
+  CodeBlock: null,
+  ConfirmationCard: {
+    name: 'Dialog',
+    url: `${MUI_BASE}dialog/`,
+    note: 'Use a Dialog with confirmation actions. ConfirmationCard is an inline card, not a modal.',
+  },
+  ContentBlock: null,
+  DatePicker: {
+    name: 'DatePicker',
+    url: `${MUI_X_BASE}date-picker/`,
+    note: 'MUI X component — requires @mui/x-date-pickers.',
+  },
+  Dialog: { name: 'Dialog', url: `${MUI_BASE}dialog/` },
+  Divider: { name: 'Divider', url: `${MUI_BASE}divider/` },
+  Expandable: { name: 'Collapse', url: `${MUI_BASE}collapse/` },
+  FormLabel: { name: 'FormLabel', url: `${MUI_BASE}text-field/` },
+  Grid: { name: 'Grid', url: `${MUI_BASE}grid/` },
+  Icon: { name: 'SvgIcon', url: `${MUI_BASE}icons/` },
+  InfoBox: { name: 'Alert', url: `${MUI_BASE}alert/` },
+  MessageActions: null,
+  Pagination: { name: 'Pagination', url: `${MUI_BASE}pagination/` },
+  PopUpMenu: { name: 'Menu', url: `${MUI_BASE}menu/` },
+  ProgressIndicator: {
+    name: 'LinearProgress / CircularProgress',
+    url: `${MUI_BASE}progress/`,
+  },
+  Radio: { name: 'RadioGroup', url: `${MUI_BASE}radio-button/` },
+  ScoreCard: null,
+  Segment: {
+    name: 'ToggleButtonGroup',
+    url: `${MUI_BASE}toggle-button/`,
+  },
+  Select: { name: 'Select', url: `${MUI_BASE}select/` },
+  Sheet: {
+    name: 'Drawer',
+    url: `${MUI_BASE}drawer/`,
+    note: 'Use a temporary or persistent Drawer.',
+  },
+  SideNavigation: {
+    name: 'Drawer (persistent)',
+    url: `${MUI_BASE}drawer/`,
+  },
+  Skeleton: { name: 'Skeleton', url: `${MUI_BASE}skeleton/` },
+  Snackbar: { name: 'Snackbar', url: `${MUI_BASE}snackbar/` },
+  Stack: { name: 'Stack', url: `${MUI_BASE}stack/` },
+  Switch: { name: 'Switch', url: `${MUI_BASE}switch/` },
+  Table: {
+    name: 'Table / DataGrid',
+    url: `${MUI_BASE}table/`,
+    note: 'For advanced features use MUI X DataGrid (@mui/x-data-grid).',
+  },
+  Tabs: { name: 'Tabs', url: `${MUI_BASE}tabs/` },
+  Tag: {
+    name: 'Chip',
+    url: `${MUI_BASE}chip/`,
+    note: 'MUI Chip covers static labels; Unity UI Tag is display-only with more color/tone variants.',
+  },
+  TextField: { name: 'TextField', url: `${MUI_BASE}text-field/` },
+  Textarea: {
+    name: 'TextField (multiline)',
+    url: `${MUI_BASE}text-field/`,
+    note: 'Use TextField with multiline and rows props.',
+  },
+  Tooltip: { name: 'Tooltip', url: `${MUI_BASE}tooltip/` },
+  TopBar: { name: 'AppBar', url: `${MUI_BASE}app-bar/` },
+  Typography: { name: 'Typography', url: `${MUI_BASE}typography/` },
+  Uploader: null,
+  useBreakpoint: {
+    name: 'useMediaQuery',
+    url: 'https://mui.com/material-ui/react-use-media-query/',
+  },
+  useClickOutside: {
+    name: 'ClickAwayListener',
+    url: `${MUI_BASE}click-away-listener/`,
+  },
+};
+
+// ─── Storybook documentation links ───────────────────────────────────────────
+// Maps component name → Storybook title path (as defined in *.stories.tsx).
+// URL: https://main--67c03f013fea08bb2f926e5f.chromatic.com/?path=/docs/<path>--docs
+const STORYBOOK_BASE =
+  'https://main--67c03f013fea08bb2f926e5f.chromatic.com/?path=/docs/';
+
+const STORYBOOK_MAP = {
+  Accordion: 'Components/Accordion',
+  ActionCard: 'Chat/ActionCard',
+  Avatar: 'Components/Avatar/Avatar',
+  Badge: 'Components/Badge',
+  Breadcrumbs: 'Navigation/Breadcrumbs',
+  Button: 'Components/Buttons/Button',
+  Card: 'Components/Card',
+  ChatBubble: 'Chat/ChatBubble',
+  Checkbox: 'Forms/Checkbox',
+  Chip: 'Components/Chip',
+  CodeBlock: 'Components/CodeBlock',
+  ConfirmationCard: 'Components/ConfirmationCard',
+  ContentBlock: 'Components/ContentBlock',
+  DatePicker: 'Forms/DatePicker',
+  Dialog: 'Components/Dialog',
+  Divider: 'Components/Divider',
+  Expandable: 'Components/Expandable',
+  FormLabel: 'Forms/FormLabel',
+  Grid: 'Layout/Grid',
+  Icon: 'Components/Icon',
+  InfoBox: 'Components/InfoBox',
+  MessageActions: 'Chat/MessageActions',
+  Pagination: 'Components/Pagination',
+  PopUpMenu: 'Components/PopUpMenu',
+  ProgressIndicator: 'Components/ProgressIndicator',
+  Radio: 'Forms/Radio/RadioGroup',
+  ScoreCard: 'Components/ScoreCard',
+  Segment: 'Components/Buttons/Segment/SegmentGroup',
+  Select: 'Forms/Select',
+  Sheet: 'Components/Sheet',
+  SideNavigation: 'Navigation/SideNavigation',
+  Skeleton: 'Components/Skeleton',
+  Snackbar: 'Components/Snackbar',
+  Stack: 'Layout/Stack',
+  Switch: 'Forms/Switch',
+  Table: 'Components/Table',
+  Tabs: 'Navigation/Tabs',
+  Tag: 'Components/Tag',
+  TextField: 'Forms/TextField',
+  Textarea: 'Forms/Textarea',
+  Tooltip: 'Components/Tooltip',
+  TopBar: 'Components/TopBar',
+  Typography: 'Components/Typography',
+  Uploader: 'Forms/Uploader',
+};
+
+function storybookUrl(name) {
+  const title = STORYBOOK_MAP[name];
+  if (!title) return null;
+  const slug = title.toLowerCase().replaceAll('/', '-');
+  return `${STORYBOOK_BASE}${slug}--docs`;
+}
+
+// ─── Component categories ───────────────────────────────────────────────────
+const CATEGORIES = {
+  Stack: 'layout',
+  Grid: 'layout',
+  Card: 'layout',
+  Divider: 'layout',
+  Expandable: 'layout',
+  ContentBlock: 'layout',
+  Typography: 'typography',
+  TextField: 'form',
+  Textarea: 'form',
+  Select: 'form',
+  Checkbox: 'form',
+  Radio: 'form',
+  Switch: 'form',
+  DatePicker: 'form',
+  Uploader: 'form',
+  FormLabel: 'form',
+  Button: 'action',
+  Segment: 'action',
+  PopUpMenu: 'action',
+  Table: 'data-display',
+  Tag: 'data-display',
+  Chip: 'data-display',
+  Avatar: 'data-display',
+  Badge: 'data-display',
+  Icon: 'data-display',
+  Skeleton: 'data-display',
+  ProgressIndicator: 'data-display',
+  CodeBlock: 'data-display',
+  Tabs: 'navigation',
+  Breadcrumbs: 'navigation',
+  SideNavigation: 'navigation',
+  Pagination: 'navigation',
+  TopBar: 'navigation',
+  Dialog: 'feedback',
+  Sheet: 'feedback',
+  Snackbar: 'feedback',
+  InfoBox: 'feedback',
+  ConfirmationCard: 'feedback',
+  Tooltip: 'feedback',
+  Accordion: 'compound',
+  ActionCard: 'compound',
+  ChatBubble: 'compound',
+  MessageActions: 'compound',
+  ScoreCard: 'compound',
+  useBreakpoint: 'hook',
+  useClickOutside: 'hook',
+};
+
+// Category-specific rules appended to each skill
+const CATEGORY_RULES = {
+  layout: [
+    '- Use Stack and Grid for layout instead of raw div + CSS',
+    '- Use the spacing scale for gap/padding/margin — never use arbitrary pixel values',
+  ],
+  form: [
+    '- Never create custom form inputs when this component exists',
+    '- Use responsive `density` prop when available for compact layouts',
+  ],
+  feedback: [
+    '- Never create custom overlays or toast systems when this component exists',
+  ],
+  typography: [
+    '- Use Typography for all text — never use raw `<p>`, `<h1>`, `<span>` etc.',
+  ],
+  hook: ['- Import hooks directly from `@zvoove/unity-ui`'],
+};
+
+// ─── Parse llms.txt ─────────────────────────────────────────────────────────
+
+function detectSection(line) {
+  const sectionHeaders = {
+    '## Setup': 'setup',
+    '## Responsive Props': 'responsive',
+    '## RULES FOR AI AGENTS': 'rules',
+    '## SPACING SCALE': 'spacing',
+    '## ICON NAMES': 'icons',
+    '## STYLING': 'styling',
+    '## CUSTOM COMPONENT': 'customComponent',
+  };
+
+  for (const [prefix, key] of Object.entries(sectionHeaders)) {
+    if (line.startsWith(prefix)) return key;
+  }
+  if (line.startsWith('## EXAMPLE:')) return 'example';
+  if (
+    /^## [A-Z]+ COMPONENTS?$/.test(line) ||
+    /^## (HOOKS|COMPOUND COMPONENTS|TYPOGRAPHY)$/.test(line)
+  ) {
+    return 'category-header';
+  }
+  return null;
+}
+
+function mergeComponent(components, buckets, name, lines) {
+  if (!name || lines.length === 0) return;
+  const normalizedName = NAME_MAP[name] ?? name;
+
+  if (normalizedName === '__SKIP__') {
+    buckets.icons.push('', `### ${name}`, ...lines);
+    return;
+  }
+  const text = lines.join('\n').trim();
+  components[normalizedName] = components[normalizedName]
+    ? components[normalizedName] + '\n\n' + text
+    : text;
+}
+
+function parseLlmsTxt(content) {
+  const components = {};
+  const buckets = {
+    setup: [],
+    responsive: [],
+    rules: [],
+    spacing: [],
+    styling: [],
+    customComponent: [],
+    icons: [],
+    example: [],
+  };
+
+  let activeSection = null;
+  let currentComponent = null;
+  let currentLines = [];
+
+  function flush() {
+    mergeComponent(components, buckets, currentComponent, currentLines);
+    currentComponent = null;
+    currentLines = [];
+  }
+
+  function handleSectionHeader(line) {
+    flush();
+    const section = detectSection(line);
+    activeSection = section === 'category-header' ? null : section;
+  }
+
+  function handleComponentHeader(line) {
+    // In prose sections, ### sub-headings are content, not component names
+    if (activeSection === 'styling' || activeSection === 'customComponent') {
+      handleContentLine(line);
+      return;
+    }
+    flush();
+    currentComponent = line.slice(4).trim();
+    if (activeSection !== 'icons') activeSection = null;
+  }
+
+  function handleContentLine(line) {
+    if (currentComponent) {
+      currentLines.push(line);
+      return;
+    }
+    if (activeSection && buckets[activeSection]) {
+      buckets[activeSection].push(line);
+    }
+  }
+
+  for (const line of content.split('\n')) {
+    if (line === '---') continue;
+    if (line.startsWith('## ')) handleSectionHeader(line);
+    else if (line.startsWith('### ')) handleComponentHeader(line);
+    else handleContentLine(line);
+  }
+
+  flush();
+
+  const trimBucket = (key) => buckets[key].join('\n').trim();
+  return {
+    setup: trimBucket('setup'),
+    responsive: trimBucket('responsive'),
+    rules: trimBucket('rules'),
+    spacing: trimBucket('spacing'),
+    styling: trimBucket('styling'),
+    customComponent: trimBucket('customComponent'),
+    icons: trimBucket('icons'),
+    example: trimBucket('example'),
+    components,
+  };
+}
+
+// ─── Skill generators ───────────────────────────────────────────────────────
+
+function kebabCase(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function generateComponentSkill(name, content) {
+  const shadcn = SHADCN_MAP[name];
+  const category = CATEGORIES[name] || 'component';
+  const slug = kebabCase(name);
+  const docsUrl = storybookUrl(name);
+
+  let description = `${name} component from Unity UI (@zvoove/unity-ui). Category: ${category}.`;
+  if (shadcn) {
+    description += ` Comparable to shadcn/ui ${shadcn.name}.`;
+  }
+  description += String.raw`\nTRIGGER when: user needs ${name} in a project using @zvoove/unity-ui.\nDO NOT read dist/ or source files — all API docs are in this skill.`;
+
+  const frontmatter = [
+    '---',
+    `name: unity-ui-${slug}`,
+    `description: "${description}"`,
+    `category: ${category}`,
+  ];
+  if (shadcn) frontmatter.push(`shadcn_equivalent: ${shadcn.name}`);
+  if (docsUrl) frontmatter.push(`docs: ${docsUrl}`);
+  frontmatter.push('---');
+
+  const body = [`# Unity UI — ${name}\n`];
+
+  const links = [];
+  if (docsUrl) links.push(`[Storybook docs](${docsUrl})`);
+  if (shadcn) links.push(`[shadcn/ui ${shadcn.name}](${shadcn.url})`);
+  if (links.length > 0) {
+    body.push(`> ${links.join(' | ')}`);
+    if (shadcn?.note) body.push(`> ${shadcn.note}`);
+    body.push('');
+  }
+
+  body.push(content);
+  body.push('\n## Rules\n');
+  body.push('- Always import from `@zvoove/unity-ui`');
+  body.push('- Never recreate components that exist in this library');
+
+  const extraRules = CATEGORY_RULES[category] || [];
+  body.push(...extraRules);
+  body.push(
+    '- Use responsive props where applicable (single value or breakpoint object)'
+  );
+
+  return frontmatter.join('\n') + '\n\n' + body.join('\n') + '\n';
+}
+
+function generateSetupSkill(parsed) {
+  const frontmatter = [
+    '---',
+    'name: unity-ui-setup',
+    'description: "Setup and installation for Unity UI (@zvoove/unity-ui). React component library with 40+ components, Tailwind CSS 4, dark mode, responsive props."',
+    'category: setup',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Setup & Overview
+
+> Unity UI (\`@zvoove/unity-ui\`) is a React component library with 40+ accessible, themeable components built with TypeScript and Tailwind CSS 4.
+
+${parsed.setup}
+
+## Responsive Props
+
+${parsed.responsive}
+
+## Spacing Scale
+
+${parsed.spacing}
+
+## Example: Contact Form
+
+${parsed.example}
+
+## Rules
+
+${parsed.rules}
+`
+  );
+}
+
+function generateIconsSkill(parsed) {
+  const frontmatter = [
+    '---',
+    'name: unity-ui-icons',
+    'description: "Icon names and usage for Unity UI (@zvoove/unity-ui). Semantic icon names based on Phosphor Icons. Use with <Icon name=\\"icon-name\\" /> component."',
+    'category: data-display',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Icons
+
+> Unity UI uses its own semantic icon names (not raw Phosphor icon names). Pass them via \`<Icon name="icon-name" />\`.
+
+${parsed.icons}
+
+## Rules
+
+- Always import Icon from \`@zvoove/unity-ui\`
+- Use semantic icon name strings — never import Phosphor icon components directly
+- Use \`getIconForFileExtension(extension)\` to resolve file extensions to icon names automatically
+`
+  );
+}
+
+function generateIndexSkill(componentNames) {
+  const shadcnRows = componentNames
+    .filter((n) => SHADCN_MAP[n])
+    .map(
+      (n) =>
+        `| ${n} | [${SHADCN_MAP[n].name}](${SHADCN_MAP[n].url}) | \`unity-ui-${kebabCase(n)}\` |`
+    );
+
+  const muiRows = componentNames
+    .filter((n) => MUI_MAP[n])
+    .map(
+      (n) =>
+        `| ${n} | [${MUI_MAP[n].name}](${MUI_MAP[n].url}) | \`unity-ui-${kebabCase(n)}\` |`
+    );
+
+  const uniqueRows = componentNames
+    .filter((n) => !SHADCN_MAP[n] && !MUI_MAP[n])
+    .map((n) => `| ${n} | \`unity-ui-${kebabCase(n)}\` |`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-index',
+    'description: "Component index for Unity UI (@zvoove/unity-ui). Maps all 40+ components to their shadcn/ui and MUI equivalents. Use this to find the right component or migrate from another library."',
+    'category: index',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Component Index
+
+> Use this index to find the right Unity UI component. Each component has its own skill with full documentation.
+
+## shadcn/ui → Unity UI
+
+| Unity UI | shadcn/ui | Skill |
+|----------|-----------|-------|
+${shadcnRows.join('\n')}
+
+## MUI → Unity UI
+
+| Unity UI | MUI | Skill |
+|----------|-----|-------|
+${muiRows.join('\n')}
+
+## Unity UI–Only Components
+
+| Unity UI | Skill |
+|----------|-------|
+${uniqueRows.map((r) => r.replace(' | — ', '')).join('\n')}
+
+## How to Use Skills
+
+Each skill is a standalone file with full props, usage examples, and rules for one component.
+AI agents should load the relevant skill when they need to use a specific component.
+`
+  );
+}
+
+function generateStylingSkill(parsed) {
+  const description = [
+    'Styling guide for Unity UI (@zvoove/unity-ui). Tailwind CSS v4 + design tokens + tailwind-variants.',
+    'TRIGGER when: user needs to style a custom element, asks about CSS/styling, or produces inline styles / arbitrary Tailwind values in a @zvoove/unity-ui project.',
+    'DO NOT use inline styles, arbitrary Tailwind values, or raw CSS — use design tokens and tv() instead.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-styling',
+    `description: "${description}"`,
+    'category: styling',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter + `\n\n# Unity UI — Styling Guide\n\n` + parsed.styling + '\n'
+  );
+}
+
+function generateCustomComponentSkill(parsed) {
+  const description = [
+    'Guide for creating a custom component in a project using @zvoove/unity-ui, following the same conventions as the design system.',
+    'TRIGGER when: user needs to create a custom component that does not exist in @zvoove/unity-ui, following Unity UI patterns.',
+    'DO NOT TRIGGER when: an existing Unity UI component already covers the use case — use that instead.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-custom-component',
+    `description: "${description}"`,
+    'category: authoring',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Creating a Custom Component\n\n` +
+    parsed.customComponent +
+    '\n'
+  );
+}
+
+function generateFormsSkill() {
+  const description = [
+    'Form composition guide for @zvoove/unity-ui with react-hook-form and zod.',
+    'TRIGGER when: user is building a form, adding validation, wiring inputs to a form library, or asking how to use Unity UI inputs with react-hook-form.',
+    'DO NOT use register() — Unity UI inputs are controlled components; always use Controller.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-forms',
+    `description: "${description}"`,
+    'category: forms',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Form Composition
+
+> Unity UI inputs are **controlled components**. Use \`Controller\` from react-hook-form — never \`register()\`.
+
+## Installing
+
+\`\`\`bash
+npm install react-hook-form zod @hookform/resolvers
+\`\`\`
+
+## Basic Pattern
+
+\`\`\`tsx
+import { useForm, Controller } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Button, Select, Stack, TextField } from '@zvoove/unity-ui';
+
+const schema = z.object({
+  email: z.string().email('Ungültige E-Mail-Adresse'),
+  role: z.string().min(1, 'Pflichtfeld'),
+});
+
+type FormValues = z.infer<typeof schema>;
+
+export function ExampleForm() {
+  const { control, handleSubmit } = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: '', role: '' },
+  });
+
+  return (
+    <form onSubmit={handleSubmit((data) => console.log(data))}>
+      <Stack direction="column" gap="md">
+        <Controller
+          name="email"
+          control={control}
+          render={({ field, fieldState }) => (
+            <TextField
+              {...field}
+              label="E-Mail"
+              error={!!fieldState.error}
+              errorMessage={fieldState.error?.message}
+            />
+          )}
+        />
+        <Controller
+          name="role"
+          control={control}
+          render={({ field, fieldState }) => (
+            <Select
+              {...field}
+              label="Rolle"
+              options={[
+                { value: 'admin', label: 'Administrator' },
+                { value: 'user', label: 'Benutzer' },
+              ]}
+              error={!!fieldState.error}
+              errorMessage={fieldState.error?.message}
+            />
+          )}
+        />
+        <Stack direction="row" gap="sm" justify="flex-end">
+          <Button type="submit" variant="filled">Speichern</Button>
+        </Stack>
+      </Stack>
+    </form>
+  );
+}
+\`\`\`
+
+## Input Binding Reference
+
+| Component | Binding pattern | Notes |
+|-----------|----------------|-------|
+| TextField | \`{...field}\` | value + onChange + onBlur + name |
+| Textarea | \`{...field}\` | same as TextField |
+| Select | \`{...field}\` | value + onChange |
+| Checkbox | \`checked={field.value}\` | use \`checked\`, not \`value\` |
+| Switch | \`checked={field.value}\` | use \`checked\`, not \`value\` |
+| DatePicker | \`value={field.value} onChange={field.onChange}\` | pass date value directly |
+| Radio (RadioGroup) | \`value={field.value} onChange={field.onChange}\` | — |
+
+## Checkbox / Switch Pattern
+
+\`\`\`tsx
+<Controller
+  name="acceptTerms"
+  control={control}
+  render={({ field }) => (
+    <Checkbox
+      label="Ich akzeptiere die Nutzungsbedingungen"
+      checked={field.value ?? false}
+      onChange={(e) => field.onChange(e.target.checked)}
+    />
+  )}
+/>
+\`\`\`
+
+## DatePicker Pattern
+
+\`\`\`tsx
+<Controller
+  name="birthDate"
+  control={control}
+  render={({ field, fieldState }) => (
+    <DatePicker
+      label="Geburtsdatum"
+      value={field.value}
+      onChange={field.onChange}
+      error={!!fieldState.error}
+      errorMessage={fieldState.error?.message}
+    />
+  )}
+/>
+\`\`\`
+
+## Complete Login Form
+
+\`\`\`tsx
+import { useForm, Controller } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Button, Card, Checkbox, Stack, TextField, Typography } from '@zvoove/unity-ui';
+
+const loginSchema = z.object({
+  email: z.string().email('Ungültige E-Mail-Adresse'),
+  password: z.string().min(8, 'Mindestens 8 Zeichen erforderlich'),
+  rememberMe: z.boolean().optional(),
+});
+
+type LoginValues = z.infer<typeof loginSchema>;
+
+export function LoginForm() {
+  const {
+    control,
+    handleSubmit,
+    formState: { isSubmitting },
+  } = useForm<LoginValues>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: { email: '', password: '', rememberMe: false },
+  });
+
+  const onSubmit = async (data: LoginValues) => {
+    await login(data);
+  };
+
+  return (
+    <Card padding="xl">
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Stack direction="column" gap="md">
+          <Typography variant="title-large">Anmelden</Typography>
+
+          <Controller
+            name="email"
+            control={control}
+            render={({ field, fieldState }) => (
+              <TextField
+                {...field}
+                label="E-Mail"
+                type="email"
+                error={!!fieldState.error}
+                errorMessage={fieldState.error?.message}
+              />
+            )}
+          />
+
+          <Controller
+            name="password"
+            control={control}
+            render={({ field, fieldState }) => (
+              <TextField
+                {...field}
+                label="Passwort"
+                type="password"
+                error={!!fieldState.error}
+                errorMessage={fieldState.error?.message}
+              />
+            )}
+          />
+
+          <Controller
+            name="rememberMe"
+            control={control}
+            render={({ field }) => (
+              <Checkbox
+                label="Angemeldet bleiben"
+                checked={field.value ?? false}
+                onChange={(e) => field.onChange(e.target.checked)}
+              />
+            )}
+          />
+
+          <Stack direction="row" justify="flex-end">
+            <Button type="submit" variant="filled" disabled={isSubmitting}>
+              {isSubmitting ? 'Wird angemeldet…' : 'Anmelden'}
+            </Button>
+          </Stack>
+        </Stack>
+      </form>
+    </Card>
+  );
+}
+\`\`\`
+
+## Rules
+
+- NEVER use \`register()\` — Unity UI inputs are controlled components; always use \`Controller\`
+- ALWAYS use \`zodResolver\` from \`@hookform/resolvers/zod\` for schema validation
+- Checkbox and Switch require \`checked={field.value}\` — not \`value\`
+- Display errors with \`error={!!fieldState.error}\` + \`errorMessage={fieldState.error?.message}\`
+- Use \`Stack\` for form layout — never raw \`<div>\` with flexbox CSS
+- Default texts, labels, and validation messages must be in German
+`
+  );
+}
+
+function generateLayoutsSkill() {
+  const description = [
+    'Common app layout patterns for @zvoove/unity-ui: app shells, dashboards, settings pages, master/detail.',
+    'TRIGGER when: user is building a page layout, app shell, or multi-section UI in a @zvoove/unity-ui project.',
+    'DO NOT use raw div + CSS for layout — always use Stack, Grid, TopBar, SideNavigation.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-layouts',
+    `description: "${description}"`,
+    'category: layout',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Layout Patterns
+
+> Use \`Stack\` and \`Grid\` for all layout. Never use raw \`<div style={{ display: 'flex' }}>\`.
+
+## App Shell (TopBar + SideNavigation)
+
+\`\`\`tsx
+import { Avatar, SideNavigation, Stack, TopBar } from '@zvoove/unity-ui';
+
+export function AppShell({ children }: { children: React.ReactNode }) {
+  const [activeId, setActiveId] = useState('dashboard');
+
+  return (
+    <Stack direction="column" style={{ height: '100vh' }}>
+      <TopBar
+        title="Meine App"
+        actions={<Avatar initials="AB" />}
+      />
+      <Stack direction="row" style={{ flex: 1, overflow: 'hidden' }}>
+        <SideNavigation
+          items={[
+            { id: 'dashboard', label: 'Dashboard', icon: 'House' },
+            { id: 'users', label: 'Benutzer', icon: 'Users' },
+            { id: 'settings', label: 'Einstellungen', icon: 'Gear' },
+          ]}
+          activeId={activeId}
+          onSelect={setActiveId}
+        />
+        <Stack
+          direction="column"
+          padding="xl"
+          style={{ flex: 1, overflow: 'auto' }}
+        >
+          {children}
+        </Stack>
+      </Stack>
+    </Stack>
+  );
+}
+\`\`\`
+
+## Dashboard Layout
+
+\`\`\`tsx
+<Stack direction="column" gap="lg" padding="xl">
+  <Typography variant="headline-small">Dashboard</Typography>
+
+  {/* KPI summary row */}
+  <Grid columns={{ mobile: 1, tablet: 2, desktop: 4 }} gap="md">
+    {kpis.map((kpi) => (
+      <Card key={kpi.id} padding="md">
+        <Stack direction="column" gap="xs">
+          <Typography variant="label-medium">{kpi.label}</Typography>
+          <Typography variant="display-small">{kpi.value}</Typography>
+        </Stack>
+      </Card>
+    ))}
+  </Grid>
+
+  {/* Main area: 2/3 table + 1/3 sidebar */}
+  <Grid columns={{ mobile: 1, laptop: 3 }} gap="lg">
+    <Stack style={{ gridColumn: 'span 2' }}>
+      <Card padding="md">
+        <Table columns={columns} rows={rows} />
+      </Card>
+    </Stack>
+    <Stack direction="column" gap="md">
+      <Card padding="md">
+        <Typography variant="title-medium">Aktivität</Typography>
+        {/* activity list */}
+      </Card>
+    </Stack>
+  </Grid>
+</Stack>
+\`\`\`
+
+## Settings Page (Two-Column)
+
+\`\`\`tsx
+<Stack direction="column" gap="xl" padding="xl">
+  <Typography variant="headline-small">Einstellungen</Typography>
+
+  <Stack direction={{ mobile: 'column', tablet: 'row' }} gap="xl">
+    {/* Left: section label */}
+    <Stack direction="column" gap="xs" style={{ minWidth: 200 }}>
+      <Typography variant="title-medium">Profil</Typography>
+      <Typography variant="body-medium">Persönliche Informationen.</Typography>
+    </Stack>
+
+    {/* Right: fields */}
+    <Card padding="lg" style={{ flex: 1 }}>
+      <Stack direction="column" gap="md">
+        <Stack direction={{ mobile: 'column', tablet: 'row' }} gap="md">
+          <TextField label="Vorname" value={firstName} onChange={setFirstName} />
+          <TextField label="Nachname" value={lastName} onChange={setLastName} />
+        </Stack>
+        <TextField label="E-Mail" value={email} onChange={setEmail} />
+        <Switch
+          label="E-Mail-Benachrichtigungen aktivieren"
+          checked={notifications}
+          onChange={(e) => setNotifications(e.target.checked)}
+        />
+      </Stack>
+    </Card>
+  </Stack>
+
+  {/* Sticky action bar */}
+  <Stack direction="row" gap="sm" justify="flex-end">
+    <Button variant="outlined">Abbrechen</Button>
+    <Button variant="filled">Speichern</Button>
+  </Stack>
+</Stack>
+\`\`\`
+
+## Master / Detail (List + Detail)
+
+\`\`\`tsx
+<Stack
+  direction={{ mobile: 'column', tablet: 'row' }}
+  gap="md"
+  padding="xl"
+  style={{ height: '100%' }}
+>
+  {/* List panel */}
+  <Stack direction="column" gap="sm" style={{ width: 300, flexShrink: 0 }}>
+    {items.map((item) => (
+      <Card
+        key={item.id}
+        padding="md"
+        onClick={() => setSelected(item.id)}
+      >
+        <Typography variant="body-medium">{item.title}</Typography>
+      </Card>
+    ))}
+  </Stack>
+
+  {/* Detail panel */}
+  <Stack direction="column" gap="md" style={{ flex: 1 }}>
+    {selected ? (
+      <Card padding="lg">{/* detail content */}</Card>
+    ) : (
+      <Stack direction="column" align="center" justify="center" style={{ height: '100%' }}>
+        <Typography variant="body-medium">Wählen Sie einen Eintrag aus.</Typography>
+      </Stack>
+    )}
+  </Stack>
+</Stack>
+\`\`\`
+
+## Centered Auth / Empty State
+
+\`\`\`tsx
+<Stack
+  direction="column"
+  align="center"
+  justify="center"
+  style={{ minHeight: '100vh' }}
+  gap="lg"
+>
+  <Card padding="xl" style={{ width: '100%', maxWidth: 400 }}>
+    <Stack direction="column" gap="md">
+      <Typography variant="headline-small">Anmelden</Typography>
+      {/* form fields */}
+    </Stack>
+  </Card>
+</Stack>
+\`\`\`
+
+## Card Grid (Content Listing)
+
+\`\`\`tsx
+<Stack direction="column" gap="lg" padding="xl">
+  <Stack direction="row" justify="space-between" align="center">
+    <Typography variant="headline-small">Projekte</Typography>
+    <Button variant="filled" icon="Plus">Neues Projekt</Button>
+  </Stack>
+
+  <Grid columns={{ mobile: 1, tablet: 2, desktop: 3 }} gap="md">
+    {projects.map((project) => (
+      <Card key={project.id} padding="md">
+        <Stack direction="column" gap="sm">
+          <Typography variant="title-medium">{project.name}</Typography>
+          <Typography variant="body-small">{project.description}</Typography>
+          <Stack direction="row" gap="xs" justify="flex-end">
+            <Button variant="ghost" size="sm">Bearbeiten</Button>
+          </Stack>
+        </Stack>
+      </Card>
+    ))}
+  </Grid>
+</Stack>
+\`\`\`
+
+## Rules
+
+- Use \`Stack\` and \`Grid\` for ALL layout — never \`<div style={{ display: 'flex' }}>\`
+- Use \`TopBar\` + \`SideNavigation\` for app shells — never custom nav bars
+- Use \`Card\` for content containers — never styled divs
+- Use spacing tokens for gap/padding — never arbitrary pixel values (\`gap-lg\` not \`gap-5\`)
+- Always make layouts responsive with \`ResponsiveType\` props
+- SideNavigation handles its own responsive collapse — do not wrap it in conditional rendering
+`
+  );
+}
+
+function generateDarkModeSkill() {
+  const description = [
+    'Dark mode setup and theme toggling for @zvoove/unity-ui projects.',
+    'TRIGGER when: user wants to add dark mode, a theme toggle, or asks how Unity UI dark mode works.',
+    'DO NOT use prefers-color-scheme media queries or className=\\"dark\\" — Unity UI uses data-theme=\\"dark\\".',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-dark-mode',
+    `description: "${description}"`,
+    'category: theming',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Dark Mode
+
+> Dark mode is activated by \`data-theme="dark"\` on any ancestor element.
+> All semantic design tokens adapt automatically — no per-component changes needed.
+
+## How It Works
+
+\`\`\`html
+<!-- Light mode (default) -->
+<div>...</div>
+
+<!-- Dark mode — applies to this element and all descendants -->
+<div data-theme="dark">...</div>
+\`\`\`
+
+Unity UI uses Tailwind's **selector strategy** (\`[data-theme="dark"]\`), not the class or media-query strategy.
+Configure Tailwind accordingly if you need \`dark:\` in custom components:
+
+\`\`\`ts
+// tailwind.config.ts
+export default {
+  darkMode: ['selector', '[data-theme="dark"]'],
+};
+\`\`\`
+
+## React ThemeProvider
+
+\`\`\`tsx
+import { createContext, useContext, useEffect, useState } from 'react';
+
+type Theme = 'light' | 'dark';
+
+const ThemeContext = createContext<{
+  theme: Theme;
+  toggleTheme: () => void;
+}>({ theme: 'light', toggleTheme: () => {} });
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    const stored = localStorage.getItem('theme') as Theme | null;
+    if (stored) return stored;
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  });
+
+  // Sync with OS preference changes (only when no stored preference)
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = (e: MediaQueryListEvent) => {
+      if (!localStorage.getItem('theme')) {
+        setTheme(e.matches ? 'dark' : 'light');
+      }
+    };
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  const toggleTheme = () => {
+    setTheme((t) => {
+      const next = t === 'light' ? 'dark' : 'light';
+      localStorage.setItem('theme', next);
+      return next;
+    });
+  };
+
+  return (
+    <ThemeContext.Provider value={{ theme, toggleTheme }}>
+      <div data-theme={theme} style={{ minHeight: '100vh' }}>
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  );
+}
+
+export const useTheme = () => useContext(ThemeContext);
+\`\`\`
+
+Wrap the app root:
+
+\`\`\`tsx
+// main.tsx
+<ThemeProvider>
+  <App />
+</ThemeProvider>
+\`\`\`
+
+## Theme Toggle Button
+
+\`\`\`tsx
+import { Button } from '@zvoove/unity-ui';
+import { useTheme } from './ThemeProvider';
+
+export function ThemeToggle() {
+  const { theme, toggleTheme } = useTheme();
+
+  return (
+    <Button
+      variant="ghost"
+      icon={theme === 'dark' ? 'Sun' : 'Moon'}
+      onClick={toggleTheme}
+      aria-label={
+        theme === 'dark'
+          ? 'Zum hellen Modus wechseln'
+          : 'Zum dunklen Modus wechseln'
+      }
+    />
+  );
+}
+\`\`\`
+
+Place it in \`TopBar\`'s \`actions\` prop:
+
+\`\`\`tsx
+<TopBar title="Meine App" actions={<ThemeToggle />} />
+\`\`\`
+
+## Token Behaviour in Dark Mode
+
+Semantic tokens adapt automatically — no \`dark:\` prefix needed for these:
+
+| Token | Light | Dark |
+|-------|-------|------|
+| \`bg-surface\` | white / light gray | dark gray |
+| \`bg-primary\` | brand color | lighter brand color |
+| \`text-on-surface\` | near-black | near-white |
+| \`text-on-surface-variant\` | gray | lighter gray |
+| \`border-outline\` | gray border | darker border |
+| \`bg-background\` | page background | dark page background |
+
+Only use \`dark:\` for values **outside** the token system (custom hex colors, images, etc.).
+
+## Storybook Dark Mode
+
+\`\`\`tsx
+// In a story file
+export const DarkMode: Story = {
+  decorators: [
+    (Story) => (
+      <div data-theme="dark" style={{ padding: '1rem', background: 'var(--color-background)' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+\`\`\`
+
+Or use the Storybook backgrounds addon — set the decorator on the global level in \`preview.ts\`.
+
+## Rules
+
+- NEVER use \`prefers-color-scheme\` CSS to apply dark mode — use \`data-theme="dark"\`
+- NEVER use \`className="dark"\` — Unity UI uses the selector strategy, not the class strategy
+- Semantic tokens adapt automatically — only add \`dark:\` for custom non-token values
+- Persist theme in \`localStorage\` to avoid a flash-of-wrong-theme on reload
+- Do not apply \`data-theme\` to \`<html>\` or \`<body>\` unless your React root is there
+`
+  );
+}
+
+function generateMigrateShadcnSkill(componentNames) {
+  const description = [
+    'Step-by-step guide for migrating a shadcn/ui codebase to @zvoove/unity-ui.',
+    'TRIGGER when: user wants to migrate from shadcn/ui to Unity UI, or is converting shadcn/ui components.',
+    'DO NOT keep shadcn/ui imports alongside Unity UI — replace fully.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-migrate-shadcn',
+    `description: "${description}"`,
+    'category: migration',
+    '---',
+  ].join('\n');
+
+  const componentRows = componentNames
+    .filter((n) => SHADCN_MAP[n])
+    .map((n) => {
+      const s = SHADCN_MAP[n];
+      const note = s.note ? ` _(${s.note})_` : '';
+      return `| [${s.name}](${s.url}) | \`<${n} />\` | \`unity-ui-${kebabCase(n)}\`${note} |`;
+    });
+
+  const noEquivalent = componentNames
+    .filter((n) => !SHADCN_MAP[n])
+    .map(
+      (n) => `- **${n}** — load skill \`unity-ui-${kebabCase(n)}\` for usage`
+    )
+    .join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Migrating from shadcn/ui to Unity UI
+
+## Step-by-Step Process
+
+1. **Install Unity UI** — see \`unity-ui-setup\` skill
+2. **Run a global find** for \`from "@/components/ui/\` and \`from "~/components/ui/\` — those are shadcn/ui imports
+3. **Replace each component** using the table below — load the \`unity-ui-<component>\` skill for full props
+4. **Replace styling** — remove Tailwind class-heavy JSX and use Unity UI props instead
+5. **Remove shadcn/ui** — delete the \`components/ui/\` folder and uninstall \`class-variance-authority\`, \`cmdk\`, \`@radix-ui\` etc.
+
+## Component Map
+
+| shadcn/ui | Unity UI | Skill |
+|-----------|----------|-------|
+${componentRows.join('\n')}
+
+## Unity UI–Only Components (no shadcn/ui equivalent)
+
+${noEquivalent}
+
+## Common Prop Differences
+
+| Pattern | shadcn/ui | Unity UI |
+|---------|-----------|----------|
+| Text input | \`<Input />\` | \`<TextField label="..." />\` |
+| Validation error | custom error \`<p>\` | \`error={true} errorMessage="..."\` |
+| Button icon | wrap with \`<Icon />\` | \`icon="IconName"\` prop |
+| Loading state | manual spinner | \`loading={true}\` prop (Button) |
+| Form field wrapper | \`<FormField>\` + \`<FormControl>\` | direct Controller render |
+| Toast | \`toast("msg")\` from sonner | \`addSnackbar("msg")\` from useSnackbar |
+| Sheet position | \`side="right"\` | \`anchor="right"\` |
+
+## Removing shadcn/ui
+
+\`\`\`bash
+# Remove shadcn/ui dependencies
+npm uninstall @radix-ui/react-* class-variance-authority cmdk lucide-react
+
+# Delete the generated component folder
+rm -rf src/components/ui
+\`\`\`
+
+## Rules
+
+- NEVER keep shadcn/ui and Unity UI components side-by-side — migrate fully
+- Replace all \`cn()\` usage in component files with \`twMerge()\` from tailwind-merge
+- shadcn/ui uses \`className\` extensively — Unity UI uses props (variant, size, etc.); remove the class overrides
+- Import everything from \`@zvoove/unity-ui\`, never from local \`components/ui/\`
+`
+  );
+}
+
+function generateMigrateMuiSkill(componentNames) {
+  const description = [
+    'Step-by-step guide for migrating a Material UI (MUI) codebase to @zvoove/unity-ui.',
+    'TRIGGER when: user wants to migrate from MUI (@mui/material) to Unity UI, or is converting MUI components.',
+    'DO NOT keep MUI imports alongside Unity UI — replace fully.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-migrate-mui',
+    `description: "${description}"`,
+    'category: migration',
+    '---',
+  ].join('\n');
+
+  const componentRows = componentNames
+    .filter((n) => MUI_MAP[n])
+    .map((n) => {
+      const m = MUI_MAP[n];
+      const note = m.note ? ` _(${m.note})_` : '';
+      return `| [${m.name}](${m.url}) | \`<${n} />\` | \`unity-ui-${kebabCase(n)}\`${note} |`;
+    });
+
+  const noEquivalent = componentNames
+    .filter((n) => !MUI_MAP[n])
+    .map(
+      (n) => `- **${n}** — load skill \`unity-ui-${kebabCase(n)}\` for usage`
+    )
+    .join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Migrating from MUI to Unity UI
+
+## Step-by-Step Process
+
+1. **Install Unity UI** — see \`unity-ui-setup\` skill
+2. **Run a global find** for \`from "@mui/material\` and \`from "@mui/x-\` — those are MUI imports
+3. **Replace each component** using the table below — load the \`unity-ui-<component>\` skill for full props
+4. **Replace the sx prop** — MUI's \`sx\` system does not exist in Unity UI; use Tailwind tokens instead (load \`unity-ui-styling\`)
+5. **Remove ThemeProvider** — Unity UI uses \`data-theme="dark"\` for dark mode; load \`unity-ui-dark-mode\`
+6. **Uninstall MUI** after all components are replaced
+
+## Component Map
+
+| MUI | Unity UI | Skill |
+|-----|----------|-------|
+${componentRows.join('\n')}
+
+## Unity UI–Only Components (no MUI equivalent)
+
+${noEquivalent}
+
+## Common Pattern Differences
+
+| Pattern | MUI | Unity UI |
+|---------|-----|----------|
+| Theming | \`<ThemeProvider theme={theme}>\` | \`data-theme="dark"\` attribute |
+| Dark mode | \`createTheme({ palette: { mode: 'dark' } })\` | \`data-theme="dark"\` on container |
+| Inline styles | \`sx={{ mt: 2, color: 'primary.main' }}\` | Tailwind tokens: \`className="mt-md text-primary"\` |
+| Custom style prop | \`sx={{ ... }}\` | \`className\` with token classes |
+| Text field | \`<TextField variant="outlined" label="..." />\` | \`<TextField label="..." />\` |
+| Grid v2 | \`<Grid container spacing={2}>\` | \`<Grid columns={3} gap="md">\` |
+| Stack spacing | \`<Stack spacing={2}>\` | \`<Stack gap="md">\` |
+| Icons | \`import EditIcon from '@mui/icons-material/Edit'\` | \`<Icon name="Pencil" />\` |
+| Button loading | \`<LoadingButton loading>\` | \`<Button loading>\` |
+| Alert | \`<Alert severity="error">\` | \`<InfoBox variant="error">\` |
+| Snackbar | \`<Snackbar>...</Snackbar>\` (imperative) | \`addSnackbar()\` from \`useSnackbar()\` |
+
+## Replacing the sx Prop
+
+MUI's \`sx\` prop maps CSS properties to theme values. Replace with Tailwind design tokens:
+
+\`\`\`tsx
+// MUI
+<Box sx={{ mt: 2, mb: 3, color: 'text.secondary', bgcolor: 'background.paper' }}>
+
+// Unity UI
+<Stack direction="column" gap="md" className="text-on-surface-variant bg-surface">
+\`\`\`
+
+See the \`unity-ui-styling\` skill for the full token reference.
+
+## Removing MUI
+
+\`\`\`bash
+npm uninstall @mui/material @mui/x-date-pickers @mui/icons-material @emotion/react @emotion/styled
+\`\`\`
+
+## Rules
+
+- NEVER keep MUI and Unity UI components side-by-side — migrate fully
+- The \`sx\` prop does not exist in Unity UI — use \`className\` with token classes or component props
+- MUI icons do not exist in Unity UI — use \`<Icon name="..." />\` (load \`unity-ui-icons\` skill for names)
+- Remove \`ThemeProvider\` and \`CssBaseline\` from MUI; Unity UI uses CSS custom properties from \`theme.css\`
+- Import everything from \`@zvoove/unity-ui\`
+`
+  );
+}
+
+function generateFigmaCodeConnectSkill() {
+  const description = [
+    'Figma Code Connect setup for @zvoove/unity-ui — links Figma components to Unity UI React components.',
+    'TRIGGER when: user wants to set up Figma Code Connect, link design components to code, or improve design-to-code accuracy in a Unity UI project.',
+    'DO NOT use this for general Figma-to-code generation — Code Connect is for mapping design components to existing code components.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-figma-code-connect',
+    `description: "${description}"`,
+    'category: tooling',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Figma Code Connect
+
+> Code Connect links Figma components to Unity UI React components so that when a designer shares a Figma URL, the AI knows exactly which component and props to use.
+
+## Install
+
+\`\`\`bash
+npm install --save-dev @figma/code-connect
+\`\`\`
+
+## Configuration
+
+Create \`figma.config.json\` at the project root:
+
+\`\`\`json
+{
+  "codeConnect": {
+    "parser": "react",
+    "include": ["src/**/*.figma.tsx"],
+    "importPaths": {
+      "@zvoove/unity-ui": "@zvoove/unity-ui"
+    }
+  }
+}
+\`\`\`
+
+## How to Get the Figma Node ID
+
+1. Open the Unity UI Figma design file
+2. Select the component you want to connect
+3. Copy the URL — it contains \`node-id=<nodeId>\`
+4. Convert \`-\` to \`:\` in the node ID (e.g. \`123-456\` → \`123:456\`)
+
+## Mapping File Structure
+
+Create a \`.figma.tsx\` file next to each component (or in a \`figma/\` folder):
+
+\`\`\`tsx
+// src/figma/Button.figma.tsx
+import figma from '@figma/code-connect';
+import { Button } from '@zvoove/unity-ui';
+
+figma.connect(
+  Button,
+  'https://www.figma.com/design/<FILE_KEY>/<FILE_NAME>?node-id=<NODE_ID>',
+  {
+    props: {
+      variant: figma.enum('Variant', {
+        filled: 'filled',
+        outlined: 'outlined',
+        ghost: 'ghost',
+        text: 'text',
+      }),
+      size: figma.enum('Size', {
+        sm: 'sm',
+        md: 'md',
+        lg: 'lg',
+      }),
+      disabled: figma.boolean('Disabled'),
+      label: figma.string('Label'),
+    },
+    example: ({ variant, size, disabled, label }) => (
+      <Button variant={variant} size={size} disabled={disabled}>
+        {label}
+      </Button>
+    ),
+  }
+);
+\`\`\`
+
+## Example: TextField
+
+\`\`\`tsx
+// src/figma/TextField.figma.tsx
+import figma from '@figma/code-connect';
+import { TextField } from '@zvoove/unity-ui';
+
+figma.connect(
+  TextField,
+  'https://www.figma.com/design/<FILE_KEY>/<FILE_NAME>?node-id=<NODE_ID>',
+  {
+    props: {
+      label: figma.string('Label'),
+      placeholder: figma.string('Placeholder'),
+      error: figma.boolean('Error'),
+      disabled: figma.boolean('Disabled'),
+    },
+    example: ({ label, placeholder, error, disabled }) => (
+      <TextField
+        label={label}
+        placeholder={placeholder}
+        error={error}
+        disabled={disabled}
+      />
+    ),
+  }
+);
+\`\`\`
+
+## Publish to Figma
+
+\`\`\`bash
+# Preview what will be published (dry run)
+npx figma connect publish --dry-run --token <FIGMA_ACCESS_TOKEN>
+
+# Publish
+npx figma connect publish --token <FIGMA_ACCESS_TOKEN>
+\`\`\`
+
+Store the token in \`.env.local\` (never commit it):
+
+\`\`\`bash
+FIGMA_ACCESS_TOKEN=figd_xxxxxxxx
+\`\`\`
+
+\`\`\`bash
+npx figma connect publish --token $FIGMA_ACCESS_TOKEN
+\`\`\`
+
+## Figma Prop Types Reference
+
+| Figma layer type | Code Connect helper | Example |
+|-----------------|---------------------|---------|
+| Variant property | \`figma.enum()\` | \`figma.enum('Variant', { filled: 'filled' })\` |
+| Boolean property | \`figma.boolean()\` | \`figma.boolean('Disabled')\` |
+| Text layer | \`figma.string()\` | \`figma.string('Label')\` |
+| Instance swap | \`figma.instance()\` | \`figma.instance('Icon')\` |
+| Nested instance | \`figma.nestedProps()\` | \`figma.nestedProps('Slot', { ... })\` |
+
+## Rules
+
+- Create one \`.figma.tsx\` file per component
+- The Figma URL must point to the **main component** (not an instance or frame)
+- Prop names in \`figma.enum()\` must match Figma's exact property names (case-sensitive)
+- Never commit Figma access tokens — use environment variables
+- After updating, republish with \`npx figma connect publish\`
+`
+  );
+}
+
+function generateUmbrellaSkill(componentNames) {
+  const description = [
+    'Unity UI (@zvoove/unity-ui) component library router. Use this as the entry point when building UI with this package.',
+    'TRIGGER when: user wants to build UI, use a component, or migrate/convert a UI from any source (Lovable, Figma Make, shadcn/ui, MUI, Ant Design, etc.) into this design system.',
+    'DO NOT TRIGGER when: @zvoove/unity-ui is not installed in the project.',
+  ].join(String.raw`\n`);
+
+  const componentList = componentNames
+    .map((n) => `- ${n} → load skill \`unity-ui-${kebabCase(n)}\``)
+    .join('\n');
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui',
+    `description: "${description}"`,
+    'category: routing',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Component Router
+
+> **@zvoove/unity-ui** is installed in this project. Use the skills below — do NOT read \`dist/\`, \`node_modules/\`, or source files for API documentation.
+
+## How to Use
+
+1. Find the component you need in the directory below
+2. Load its \`unity-ui-<component>\` skill for full props, examples, and rules
+3. Import exclusively from \`@zvoove/unity-ui\` — never from dist paths
+
+## Component Directory
+
+${componentList}
+
+## Rules
+
+- NEVER read \`dist/\` or \`node_modules/@zvoove/unity-ui/\` for type/API information — skills have everything
+- NEVER create custom components for functionality already provided by this library
+- Always import from \`@zvoove/unity-ui\`
+- If unsure which component to use, load \`unity-ui-index\` for the full shadcn/ui equivalence table
+
+## Migrating from Other Libraries
+
+If the project contains components from shadcn/ui, MUI, Ant Design, Lovable, Figma Make, or any other source:
+- **Replace them with Unity UI equivalents** — do not keep mixed component libraries
+- Load \`unity-ui-index\` to find the equivalent Unity UI component
+- Remove the replaced library's imports and dependencies once converted
+- Prefer Unity UI over any other component library, regardless of what already exists in the codebase
+`
+  );
+}
+
+// ─── Write skills to disk ───────────────────────────────────────────────────
+
+function writeSkill(outputDir, slug, content) {
+  const skillDir = path.join(outputDir, slug);
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content, 'utf8');
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  const { outputBase } = parseArgs(process.argv);
+
+  const llmsPath = findLlmsTxt();
+  if (!llmsPath) {
+    console.error(
+      'Could not find llms.txt. Make sure @zvoove/unity-ui is installed and built.'
+    );
+    process.exit(1);
+  }
+
+  const projectRoot = process.cwd();
+  const outputDir = path.resolve(projectRoot, outputBase, 'skills');
+  const content = fs.readFileSync(llmsPath, 'utf8');
+  const parsed = parseLlmsTxt(content);
+
+  // Clean previous unity-ui skills (leave other skills untouched)
+  if (fs.existsSync(outputDir)) {
+    for (const entry of fs.readdirSync(outputDir)) {
+      if (entry.startsWith('unity-ui-')) {
+        fs.rmSync(path.join(outputDir, entry), { recursive: true });
+      }
+    }
+  }
+
+  const componentNames = Object.keys(parsed.components).sort();
+  let count = 0;
+
+  // Component skills
+  for (const [name, componentContent] of Object.entries(parsed.components)) {
+    writeSkill(
+      outputDir,
+      `unity-ui-${kebabCase(name)}`,
+      generateComponentSkill(name, componentContent)
+    );
+    count++;
+  }
+
+  // Meta skills
+  writeSkill(outputDir, 'unity-ui', generateUmbrellaSkill(componentNames));
+  writeSkill(outputDir, 'unity-ui-setup', generateSetupSkill(parsed));
+  writeSkill(outputDir, 'unity-ui-styling', generateStylingSkill(parsed));
+  writeSkill(
+    outputDir,
+    'unity-ui-custom-component',
+    generateCustomComponentSkill(parsed)
+  );
+  writeSkill(outputDir, 'unity-ui-icons', generateIconsSkill(parsed));
+  writeSkill(outputDir, 'unity-ui-index', generateIndexSkill(componentNames));
+  writeSkill(outputDir, 'unity-ui-forms', generateFormsSkill());
+  writeSkill(outputDir, 'unity-ui-layouts', generateLayoutsSkill());
+  writeSkill(outputDir, 'unity-ui-dark-mode', generateDarkModeSkill());
+  writeSkill(
+    outputDir,
+    'unity-ui-migrate-shadcn',
+    generateMigrateShadcnSkill(componentNames)
+  );
+  writeSkill(
+    outputDir,
+    'unity-ui-migrate-mui',
+    generateMigrateMuiSkill(componentNames)
+  );
+  writeSkill(
+    outputDir,
+    'unity-ui-figma-code-connect',
+    generateFigmaCodeConnectSkill()
+  );
+  count += 12;
+
+  const relOutput = path.relative(projectRoot, outputDir);
+  console.log(`\n  Unity UI — Agent Skills Generator\n`);
+  console.log(`  ✅ Generated ${count} skills in ${relOutput}/\n`);
+  console.log(`     ${componentNames.length} component skills`);
+  console.log(`     1 umbrella routing skill (entry point + migration rules)`);
+  console.log(`     1 setup skill (installation, spacing, responsive props)`);
+  console.log(
+    `     1 styling skill (Tailwind v4 tokens, tv(), no inline styles)`
+  );
+  console.log(
+    `     1 custom component skill (patterns for creating new components)`
+  );
+  console.log(`     1 icons skill (all icon names)`);
+  console.log(`     1 index skill (shadcn/ui + MUI mapping tables)`);
+  console.log(
+    `     1 forms skill (react-hook-form + zod + Controller pattern)`
+  );
+  console.log(
+    `     1 layouts skill (app shells, dashboards, settings, master/detail)`
+  );
+  console.log(
+    `     1 dark mode skill (data-theme, ThemeProvider, token behaviour)`
+  );
+  console.log(
+    `     1 migrate-shadcn skill (step-by-step shadcn/ui → Unity UI)`
+  );
+  console.log(`     1 migrate-mui skill (step-by-step MUI → Unity UI)`);
+  console.log(
+    `     1 figma-code-connect skill (Code Connect setup and mappings)\n`
+  );
+  console.log(`  Your AI agent can now discover and use Unity UI components.`);
+  console.log(`  Skills are loaded on-demand — only relevant ones are read.\n`);
+}
+
+main();