Claude Code Skills: Teach Your AI Your Patterns

Something most Claude Code users never discover: you can teach Claude your specific patterns, preferences, and workflows using simple markdown files. They're called skills. They're how you turn Claude from a general-purpose AI into your team's specific AI, one that knows your stack, follows your conventions, and builds things the way you actually want them built.

I use skills in every project I work on, and I teach every student to set them up. The difference between "Claude Code with skills" and "Claude Code without skills" is like the difference between a new hire on day 1 and that same person 6 months in. Skills are institutional knowledge for your AI.

What Skills Are

Skills are markdown files that live in your project's .claude/skills/ directory. Each file teaches Claude a specific workflow, pattern, or set of conventions. When Claude Code starts a session in your project, it discovers these files and uses them to guide its behavior.

A skill file is just a .md file with instructions written in plain English. No special syntax, no configuration format, no API. You write what you want Claude to know and do, and it follows those instructions throughout the session.

Here's a simple example, a skill file that teaches Claude how your team handles frontend components:

# Frontend Component Patterns

## File structure
- All components go in src/components/
- Each component gets its own directory: ComponentName/index.tsx
- Co-locate styles: ComponentName/styles.ts (using styled-components)
- Co-locate tests: ComponentName/ComponentName.test.tsx

## Conventions
- Use functional components with TypeScript
- Props interface named ComponentNameProps
- Export as named export, not default
- Always include a displayName
- Use React.memo for components that receive primitive props

## Styling
- Use our design tokens from src/styles/tokens.ts
- Never use inline styles
- Never use arbitrary values — always reference tokens
- Responsive breakpoints: use our useBreakpoint hook, not media queries

## Don'ts
- Don't use class components
- Don't use CSS modules (we migrated away from them)
- Don't create components in the pages directory
- Don't import from @mui — we removed that dependency

With this skill in place, every component Claude builds will follow your team's exact patterns. Without it, Claude guesses. And it guesses differently every time.

Skills vs. CLAUDE.md

If you already know about CLAUDE.md, you might wonder why not just put everything in there. There's an important distinction:

• CLAUDE.md is for project-level context: what the project is, how to run it, what the tech stack is, general rules that apply to everything. Think of it as the project README for Claude.
• Skills are for task-specific instructions: how to build a frontend component, how to write a database migration, how to handle code reviews. Think of them as specialized training manuals.

CLAUDE.md is always loaded. Skills are discovered and applied when relevant. This matters because Claude has a context window. Stuffing everything into CLAUDE.md wastes context on instructions that aren't relevant to the current task. Skills let you be detailed about specific workflows without bloating the base context.

In practice, I keep CLAUDE.md short: project description, tech stack, how to run the dev server, a few universal rules. Everything else goes into skills.

How Claude Discovers and Uses Skills

When you start Claude Code in a project that has a .claude/skills/ directory, Claude reads those files and incorporates them into its understanding. You don't need to reference skills in your prompts. Claude uses them automatically when they're relevant.

If you have a frontend skill and you ask Claude to "build a user profile component," it'll follow the patterns in your frontend skill without you mentioning it. Ask it to "write a database migration" and it'll use your migration skill. Claude matches the task to the relevant skill and applies the instructions.

You can also explicitly invoke a skill: "Build this component following our frontend skill." Useful when you want to make absolutely sure Claude pays attention to specific conventions.

Examples of Useful Skills

Here are the skills I've found most valuable across my own projects and my students' work:

Frontend design skill

Covers component structure, naming conventions, styling approach, accessibility requirements, and responsive patterns. This is the single most impactful skill because frontend code has the most variation in how it can be written. Without a frontend skill, Claude might use CSS modules in one component and Tailwind in another.

Database migration skill

Defines how your team handles schema changes: what migration tool you use, naming conventions for migration files, whether to include rollback scripts, how to handle data migrations vs. schema migrations. Example instruction: "Always create a migration file using npx drizzle-kit generate. Never modify the database schema directly."

Testing skill

