Authoring Portable SKILL.md Files for Design Systems

Overview

How It Works

Step-by-Step

1. Step 1: Inventory your design system's canonical values

   md, collect every concrete value your design system defines. Open your Figma tokens, your CSS custom properties, your Tailwind config, or wherever your source of truth lives. Extract: your full color palette with hex or HSL values and semantic names, your spacing scale as a numbered list of pixel values, your typography ramp (font families, sizes, line-heights, weights for each heading level and body text), your border-radius values, your shadow definitions, and your breakpoint widths. Write these into a scratch document exactly as resolved values, not as variable names.

   If your system defines --color-primary as #2563EB, write primary: #2563EB. This step produces a flat list of 40-120 token entries. If you have fewer than 20, your system may be under-specified and you should define the missing values before proceeding.

   Tip: If your design system has tokens that differ between light and dark modes, list both sets explicitly and label them. Agents cannot resolve mode-switching logic from a single token name.

2. Step 2: Document component-level composition rules

   For each major component in your system (buttons, cards, form inputs, navigation, modals, tables, alerts), write a short rule block that specifies: the allowed variants, the token values each variant uses, the required internal spacing, and any forbidden compositions. For example, a button rule block might state that primary buttons use bg: #2563EB, text: #FFFFFF, padding: 10px 20px, border-radius: 8px, font-weight: 600, font-size: 14px and that buttons must never appear inside other buttons or inside anchor tags. A card rule block might state that cards use padding: 24px, border-radius: 12px, border: 1px solid #E5E7EB and that cards must never nest more than one level deep. Each rule block should be 5-15 lines.

   Focus on the components your team uses most frequently, aiming for 8-15 component blocks in a first pass. Skip components you rarely build, since they add context-window cost without proportional benefit.

   Tip: Write one forbidden-composition rule per component block. Agents are surprisingly good at avoiding explicitly named anti-patterns but will happily stumble into them if the anti-pattern is only implied.

3. Step 3: Define aesthetic guardrails and quality thresholds

   This is where you encode taste. Aesthetic guardrails are rules that do not map directly to a single token but govern how tokens combine. , no more than 3 non-neutral colors on a single page). Write these as numbered rules with specific thresholds, not as vague guidance.

   Each rule should be testable: a reviewer should be able to look at the output and determine in under 10 seconds whether the rule was followed. Aim for 8-15 guardrail rules. More than 20 dilutes their impact in the agent's context.

   Tip: Frame guardrails as numeric thresholds wherever possible. 'Generous whitespace' is unenforceable. 'Minimum 32px vertical gap between sections' is testable and the agent can verify it against its own output.

4. Step 4: Write the anti-pattern catalog

   List the specific visual mistakes your team has already seen AI agents make. If you have been using AI coding tools, review the last 10-20 generated components and note every visual issue you had to fix manually. Common entries include: using raw Tailwind gray-500 instead of your system's neutral-500, adding decorative borders or shadows not in the token set, centering everything on the page, using inconsistent icon sizes within a single component, generating overly nested card-in-card layouts, defaulting to 100% width containers without max-width constraints, and using generic sans-serif fallback fonts. For each anti-pattern, write a short name, a one-sentence description of what it looks like, and a one-sentence instruction for what the agent should do instead.

   This section should contain 6-12 entries. It serves as the agent's self-review checklist before presenting output.

   Tip: Pull anti-patterns from real agent output rather than inventing hypothetical ones. The patterns you have actually seen recur are the ones the agent is statistically most likely to reproduce.

5. Step 5: Structure the file with hierarchical headings

   Organize your content into a clean markdown structure that AI agents can parse hierarchically. , # [YourProduct] Design System Instructions). Use H2 for major sections: ## Design Tokens, ## Component Rules, ## Aesthetic Guardrails, ## Anti-Patterns, ## Quality Checklist. , ### Color Tokens, ### Spacing Scale, ### Typography).

   Place your most critical rules in the first two H2 sections because agents weight early content more heavily. Use bullet lists for enumerated rules and fenced code blocks for any literal CSS or class-name examples. Do not use HTML inside the markdown. Do not use images, links to external assets, or relative file paths.

   The entire file should be self-contained plain text. Target 300-800 lines total.

   Tip: Add a 2-3 sentence summary paragraph immediately after the H1 title that states the file's purpose and scope. This paragraph acts as a system-prompt-style instruction that anchors the agent's behavior for the entire file.

6. Step 6: Add a priority ranking to your rules

   Not all rules are equally important. If an agent must choose between respecting your color tokens and respecting your preferred animation easing, you want it to choose colors every time. Add a priority section near the top of the file (right after the summary paragraph) that lists your rules in ranked order. A typical priority list looks like: 1) Color tokens must match exactly, 2) Typography scale must be followed, 3) Spacing scale must be followed, 4) Component composition rules must be respected, 5) Anti-patterns must be avoided, 6) Aesthetic guardrails should be followed, 7) Motion and animation preferences should be followed.

   This ranking gives the agent a tiebreaker when context-window pressure forces it to drop lower-priority rules. It also helps human reviewers know which violations to flag as blocking versus advisory.

   Tip: Use the word 'must' for your top 3-4 priorities and 'should' for everything below. Agents trained on RFC-style language interpret 'must' as a hard constraint and 'should' as a soft preference.

