Claude Code skills, explained

A skill file in Claude Code is a markdown document that teaches the agent how to handle a specific task. You write it once, and Claude Code loads it whenever that task comes up. Think of it like a recipe card: the agent doesn't memorize it, but it knows where to find it when you're cooking that dish.

What belongs in a skill file

Task-specific workflows. Things that are useful sometimes but not always. Here are examples that make sense as skills:

• •How to write and run database migrations for your project
• •Your team's process for debugging production issues
• •Steps for adding a new API endpoint (including tests, docs, types)
• •How to set up a new React component with your design system

The pattern: if you wouldn't need this instruction in every single session, it's a skill, not an agents.md entry.

What doesn't belong in a skill file

Anything that applies to every interaction with your codebase. Your commit message format. Your coding style preferences. Your testing framework. These go in agents.md or CLAUDE.md because Claude Code needs them every time.

If you're not sure which one a particular instruction belongs in, describe it and ClaudeOrNot will tell you.

How to structure a skill file

There's no required format, but the ones that work well tend to follow a pattern:

# Database Migrations

## When to load this skill
When the user asks to create, modify, or run database migrations.

## Steps
1. Check the current migration files in `db/migrations/`
2. Generate a new migration with `npx drizzle-kit generate`
3. Review the generated SQL before applying
4. Run `npx drizzle-kit migrate` to apply
5. Update the schema types with `npx drizzle-kit introspect`

## Pitfalls
- Never run migrations on production without a backup
- Always check for data loss in the generated SQL
- The naming convention is `YYYYMMDD_description.sql`

Short, specific, with clear steps and pitfalls. That's it. You don't need prose paragraphs explaining why migrations matter. Claude Code already knows what migrations are. It needs to know how your project handles them.

Where to put skill files

In your project, typically under a .claude/skills/ directory or wherever your Claude Code configuration lives. The exact location depends on your setup. Claude Code looks for them based on the instructions in your agents.md or project config.

Common skill file mistakes

• •Writing too much. A 200-line skill file is almost always too long. Claude Code can follow instructions, but shorter is better. If your skill is over 50 lines, see what you can cut.
• •Being too generic. "Write good code" isn't a skill. "When adding a new API route, create the handler in app/api/[route]/route.ts, add Zod validation, write integration tests in tests/api/" is a skill.
• •Not updating them. Your project changes. Your skill files should too. Review them every few weeks.