A crash course on Anthropic's Agent Skills
What are skills
If you use Claude Code, you've probably noticed you keep repeating yourself. Every PR review, you re-explain how you like feedback structured. Every commit message, you remind Claude of your preferred format. Skills exist to stop that loop.
A skill is a folder of instructions that Claude Code can discover and apply on its own. At its core sits a single file named SKILL.md, which holds a name and a description in its frontmatter, followed by the actual instructions Claude should follow. You write the knowledge down once, and Claude reuses it automatically whenever the task comes up again.
The description is the magic ingredient. When you send a request, Claude compares what you asked against the descriptions of every available skill and activates the ones that match. So a request like "summarize my changes for a pull request" will pull in a skill whose description mentions writing PR descriptions, without you having to name it.
Where skills live: personal vs. project
Where a skill lives decides who gets to use it. Personal skills go in ~/.claude/skills in your home directory (on Windows that's C:/Users/<your-user>/.claude/skills). These travel with you across every project, so they're the right home for things like your own commit-message style or how you like code explained.
Project skills go in a .claude/skills folder inside a repository and get committed to version control alongside the code. Anyone who clones the repo picks them up automatically, which makes them ideal for team standards: shared review checklists, brand guidelines, or workflows tied to that specific codebase.
When two skills share a name, a fixed priority order decides the winner: Enterprise (managed settings) beats Personal, which beats Project, which beats Plugins. That lets an organization enforce a mandatory standard while still leaving room for individual tweaks. The easiest way to dodge conflicts is to give skills distinct, specific names like frontend-review rather than just review.
Skills vs. CLAUDE.md, slash commands, subagents, hooks, and MCP
This is where most people get confused, so here's the quick mental model. Skills are automatic and task-specific: Claude loads them on demand when your request matches their description, so they don't clog up your context window the rest of the time.
A CLAUDE.md file, by contrast, loads into every single conversation. That makes it the right place for always-on rules, like "use TypeScript strict mode" or "never modify the database schema." If something should apply all the time, it belongs in CLAUDE.md; if it only matters sometimes, make it a skill.
Slash commands wait for you to type them explicitly, whereas skills trigger themselves when Claude recognizes the situation. Subagents run in their own isolated context and hand back a result, so they're for delegated work rather than adding knowledge to your current conversation. Hooks are event-driven, firing on things like a file save or before a tool call. And MCP servers are a different category altogether, providing external tools and integrations.
The point isn't to pick one. A healthy setup combines them: CLAUDE.md for standing rules, skills for on-demand expertise, hooks for automated side effects, subagents for isolated delegation, and MCP for outside tools. One subtlety worth flagging: subagents don't inherit your skills automatically. Built-in agents like Explorer, Plan, and Verify can't use skills at all, and a custom subagent only gets the skills you explicitly list in its frontmatter skills field.
When to use skills (and when not to)
The rule of thumb is the cleanest signal you'll get: if you find yourself explaining the same thing to Claude over and over, that repeated explanation is a skill waiting to be written. Good candidates include code-review standards, commit-message formats, brand guidelines, documentation templates, and debugging checklists for a particular framework.
Skills are the wrong tool when the knowledge should always be present (use CLAUDE.md), when you only ever invoke it by hand (a slash command is simpler), when you need isolated delegation (reach for a subagent), or when you want something to fire on an event like a save (that's a hook). Don't force everything into a skill just because skills are convenient.
The limitations worth knowing
Skills are powerful but not magic, and a few constraints are worth knowing up front. They share Claude's context window with your conversation, so an enormous SKILL.md eats into the space you have for actual work; the fix is progressive disclosure, which we'll cover below. They also rely on semantic matching, which means a vaguely worded description simply won't trigger when you expect it to.
Skills load at startup, so after creating, editing, or deleting one you have to restart Claude Code before the change takes effect. Subagents are the other big gotcha: they don't see your skills unless you explicitly list them, and the built-in agents can't use skills at all. Finally, name collisions get resolved by the priority hierarchy, so a personal skill can be silently shadowed by an enterprise skill with the same name.
Build a skill in five minutes
Enough theory. Here's a complete personal skill that teaches Claude to write consistent PR descriptions. Make a directory whose name matches the skill (mkdir -p ~/.claude/skills/pr-description), then drop a file called SKILL.md inside it. The file has two parts: YAML frontmatter between dashes, and the instructions underneath.
---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or summarizing changes for a pull request.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---
When writing a PR description, first run `git diff main...HEAD` to see all
changes on the branch, then write the description in this format:
## What
One sentence on what this PR does.
## Why
Brief context on why the change is needed.
## Changes
- Bullet points of the specific changes
- Group related changes together
- Call out any files deleted or renamedTwo fields are required: name (lowercase letters, numbers, and hyphens, up to 64 characters, matching the directory) and description (up to 1,024 characters, and the single most important field since it drives matching). Two more are optional but handy: allowed-tools restricts what Claude may do while the skill is active, which is perfect for read-only or security-sensitive work, and model pins the skill to a specific Claude model.
Once you've saved it, restart Claude Code (skills load at startup), ask what skills are available to confirm it registered, then make a change on a branch and say something like "write a PR description for my changes." Claude will note it's using the skill, run the diff, and produce the same format every time.
When a skill grows large, don't cram everything into one file. Use progressive disclosure: keep the essentials in SKILL.md (a good ceiling is 500 lines) and move the rest into supporting folders the standard suggests, namely references/ for extra docs, scripts/ for executable code, and assets/ for templates or images. In SKILL.md you link to those files with a note about when to read them, so Claude only pulls in the architecture guide when someone actually asks about system design. Scripts are especially efficient: tell Claude to run a script rather than read it, and only the output consumes tokens.
A checklist for shipping a good skill
Before you ship a skill, run through this quick checklist. Most problems trace back to one of these, and most fixes are a one-line change:
- Validate first. Run the agent skills verifier (uv is the quickest install) to catch structural problems before you debug anything else.
- Not triggering? The description is almost always the culprit. Add the trigger phrases you actually say, and test variations like "why is this slow?" or "make this faster."
- Not loading? Confirm SKILL.md sits inside a named directory (not at the skills root) and that the filename is exactly SKILL.md. Run claude --debug to see loading errors.
- Wrong skill firing? Two descriptions are too similar. Make them distinct and specific.
- Being shadowed? A higher-priority skill shares the name. Rename yours or talk to your admin.
- Runtime errors? Check dependencies are installed, give scripts execute permission with chmod +x, and use forward slashes in paths everywhere, even on Windows.
The takeaway from the whole course fits in one line: the best skills come from your own repeated frustrations. The next time you catch yourself explaining the same thing to Claude for the third time, stop and write it down as a SKILL.md. That single file will keep paying you back across every future conversation.