7. Step 7: Write a quality checklist as a terminal section

   Close the file with a numbered checklist that the agent should mentally run before presenting its output. Each item should be a yes/no question. For example: 1) Are all colors from the defined palette? 2) Does the typography use only the specified font sizes and weights?

   3. Is the spacing between elements a multiple from the spacing scale? 4) Are there more than 3 non-neutral colors visible simultaneously? 5) Does any component violate a listed anti-pattern? 6) Is the maximum container width respected?

   4. Is the contrast ratio above threshold for all text? This checklist serves as a final catch-net. Agents that support chain-of-thought reasoning will sometimes explicitly walk through this checklist, catching errors they would otherwise ship. Aim for 7-12 checklist items.

   Each should reference a rule defined earlier in the file so the agent can trace back.

   Tip: Phrase checklist items as questions the agent asks itself about its own output, not as instructions. 'Did I use only palette colors?' triggers self-review behavior more reliably than 'Use only palette colors.'

8. Step 8: Test portability across two different agents

   md must produce acceptable output in at least two different AI coding agents. , Cursor and Claude Code, or v0 and Gemini CLI). Give each agent the same prompt: 'Build a settings page with a sidebar navigation, a form with text inputs and a toggle, and a save button. md and no other context.

   Compare the two outputs against your quality checklist. If both outputs pass at least 80% of the checklist items, your file is portable. If one agent fails significantly, examine which rules it ignored and check whether those rules are too implicit, too deeply nested, or too vaguely worded. Revise and retest.

   Tip: Save the outputs from this test as your baseline. Future edits to the SKILL.md should be regression-tested against the same prompt to ensure you did not accidentally degrade quality.

9. Step 9: Version and iterate with your team

   md to version control alongside your codebase. Treat it as a living document, not a write-once artifact. Establish a lightweight review process: when someone encounters a new anti-pattern in agent output, they add it to the anti-pattern section and open a pull request. md is updated in the same PR as the token source files.

   Review the file quarterly for bloat. md) and load them selectively based on the task. Track a simple quality metric over time: the percentage of agent-generated components that pass design review without redlines on the first attempt. This metric should trend upward as the file matures.

   Tip: Add a changelog comment block at the top of the file with the last-modified date and a one-line summary of the most recent change. This helps team members understand the file's recency and context at a glance.

Examples

Best Practices

• Inline every resolved value rather than referencing external files or variable names. A SKILL.md that says 'use --color-primary' is useless to an agent that cannot resolve CSS custom properties. Write 'primary: #2563EB (use for primary buttons, links, and active states)' instead. This redundancy is the price of portability, and skipping it is the most common reason a file works in one agent but fails in another.

• Front-load your highest-priority rules in the first 100 lines of the file. AI agents allocate attention unevenly across long contexts, giving more weight to content that appears early. If your color tokens are buried under 200 lines of component rules, the agent is more likely to default to generic colors under context-window pressure. Put tokens and the priority ranking at the very top.

• Write one explicit anti-pattern for every positive rule that agents commonly violate. Positive instructions ('use 8px border-radius') are necessary but not sufficient. Negative instructions ('never use border-radius values other than 4px, 8px, or 12px') create a falsifiable check the agent can run against its own output. Pairing positive and negative rules roughly doubles enforcement reliability.

• Keep the file between 300 and 800 lines. Below 300, you almost certainly lack enough constraint specificity for consistent output. Above 800, you risk context-window competition where later rules get dropped or deprioritized. If your system genuinely requires more than 800 lines of rules, split into modular files and load only the relevant module per task.

• Use plain markdown without HTML, images, or external links. Every AI coding agent can parse standard markdown headings, bullets, numbered lists, and fenced code blocks. Not every agent can parse HTML tables, embedded images, or resolve URLs. Stick to the format with the highest compatibility surface.

• Test every major revision with a standardized prompt across two agents before merging. The portability test described in Step 8 should be a recurring gate, not a one-time exercise. Regressions happen when well-intentioned edits inadvertently make a rule ambiguous or push a critical constraint below the context-window cutoff.

• Version-control the SKILL.md alongside your design token source files and update them in the same commit. If your tokens change but your SKILL.md does not, the file becomes a source of drift and agents will generate output that matches the old system. Treating them as coupled artifacts prevents this.

• Assign semantic intent to each token, not just a value. Writing 'neutral-100: #F3F4F6 (page background, card surface on dark mode)' gives the agent application context. Writing only '#F3F4F6' forces the agent to guess where the color belongs, and it will guess wrong often enough to matter.

Common Mistakes

Frequently Asked Questions