Skills in Claude Code

📖 See also: Glossary: Claude Code Building Blocks for a full breakdown of all the pieces (skills, hooks, subagents, MCP, plugins, etc.)

How they work

A skill is a markdown file that teaches Claude how to do something once, and Claude applies that knowledge automatically whenever it's relevant. Instead of repeating your coding standards, PR review format, or commit message style every time, you write it once as a skill.

Claude reads your request, compares it to all available skill descriptions, and activates the ones that match. It only loads the name and description initially, so it doesn't fill up your context window. The full skill content loads on demand — your PR review checklist doesn't need to be in context when you're debugging.

Where to store them

Personal skills go in ~/.claude/skills/ — they follow you across all projects. Your preferences, your style, how you like things explained.

Project skills go in .claude/skills/ in the repo root — anyone who clones the repo gets them automatically. This is where team standards live, like brand guidelines, preferred fonts, and colors.

Skills vs other Claude Code features

CLAUDE.md loads into every conversation, always present. Good for global rules like "always use TypeScript strict mode."

Skills load on demand when they match your request. More efficient with context window.

Slash commands require you to type them manually. Skills are automatic — Claude applies them when it recognizes the situation.

Rule of thumb

If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written.

For design work

A project skill with your brand guidelines, token rules, and component conventions would mean anyone on your team cloning the repo gets Claude automatically following those standards — no setup needed.

Creating a skill from scratch

A skill is a directory containing a SKILL.md file. The file has two parts separated by frontmatter dashes: metadata (name and description) and instructions.

Example — a PR description skill:

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR or when the user asks to summarize changes.
---

When writing a PR description:
1. Run `git diff main...HEAD` to see all changes
2. Write a description with What, Why, and Changes sections

The name identifies the skill. The description tells Claude when to use it — this is the matching criteria. Everything after the second set of dashes is the instructions Claude follows when activated.

How skill matching works

When Claude Code starts, it scans for skills but only loads the name and description — not the full content. When you send a request, Claude compares your message against all skill descriptions using semantic matching. Once a match is found, Claude asks you to confirm loading the skill before reading the full instructions.

For example, "explain what this function does" would match a skill described as "explain code with visual diagrams" because the intent overlaps.

Skill priority hierarchy

If two skills share the same name, there's a clear priority order:

1. Enterprise — managed settings, highest priority
2. Personal — ~/.claude/skills/
3. Project — .claude/skills/ inside the repo
4. Plugins — lowest priority

This lets organizations enforce standards through enterprise skills while still allowing individual customization. To avoid conflicts, use descriptive names like "frontend-review" instead of just "review."

Updating and removing skills

Edit the SKILL.md to update a skill. Delete the directory to remove one. Always restart Claude Code after changes for them to take effect.

Configuration — metadata fields

Beyond name and description (both required), the SKILL.md frontmatter supports optional fields:

• allowed-tools — restricts what Claude can do when the skill is active. Example: allowed-tools: Read, Grep, Glob, Bash means Claude can look at files but not edit or write anything. Useful for security-sensitive or read-only workflows. If omitted, Claude uses its normal permissions.
• model — specifies which Claude model to use for the skill.

A good description answers two questions: what does this skill do, and when should Claude use it? If the skill isn't triggering, add more keywords that match how you actually phrase your requests.

Progressive disclosure — why it matters

When Claude activates a skill, it loads the SKILL.md content into the context window. The context window is shared between the skill content, your conversation, and everything else Claude is working with. It has a limited size, so everything you load has a cost.

If you put everything in one 2,000-line SKILL.md — your design token definitions, component guidelines, accessibility rules, naming conventions, example code — all of that gets loaded every single time the skill activates. Even if you only asked "what's the primary color?" Claude would load the entire file including the accessibility rules and component guidelines you don't need for that question.

Progressive disclosure solves this by splitting the content. Your SKILL.md keeps the essential instructions and acts as a router — it tells Claude where to find more detailed information and when to load it. The supporting files only get read when they're actually relevant.

Example structure for a design system skill:

.claude/skills/design-system/
├── SKILL.md              (core rules, ~100 lines)
├── references/
│   ├── color-tokens.md   (full palette + usage rules)
│   ├── typography.md     (type scale + font specs)
│   └── spacing.md        (spacing scale + layout rules)
├── scripts/
│   └── validate-tokens.sh
└── assets/
    └── component-template.md

In your SKILL.md you write something like: "When asked about colors or palette, read references/color-tokens.md. When asked about typography or fonts, read references/typography.md." Now if someone asks about typography, Claude only loads that file — not the colors, not the spacing, not the component template. The context window stays clean.

