SKILL.md vs CLAUDE.md vs .cursorrules: Which AI Rules File Do You Need?

There are five different AI rules file formats floating around. SKILL.md. CLAUDE.md. .cursorrules. .cursor/rules/. .github/copilot-instructions.md. Each tool reads a different format. Each format has different rules for where to place it and how Claude interprets it.

This creates confusion. You don't need all five. You need to match the right file format to the tool you're using.

This guide breaks down the five formats, shows which tool uses which, and gives you working examples for each one. By the end, you'll know exactly what file to create for Claude Code, Cursor, and Copilot.

The 5 AI Config File Formats (Compared)

CLAUDE.md

CLAUDE.md loads on every Claude Code prompt. It's for universal rules that apply across your entire project: coding standards, architecture decisions, folder structure conventions.

Location: Project root

Loads: Automatically, on every prompt

Best for: Global rules that apply everywhere

SKILL.md

SKILL.md lives inside .claude/skills/[skill-name]/ and loads only when relevant. It's for domain-specific rules: design system constraints, testing patterns, database schemas.

Location: .claude/skills/design/SKILL.md, .claude/skills/testing/SKILL.md, etc.

Loads: When Claude Code detects matching content (e.g., "SKILL.md" in .claude/skills/design/ loads when you ask about component creation)

Best for: Focused, domain-specific constraints (design system, testing conventions, API patterns)

.cursorrules (Legacy)

The old Cursor format. Still works, but Cursor is moving away from it.

Location: Project root

Loads: Automatically, on every prompt

Best for: Simple projects where you don't need file-specific rules

