Claude Code ships with a general-purpose AI assistant. Skills let you specialize it. A skill is a markdown file that teaches Claude Code how to handle a specific type of task: deploying to Kubernetes, writing database migrations, reviewing pull requests, or following your team's coding conventions.
The difference between "write me a React component" and "write me a React component following our design system, using our custom hooks, with proper error boundaries and accessibility attributes" is a skill.
The official Claude Code docs now make one thing explicit: custom commands have been merged into skills. Existing files in .claude/commands/ still work, but skills are the recommended abstraction because they support richer metadata, supporting files, and automatic loading. If you are standardizing a team workflow today, build it as a skill first and treat legacy commands as a compatibility path.
What Skills Actually Are
A skill lives in a directory with a SKILL.md entrypoint. Claude can load it automatically when the description matches the current task, or you can invoke it directly with /skill-name.
.claude/
skills/
deploy/
SKILL.md # /deploy
review-pr/
SKILL.md # /review-pr
write-test/
SKILL.md # /write-test
Claude still supports .claude/commands/deploy.md, and the slash command will still work. But the modern version is .claude/skills/deploy/SKILL.md.
That sounds like a small naming change. It matters because skills can carry supporting files, frontmatter, invocation controls, and subagent hints. A thin command file can tell Claude what to do. A skill can tell Claude how your team expects the work to be done.
Writing Your First Skill
Here's a practical example: a skill that enforces your team's commit message conventions.
Create .claude/skills/commit/SKILL.md:
---
name: commit
description: Generate and validate conventional commits for this repo.
---
# Commit Workflow
## Steps
1. Run `git diff --staged` to see what's being committed
2. Analyze the changes and categorize: feat, fix, refactor, docs, test, chore
3. Write a commit message following our convention:
- Format: `type(scope): description`
- Scope is the package or module name
- Description is imperative mood, lowercase, no period
- Body explains WHY, not WHAT
4. If changes touch multiple scopes, create separate commits
5. Run `git commit -m "message"` with the generated message
## Rules
- Never use `--no-verify` to skip hooks
- Never amend published commits
- If tests fail in pre-commit, fix the issue first
## Examples
- `feat(billing): add stripe webhook handler`
- `fix(auth): handle expired refresh tokens`
- `refactor(api): extract rate limiter to shared package`
Now /commit gives Claude Code a structured workflow instead of a vague "commit my changes" instruction.
If you already have legacy command files, keep them working while you migrate, but do not keep investing in the old layout. The official docs are clear that skills are the forward path.
Where Skills Live Now
Claude Code currently discovers skills from four places:
- personal skills:
~/.claude/skills/<skill-name>/SKILL.md - project skills:
.claude/skills/<skill-name>/SKILL.md - nested project skills in monorepos
- plugin-provided skills
That gives you a clean split:
- personal skills for your own working style
- project skills for repo conventions
- plugin skills for reusable packaged workflows
For team adoption, commit project skills to the repo. That is the difference between “I have a nice prompt on my laptop” and “the team now has a repeatable workflow.”
Skill Design Patterns
The Checklist Pattern
Best for tasks with multiple verification steps.
# Pre-Deploy Checklist
Before deploying, verify each item:
- [ ] `pnpm typecheck` passes
- [ ] `pnpm test` passes
- [ ] No console.log statements in production code
- [ ] Environment variables documented in .env.example
- [ ] Database migrations are reversible
- [ ] API changes are backward compatible
If any check fails, stop and report the issue. Do not proceed with deployment.
The Decision Tree Pattern
Best for tasks where the approach depends on context.
# Bug Fix Workflow
1. Reproduce the bug (find or write a failing test)
2. Identify the root cause:
- If it's a type error → fix the type definition at the source
- If it's a race condition → add proper locking/sequencing
- If it's a missing validation → add schema validation at the boundary
- If it's a logic error → fix and add regression test
3. Verify the fix doesn't break existing tests
4. Write a test that would have caught this bug
The Template Pattern
Best for generating consistent output.
# New API Endpoint
Create a new API endpoint following our conventions:
## File Structure
- Route handler: `apps/api/src/routes/{resource}/{action}.ts`
- Schema: `apps/api/src/schemas/{resource}.ts`
- Test: `apps/api/src/routes/{resource}/__tests__/{action}.test.ts`
## Required Elements
- Zod schema for request validation
- Authentication middleware
- Rate limiting
- Structured error responses using errorResponse()
- Success responses using successResponse()
- OpenAPI documentation comments
Installing Community Skills
The Claude Code ecosystem has a growing library of community skills. Install them with:
npx add-skill username/repo-name -y
Popular skill collections:
coreyhaines31/marketingskills(29 marketing/SEO skills)hedging8563/lemondata-api-skill(LemonData API integration)
Installed skills appear in ~/.claude/commands/ and work across all projects.
Installed skill packs increasingly expose proper skills rather than only slash-command markdown. If you maintain your own repo, the pattern from OpenCode + LemonData applies here too: keep the skill close to the workflow, not hidden in ad hoc prompt files.
Project vs Global Skills
| Location | Scope | Use Case |
|---|---|---|
.claude/skills/ |
This project only | Project conventions, deploy workflows |
~/.claude/skills/ |
All projects | Personal preferences, reusable habits |
.claude/commands/ |
Legacy compatibility | Old slash-command files that still work |
Project skills should be committed to your repo so the whole team benefits. Global skills are for personal workflow preferences.
Advanced: Skills with Hooks
Skills can reference hooks (shell commands that run on specific events) for automated enforcement:
# Pre-Commit Check
Before any commit, the following hooks run automatically:
- `pre-commit`: runs typecheck + lint
- `post-commit`: updates changelog
If a hook fails, investigate the error output and fix the issue.
Do not use --no-verify to bypass hooks.
The hooks themselves are configured in .claude/settings.json:
{
"hooks": {
"pre-commit": "pnpm typecheck && pnpm lint-staged"
}
}
This is where skills become more than prompt snippets. A useful team setup often has three layers:
- a skill that tells Claude the workflow
- hooks that enforce the workflow
- repo docs that explain the workflow to humans
If one of those layers is missing, the system gets brittle. A skill without hooks becomes advisory. Hooks without skills become opaque. Docs without either become stale policy nobody follows.
Supporting Files Are the Real Upgrade
The most important reason to prefer skills over old command markdown is supporting files.
With a command file, everything has to live in one blob. With a skill directory, you can keep:
- templates
- examples
- shell helpers
- longer reference notes
- validator scripts
That lets you keep SKILL.md short and high-signal while still giving Claude structured material to pull in when it matters.
This is especially useful for:
- deployment workflows
- schema migration checklists
- multi-step code review processes
- product-specific integration playbooks
If your team is also using multiple models or multiple coding tools, pair this page with the coding model comparison and the Cursor / Cline / Windsurf setup guide. Good skills matter more when the underlying model or editor changes.
Tips for Effective Skills
Be specific about file paths and naming conventions. "Create a component" is vague. "Create a component in
src/components/ui/using PascalCase naming" is actionable.Include examples of correct output. Claude Code learns better from examples than from abstract rules.
Define what NOT to do. "Never use
anytype" is more enforceable than "use proper types."Keep skills focused. One skill per workflow. A 200-line skill that covers everything is less useful than five 40-line skills that each handle one task well.
Version your skills. As your conventions evolve, update the skills. Outdated skills are worse than no skills because they enforce old patterns.
Decide whether the skill should auto-load or only run manually. Many teams forget this and then wonder why Claude invokes a deployment skill in unrelated conversations.
Real-World Impact
Teams that adopt skills report consistent improvements:
- Code review cycles drop because conventions are enforced before review
- Onboarding time decreases because new developers get the same guidance as veterans
- AI-generated code quality improves because the AI has explicit context about project standards
The investment is small (30 minutes to write your first few skills) and the payoff compounds with every interaction.
The most useful mental model is this: a skill is not a shortcut for Claude. It is a versioned workflow artifact for your team.
If you only write one skill, make it the one that encodes the highest-cost repeated decision in your codebase.
Build with AI, guided by your own rules. LemonData gives you one API key for coding models across providers, so once your workflows are encoded as skills you can switch models without rebuilding the whole toolchain.