Specifies your testing framework, what to test, file naming conventions, mocking patterns, and coverage expectations. "Use Vitest for unit tests. Test files go next to the code they test with a .test.ts suffix. Mock external services using msw. Every API endpoint needs at least 1 happy path and 1 error case test."

Code review skill

Teaches Claude how to review code the way your team does. "Check for: proper error handling, input validation, SQL injection risks, missing TypeScript types, console.log statements that should be removed, hardcoded values that should be environment variables." I use this when I ask Claude to review my own code or PRs.

API design skill

Defines your API conventions: REST vs. GraphQL, naming patterns, error response format, pagination approach, authentication headers. "All API routes return JSON with a { data, error, meta } shape. Use HTTP status codes correctly. 404 for not found, 422 for validation errors, 500 for server errors."

Writing style skill

Not for code. For content. If Claude writes copy, documentation, or emails for you, this skill defines your voice. "Write in first person. Short paragraphs, max 3 sentences. Use contractions. No corporate jargon. Prefer specific examples over abstract statements." I use this for my own content and it keeps Claude's writing consistent with my voice.

How to Write a Good Skill

After seeing hundreds of skill files from my students, here's what separates good ones from useless ones:

Be specific, not general

Bad: "Write clean, maintainable code."
Good: "Use early returns to avoid nesting. Max function length: 30 lines. Extract helper functions for any logic used more than twice."

General instructions are useless because Claude already tries to write clean code. Specific instructions are powerful because they encode your team's particular definition of clean.

Include examples

Show Claude what you want, don't just tell it. Include a code snippet of a well-written component, a properly structured API route, or a good test case. Examples are worth more than paragraphs of description.

Define do's AND don'ts

"Do" instructions tell Claude what to build toward. "Don't" instructions prevent common mistakes. Both are essential. "Don't use default exports" prevents a specific pattern. "Don't import from the old /lib directory, use /utils instead" prevents a migration mistake. Without don'ts, Claude will sometimes fall back to common patterns that your team has intentionally moved away from.

Keep each skill focused

One skill per workflow or domain. Don't create a single massive skill that covers everything. That defeats the purpose of having skills separate from CLAUDE.md. A focused skill is easier to maintain and more likely to be applied correctly.

Update skills when your patterns change

Skills are living documents. When your team adopts a new convention, update the skill. When you migrate to a new library, update the skill. Stale skills are worse than no skills because they'll actively guide Claude toward outdated patterns.

The Skills I Use in My Own Projects

For my ClaudeFluent.com website (a Next.js + Tailwind + Convex stack), I have these skills:

• frontend.md: component patterns, Tailwind conventions, page structure, our specific color tokens and spacing scale
• architect.md: how we handle data flow between Convex and the frontend, when to use server vs. client components, caching strategy
• content.md: writing style for guides and marketing copy, SEO patterns, how to structure guide content

3 files. That's it. Each one is about 50-80 lines of markdown. The total investment to write them was maybe an hour. The time they save me on every single Claude Code session is immeasurable, because Claude builds things right the first time instead of me correcting it over and over.

Getting Started With Skills

Here's what I tell every student:

1. Create the directory. mkdir -p .claude/skills in your project root.
2. Start with one skill. Pick the area where Claude most often builds things "wrong" (usually frontend patterns).
3. Write it from experience. Think about the last 5 times you corrected Claude's output. What did you keep fixing? Write those corrections into a skill.
4. Test it. Ask Claude to build something that should follow the skill and verify it does.
5. Iterate. When Claude still gets something wrong, add that correction to the skill.

Skills are how you stop repeating yourself. Every correction you make to Claude's output is a signal that you need a skill. Instead of saying "no, use Tailwind not inline styles" for the 10th time, write it once in a skill and never say it again.

The people who get the most out of Claude Code aren't the ones who write the best prompts. They're the ones who invest 30 minutes in skills and then never have to write those prompts at all. Skills are the single best investment you can make in your Claude Code workflow.

Want to keep going? Learn how to use Claude Code step by step, or read about what Claude Code is and the best practices that make the biggest difference.