.cursor/rules/*.mdc (Modern)

Cursor's new format. MDC files support frontmatter with glob patterns, so you can target rules to specific file types.

Location: .cursor/rules/design.mdc, .cursor/rules/api.mdc, etc.

Loads: When the file you're editing matches the glob pattern

Best for: Targeted rules (e.g., design rules only for TSX files, API rules only for API routes)

.github/copilot-instructions.md

GitHub Copilot's format. If you use Copilot for completions or chat, place your rules here.

Location: .github/copilot-instructions.md

Loads: Automatically, on every request

Best for: Teams using GitHub Copilot

Which File to Use for Design System Constraints

You want one design system file that works everywhere. Here's the decision tree:

Using Claude Code only? Create .claude/skills/design/SKILL.md.

Using Cursor only? Create .cursor/rules/design.mdc.

Using both Claude Code and Cursor? Create both. Same constraints, different format.

Using Copilot? Create .github/copilot-instructions.md.

Using all three? Create all three. They're not mutually exclusive.

Claude Code: SKILL.md in .claude/skills/design/

# Design System

## Components to use
Always import from these paths:
- Buttons: `@/components/ui/button`
- Forms: `@/components/ui/form`
- Cards: `@/components/ui/card`
- Dialogs: `@/components/ui/dialog`
- Inputs: `@/components/ui/input`
- Selects: `@/components/ui/select`

Never write inline button styles. Always use the Button component with a variant.

## Color tokens
- Primary: `--color-primary`
- Secondary: `--color-secondary`
- Success: `--color-success`
- Warning: `--color-warning`
- Error: `--color-error`
- Text: `--color-text`
- Border: `--color-border`

Use these in className: `bg-[--color-primary] text-white`

## Spacing tokens
- xs: `--spacing-xs` (0.25rem)
- sm: `--spacing-sm` (0.5rem)
- md: `--spacing-md` (1rem)
- lg: `--spacing-lg` (1.5rem)
- xl: `--spacing-xl` (2rem)

Use in className: `p-[--spacing-md] gap-[--spacing-sm]`

## Radius tokens
- sm: `--radius-sm`
- md: `--radius-md`
- lg: `--radius-lg`
- full: `--radius-full`

## Font sizes
- sm: `--font-size-sm` for labels
- base: `--font-size-base` for body
- lg: `--font-size-lg` for subheadings
- xl: `--font-size-xl` for headings
- 2xl: `--font-size-2xl` for page titles

## Forbidden patterns
- No hardcoded colors like `bg-blue-500` or `text-red-700`
- No inline styles
- No custom button components (use the Button component)
- No single-use CSS files
- No multiple font families (use `--font-family-sans`)

Place this in .claude/skills/design/SKILL.md at the project root. Claude Code reads this and follows the constraints during component generation.

Cursor: .cursor/rules/design.mdc

---
globs: ["**/*.tsx", "**/*.jsx"]
---

# Design System

## Always import from these paths

When writing React components, import from:
- Button: `import { Button } from "@/components/ui/button"`
- Form: `import { Form, FormField, FormControl, FormLabel } from "@/components/ui/form"`
- Card: `import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"`
- Dialog: `import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"`
- Input: `import { Input } from "@/components/ui/input"`
- Select: `import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"`

Never write inline component styles. Always compose with pre-styled components.

## Use color tokens instead of hardcoded colors

Replace all hardcoded Tailwind colors with CSS custom properties:
- `bg-[--color-primary]` instead of `bg-blue-500`
- `text-[--color-text]` instead of `text-gray-900`
- `border-[--color-border]` instead of `border-gray-300`

Color tokens available:
- `--color-primary` (blue)
- `--color-secondary` (purple)
- `--color-success` (green)
- `--color-warning` (amber)
- `--color-error` (red)
- `--color-text` (primary text)
- `--color-text-secondary` (secondary text)
- `--color-border` (dividers)
- `--color-background` (page background)
- `--color-surface` (card background)

## Use spacing tokens

Replace hardcoded spacing with tokens:
- `p-[--spacing-md]` instead of `p-4`
- `gap-[--spacing-sm]` instead of `gap-2`
- `mb-[--spacing-lg]` instead of `mb-6`

Tokens: `--spacing-xs` (0.25rem), `--spacing-sm` (0.5rem), `--spacing-md` (1rem), `--spacing-lg` (1.5rem), `--spacing-xl` (2rem)

## Use radius tokens

- `rounded-[--radius-sm]` for small elements (inputs, small buttons)
- `rounded-[--radius-md]` for standard elements (cards, buttons)
- `rounded-[--radius-lg]` for large elements (modals, sections)
- `rounded-[--radius-full]` for circles and pills

## Font sizing

Use semantic font sizes from tokens:
- `text-[--font-size-sm]` for labels
- `text-[--font-size-base]` for body text (default)
- `text-[--font-size-lg]` for subheadings
- `text-[--font-size-xl]` for section headings
- `text-[--font-size-2xl]` for page titles

## Never do this

- Don't use hardcoded Tailwind classes like `bg-gray-100` or `text-blue-600`
- Don't write inline styles
- Don't create single-use CSS files
- Don't duplicate component code
- Don't use arbitrary Tailwind values without token references

Place this in .cursor/rules/design.mdc. The frontmatter globs: ["**/*.tsx", "**/*.jsx"] tells Cursor to apply these rules only to React component files.

One Design System, Three Formats (Side by Side)

Here's the same design system constraint written in all three formats so you can see the pattern:

Constraint: "Use Button component, never hardcoded styles"

SKILL.md (Claude Code):

## Button rules
Always use the Button component from `@/components/ui/button`.
Never write button styles inline or with Tailwind utilities alone.
Use variant prop: `<Button variant="default">` for primary, `variant="outline"` for secondary.

.cursor/rules/design.mdc (Cursor):

## Button component rules
Import Button: `import { Button } from "@/components/ui/button"`
Use variants for styling:
- `<Button variant="default">` for primary actions
- `<Button variant="secondary">` for secondary actions
- `<Button variant="outline">` for tertiary actions
- `<Button variant="ghost">` for minimal actions
Never write inline button styles or hardcoded Tailwind classes.

copilot-instructions.md (Copilot):

## Button Component Rules

Always import Button from @/components/ui/button.
Use the Button component instead of writing button styles manually.

Button variants available:
- variant="default": filled background, primary color
- variant="secondary": secondary color background
- variant="outline": border only, no background fill
- variant="ghost": text only, no background or border

Never write: <button className="bg-blue-500">
Do write: <Button variant="default">

Each format follows the tool's conventions. Cursor prefers code examples. Claude Code prefers markdown lists. Copilot prefers clear declarations.

What to Put IN the Rules File

Include these things in your rules file:

• Component import paths (exact paths from your codebase)
• Token names and their meanings (color tokens, spacing tokens)
• Forbidden patterns (what to never do)
• Variant options (for components with variants)
• File organization expectations (folder structure)
• Naming conventions (for variables, functions, components)

Here's a complete design system rules file:

# Design System Rules

## Component Imports
- Button: `import { Button } from "@/components/ui/button"`
- Form: `import { Form, FormField, FormControl, FormLabel } from "@/components/ui/form"`
- Card: `import { Card, CardContent, CardHeader } from "@/components/ui/card"`
- Dialog: `import { Dialog, DialogContent } from "@/components/ui/dialog"`
- Dropdown: `import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/ui/dropdown-menu"`

Never create new component files with similar names.

## Colors
Use these token names in className attributes:
- Primary action color: `bg-[--color-primary]` or `text-[--color-primary]`
- Secondary actions: `bg-[--color-secondary]`
- Success feedback: `text-[--color-success]`
- Warning feedback: `text-[--color-warning]`
- Error feedback: `text-[--color-error]`
- Body text: `text-[--color-text]`
- Borders and dividers: `border-[--color-border]`
- Page background: `bg-[--color-background]`

Never use hardcoded colors like `bg-blue-500` or `text-gray-700`.

## Spacing
Use these semantic spacing tokens:
- Extra small: `--spacing-xs` for icon-text gaps
- Small: `--spacing-sm` for tight spacing
- Medium: `--spacing-md` for standard spacing (default for card padding)
- Large: `--spacing-lg` for loose spacing
- Extra large: `--spacing-xl` for very loose spacing

## Buttons
Use Button component with these variants:
- `variant="default"`: Primary action button (filled blue)
- `variant="secondary"`: Secondary action button (filled purple)
- `variant="outline"`: Tertiary action button (border only)
- `variant="ghost"`: Minimal action button (text only)
- `size="sm"`: Compact button
- `size="md"`: Standard button (default)
- `size="lg"`: Prominent button

## Forms
Always use the Form component wrapper. Never create form inputs without the FormField wrapper.
Use semantic HTML: label, input, textarea, select.
Never apply custom styles to form elements; use the provided Form components.

## Forbidden Patterns
- No hardcoded color values like `bg-blue-500`, `text-gray-700`
- No inline style attributes
- No custom button or input components (use provided components)
- No single-use CSS files
- No multiple font families (stick to `--font-family-sans`)
- No arbitrary Tailwind values without token references

What to Keep OUT of the Rules File

Don't include:

• Entire architecture documents (too long, AI ignores it)
• Git workflow instructions (unrelated to code generation)
• Team processes (not relevant to AI code)
• Detailed design philosophy essays (save this for docs)
• Line-by-line code examples unless critical
• More than 150-200 lines total (hits AI token limits)

Keep it focused. Design system only.

How Matchkit Generates These Automatically

Matchkit designs a visual configuration: you set colors, spacing, radius, shadows, typography. You configure your 11 design axes. You upload a logo.

Then Matchkit generates:

1. globals.css with your complete token set
2. src/components/ui/ with pre-styled component library
3. .claude/skills/design/SKILL.md with Claude Code rules
4. .cursor/rules/design.mdc with Cursor rules
5. .github/copilot-instructions.md with Copilot rules

All three rules files reference the same tokens and components. No manual formatting. No switching between formats. Download as a ZIP file and place in your project.

This is why many teams skip the manual approach. Generating these files ensures consistency and saves hours of work.

Frequently Asked Questions

Q: What is SKILL.md in Claude Code?

A: SKILL.md is a markdown file inside .claude/skills/[skill-name]/ that gives Claude Code domain-specific instructions. Unlike CLAUDE.md (which loads on every prompt), SKILL.md loads only when triggered by matching content. For design systems, it contains typography rules, color token references, spacing values, component import paths, and forbidden patterns that Claude follows during UI code generation.

Q: What's the difference between CLAUDE.md and SKILL.md?

A: CLAUDE.md sits in the project root and loads on every Claude Code prompt. It's for universal rules (coding style, architecture decisions). SKILL.md sits in .claude/skills/[name]/ and loads only when relevant. For design, use SKILL.md: it keeps design constraints separate from coding rules, preventing context overload. Claude processes about 150-200 instructions with reasonable consistency, so splitting concerns matters.

Q: Should I use .cursorrules or .cursor/rules/ for Cursor?

A: Use .cursor/rules/ with MDC files. The old .cursorrules format is being deprecated. MDC files support frontmatter with glob patterns (e.g., globs: ["**/*.tsx"]), letting you target design rules specifically to component files. This prevents design instructions from interfering with backend or API code generation.

Now that you understand which rules file to use, learn how to write one. Read "How to Build a Design System Your AI Coding Tool Actually Follows" for the complete system architecture and working code examples for each file.

Or skip the manual setup entirely and generate your rules files in Matchkit—configure your design visually and download complete SKILL.md, .cursor/rules/design.mdc, and copilot-instructions.md files ready to go.