Claude Skills

What is a Claude Skill?

A Claude Skill is a markdown file that lives in your project and tells Claude how to behave. It contains your project’s rules, conventions, design tokens, file structure, and coding standards — everything Claude needs to produce consistent, on-brand output every time.

Without a skill file, every conversation with Claude starts from zero. Claude doesn’t remember your preferences, your tech stack, or your design system. You end up repeating the same instructions over and over.

With a skill file, Claude reads your rules at the start of every session and follows them automatically. It’s like onboarding a new developer — but you only have to do it once.

The SKILL.md Pattern

The most common approach is to create a file called SKILL.md (or CLAUDE.md) in the root of your project. Claude automatically reads this file when it starts a session in your project directory.

A good SKILL.md has this structure:

• What This Is — One-line description of the project
• Tech Stack — Frameworks, libraries, versions
• Project Structure — Where things live
• Component Standards — How components should be written
• Design Tokens — Colors, spacing, typography
• Tailwind Conventions — Custom classes, patterns
• File Naming — Naming conventions
• DO NOT — Things Claude should never do
• How to Reference — How to use this file

A Production-Quality SKILL.md Template

Here’s a complete example you can adapt for your own projects:

# SKILL.md

## What This Is
A design system component library for the Acme brand, built with Next.js and Tailwind CSS.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS 3.4
- Framer Motion for animations
- Radix UI for accessible primitives
- Storybook 8 for documentation

## Project Structure
```
src/
  components/
    ui/          # Primitives: Button, Input, Badge, etc.
    layout/      # Header, Footer, Sidebar, Container
    patterns/    # LoginForm, SearchBar, DataTable
  lib/           # Utilities, helpers, hooks
  styles/        # Global CSS, Tailwind config
  stories/       # Storybook stories
```

## Component Standards
- Every component gets its own file: `ComponentName.tsx`
- Use default exports
- Props interface is always named `ComponentNameProps`
- Always include TypeScript types — never use `any`
- Destructure props in the function signature
- Use forwardRef for all interactive elements
- Include JSDoc comments on the props interface

Example:
```tsx
interface ButtonProps {
  /** The button label text */
  label: string
  /** Visual variant */
  variant?: "primary" | "secondary" | "ghost"
  /** Click handler */
  onClick?: () => void
  /** Disabled state */
  disabled?: boolean
}

export default function Button({ label, variant = "primary", onClick, disabled }: ButtonProps) {
  return (
    <button
      className={cn(baseStyles, variantStyles[variant])}
      onClick={onClick}
      disabled={disabled}
    >
      {label}
    </button>
  )
}
```

## Design Tokens
- Primary: #E3002B (Acme Red)
- Secondary: #1A1A1A (Near Black)
- Background: #FFFFFF
- Surface: #F5F5F5
- Border: #E5E5E5
- Text Primary: #1A1A1A
- Text Secondary: #6B7280
- Error: #DC2626
- Success: #16A34A
- Border Radius: 8px (default), 12px (cards), 9999px (pills)
- Font: Inter for body, JetBrains Mono for code

## Tailwind Conventions
- Use design tokens via theme: `text-primary`, `bg-surface`, `border-default`
- Never use arbitrary values like `text-[#E3002B]` — always use token names
- Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64
- Use `cn()` utility for conditional classes (from lib/utils)

## File Naming
- Components: PascalCase (`Button.tsx`, `LoginForm.tsx`)
- Utilities: camelCase (`formatDate.ts`, `useAuth.ts`)
- Stories: `ComponentName.stories.tsx`
- Tests: `ComponentName.test.tsx`
- Pages: lowercase with hyphens (`about-us/page.tsx`)

## DO NOT
- Do not use inline styles
- Do not use CSS modules
- Do not use `any` type
- Do not create files outside the src/ directory
- Do not use default Tailwind colors — always use our tokens
- Do not add new dependencies without asking first
- Do not use `var()` CSS custom properties — use Tailwind classes
- Do not skip TypeScript types on props

## How to Reference
At the start of each session, say:
"Read SKILL.md and follow all rules for this project."
Or reference specific sections:
"Follow the Component Standards from SKILL.md to create a new Badge component."

Prompting Strategies

Starting a Session

At the beginning of every Claude session, reference your skill file explicitly:

"Read SKILL.md and follow all project rules. Then create a new Input component."

This ensures Claude loads all your conventions before it starts generating code.

When Claude Forgets the Rules

Sometimes Claude drifts from your conventions mid-session, especially in long conversations. When this happens, re-anchor it:

"You're drifting from my SKILL.md rules. Re-read SKILL.md and regenerate the last component following all conventions."

"Check my SKILL.md — we don't use inline styles. Refactor to use Tailwind classes only."

Complex Operations

For complex tasks, reference specific sections of your skill file:

"Follow the Component Standards and Design Tokens sections from SKILL.md. Create a Card component with header, body, and footer slots. Use our border-radius and color tokens."

"Using the Project Structure from SKILL.md, create a new pattern component called SearchBar in the correct directory."

Multiple Skills — Different Files

For larger projects, you can split your rules across multiple files. Each file focuses on a specific concern:

The PROMPTS.md Pattern

A PROMPTS.md file stores reusable prompt templates. Instead of writing the same complex prompt every time, you save it once and reference it:

# PROMPTS.md

## New UI Component
Read SKILL.md. Create a new component called [NAME] at src/components/ui/[NAME].tsx.
Follow all Component Standards. Include:
- TypeScript props interface with JSDoc
- All variants: primary, secondary, ghost
- Hover, focus, and disabled states
- Tailwind classes only (no inline styles)
- Default export

## New Pattern Component
Read SKILL.md. Create a new pattern component called [NAME] at src/components/patterns/[NAME].tsx.
This component composes the following UI primitives: [LIST].
Follow all Component Standards and Design Tokens.

## Audit Component
Read SKILL.md. Read the component at [PATH].
Check it against all rules in SKILL.md and report:
- Any violations of Component Standards
- Missing TypeScript types
- Inline styles that should be Tailwind
- Missing accessibility attributes
- Incorrect file naming

## Create Story
Read SKILL.md. Read the component at [PATH].
Create a Storybook story at the correct path following File Naming conventions.
Include stories for: default state, all variants, disabled state, with long text.

Then in your Claude session, you can say:

"Read PROMPTS.md and run the 'New UI Component' prompt for a component called Badge."