The 500-line rule: Keep SKILL.md under 500 lines. If you're exceeding that, it's a sign content should be split into reference files.

Scripts tip: Tell Claude to run scripts, not read them. The script executes and only the output consumes tokens, not the source code. Keeps context efficient.

Skills vs all other Claude Code features

Claude Code has five customization options. Each solves a different problem:

CLAUDE.md — Loads into every conversation, always present. Use for project-wide standards that always apply: "never modify the database schema," framework preferences, coding style. Cost: always uses context window space.

Skills — Load on demand when Claude matches your request. Use for task-specific expertise that's only relevant sometimes: PR review checklist, brand guidelines, detailed procedures. Cost: only uses context when activated.

Subagents — Specialized agents that Claude creates within your session to delegate specific tasks. Each subagent runs in its own isolated context with its own system prompt and tool permissions. Claude Code comes with built-in subagents like "Explore" (read-only codebase search) and "Plan" (research for planning). You can also create custom ones. Think of them as temporary specialists — Claude hires them, they do their job, report back, and disappear.

Agent Teams — A level above subagents. Instead of working within a single session, agent teams coordinate across multiple separate sessions — like having several terminals open, each running its own Claude Code instance, all communicating with each other to work on different parts of a task simultaneously.

Hooks — Event-driven, fire automatically on specific actions. Run a linter every time Claude saves a file, validate input before tool calls, block reading .env files. Use for automated operations that should happen regardless of what you're asking.

MCP servers — Provide external tools and integrations (Figma, Notion, Playwright). A different category entirely — they give Claude new capabilities rather than new knowledge.

Key distinction: Skills are request-driven (activate based on what you ask). Hooks are event-driven (fire on system events). CLAUDE.md is always-on. Subagents are isolated workers within your session. Agent Teams are multiple sessions working together. MCP is external tool access.

A typical setup combines them: CLAUDE.md for global rules, skills for task-specific expertise, hooks for automated validation, subagents for delegated work, MCP for external tool access. Don't force everything into one — use each for what it's best at.

Sharing skills

Three ways to distribute skills:

1. Git repository — Simplest method. Put skills in .claude/skills/ and commit. Anyone who clones the repo gets them automatically, no extra installation. When you push updates, everyone gets them on the next pull. Best for team coding standards, project-specific workflows, and skills that reference your codebase structure.

2. Plugins — For skills that aren't project-specific and can be useful beyond your team. You create a plugin project with a skills directory, distribute it to a marketplace, and other users can install it. Think of it as publishing a reusable package.

3. Enterprise managed settings — Admins deploy skills organization-wide. Enterprise skills have the highest priority — they override personal, project, and plugin skills with the same name. Use for mandatory standards, security requirements, compliance workflows. The keyword is "must."

Important gotcha: skills and subagents

Subagents don't automatically see your skills. When Claude delegates a task to a subagent, it starts with a fresh, clean context. Built-in agents (Explorer, Plan, Verify) can't access skills at all. Only custom subagents you define in .claude/agents/ can use them, and only when you explicitly list them in the agent's frontmatter skills field. Skills load when the subagent starts (all at once), not on demand — so only list skills that are always relevant to that subagent's purpose.

Troubleshooting skills

When a skill doesn't work, it's usually one of these:

Not triggering? The cause is almost always the description. Claude uses semantic matching — your request needs to overlap with the description's meaning. Fix: add trigger phrases that match how you actually phrase requests. Test variations like "help me profile this," "why is this slow?", "make this faster." If any fail, add those keywords to your description.

Not loading? Check the structure. SKILL.md must be inside a named directory, not directly in the skills root. File name must be exactly SKILL.md — all caps SKILL, lowercase md. Run claude --debug to see loading errors and look for messages mentioning your skill name.

Wrong skill gets used? Your descriptions are too similar. Make them more distinct and specific. Being specific doesn't just help Claude decide when to use your skill — it also prevents conflicts with similar-sounding skills.

Being shadowed? A higher-priority skill (enterprise > personal > project > plugin) might have the same name. Rename yours to something more specific, or talk to your admin about the enterprise skill.

Plugin skills missing? Clear cache, restart Claude Code, reinstall. If they still don't appear, the plugin structure might be wrong.

Runtime failure? Check that dependencies are installed (add dependency info to your description so Claude knows what's needed), scripts have execute permission (chmod +x), and use forward slashes in paths everywhere — even on Windows.