Agent context

What is packages/skill?

packages/skill is machine-readable context for AI coding agents. It describes design tokens, component APIs, patterns, and constraints so agents generate code that fits this codebase — not generic Tailwind output.

These files are not pasted manually. Each framework has its own auto-load mechanism (see below). Once wired, agents pick up the context automatically on every task.

File index

• system.md — Monorepo layout, RSC safety, build commands, dark-mode rules, Tailwind v4 constraints.
• components.md — Every component: named exports, when to use, gotchas.
• tokens.md — Semantic alias groups. Never raw scale tokens.
• patterns.md — Modal/Drawer controlled state, react-hook-form, icon prop, compound components.
• responsive.md — Breakpoints, mobile-first, per-component mobile behavior, dvh vs vh.

Claude Code (CLAUDE.md)

Claude Code reads CLAUDE.md at session start. This repo's CLAUDE.md already references the skill files — no setup needed when working inside the monorepo.

In consumer projects, create a CLAUDE.md at the repo root and reference the installed skill files:

## Design system
Read node_modules/@mvp-ui/skill/system.md before any component work.
Read node_modules/@mvp-ui/skill/tokens.md before writing className strings.
Read node_modules/@mvp-ui/skill/components.md before importing components.

Cursor

Cursor auto-loads rules from .cursor/rules/. Create one rule file per skill file so Cursor can attach them selectively by glob:

# .cursor/rules/mvp-ui-tokens.mdc
---
globs: ["**/*.tsx", "**/*.ts"]
---
{contents of packages/skill/tokens.md}

Or reference the file path directly if using Cursor's @file mention in chat — Cursor reads the file on demand.

Windsurf

Windsurf reads .windsurfrules at the repo root. Concatenate the relevant skill files or symlink them:

# .windsurfrules
{contents of packages/skill/system.md}
{contents of packages/skill/tokens.md}

GitHub Copilot

Copilot reads .github/copilot-instructions.md. Paste the skill content or keep a short pointer to the most critical rules:

# Component library
Import all components from @mvp-ui/ui.
Use semantic token aliases only (bg-bg, text-fg, border-border).
Never use raw scale tokens (gray-900, brand-600) — they break dark mode.
See packages/skill/ for full reference.

Keeping skill files current

Stale skill files produce the same errors as no skill files. Update on every meaningful change:

• New component → add row to components.md
• New token → add to tokens.md
• Architecture change → update system.md
• New pattern → add to patterns.md