Introduction to Agent Skills |

What Are Skills?

Tue, 13 Oct 2026 00:00:00 +0000

Note

TL;DR

Skills are folders of instructions that Claude Code can discover and use to handle tasks more accurately. Each skill lives in a SKILL.md file with a name and description in its frontmatter
Claude uses the description to match skills to requests. When you ask Claude to do something, it compares your request against available skill descriptions and activates the ones that match
Personal skills go in ~/.claude/skills and follow you across all projects. Project skills go in .claude/skills inside a repository and are shared with anyone who clones it
Skills load on demand — unlike CLAUDE.md (which loads into every conversation) or slash commands (which require explicit invocation), skills activate automatically when Claude recognizes the situation
If you find yourself explaining the same thing to Claude repeatedly, that’s a skill waiting to be written

A skill is a markdown file that teaches Claude how to do something once. Claude then applies that knowledge automatically whenever it’s relevant.

What Skills Are

Skills are folders of instructions and resources that Claude Code can discover and use to handle tasks more accurately.

Each skill lives in a SKILL.md file with a name and description in its frontmatter.

Example:
```
---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---
```
- The description is how Claude decides whether to use the skill.
  - When you ask Claude to review a PR, it matches your request against available skill descriptions and finds the relevant one.
  - Claude reads your request, compares it to all available skill descriptions, and activates the ones that match.
Below the frontmatter, you write the actual instructions or whatever Claude needs to know for that task.

Where Skills Live

You can store skills in different places depending on who needs them:

Personal skills go in ~/.claude/skills (your home directory).
- These follow you across all your projects — your commit message style, your documentation format, how you like code explained.
Project skills go in .claude/skills inside the root directory of your repository.
- Anyone who clones the repo gets these skills automatically. This is where team standards live, like your company’s brand guidelines, preferred fonts, and colors for web design.
- Project skills get committed to version control alongside your code, so the whole team shares them.

Skills vs. CLAUDE.md vs. Slash Commands

CLAUDE.md files load into every conversation. For example, if you want Claude to always use TypeScript’s strict mode, that goes in CLAUDE.md.
Skills are automatic and task-specific.
- SKills load on demand when they match your request.
  
  When Claude matches a skill to your request, you’ll see it load in the terminal:
- Claude only loads the name and description initially, so they don’t fill up your entire context window.
  - E.g., Your PR review checklist doesn’t need to be in context when you’re debugging — it loads when you actually ask for a review.
Slash commands require you to explicitly type them. Skills don’t. Claude applies them when it recognizes the situation.

When to Use Skills

The rule of thumb: If you find yourself explaining the same thing to Claude repeatedly, that’s a skill waiting to be written.

Skills work best for specialized knowledge that applies to specific tasks:

Code review standards your team follows
Commit message formats you prefer
Brand guidelines for your organization
Documentation templates for specific types of docs
Debugging checklists for particular frameworks

Creating Your First Skill

Tue, 13 Oct 2026 00:00:00 +0000

Note

TL;DR

A skill is a directory containing a SKILL.md file with metadata (name, description) in frontmatter and instructions below
Claude loads only skill names and descriptions at startup, then matches incoming requests against those descriptions using semantic matching
You get a confirmation prompt before Claude loads the full skill content into context
Priority for name conflicts: Enterprise → Personal → Project → Plugins
To update a skill, edit its SKILL.md. To remove one, delete its directory. Always restart Claude Code for changes to take effect

Creating a Skill

The name identifies your 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 the skill is activated.

Example:

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

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

Testing Your Skill

Claude Code loads skills at startup, so restart your session after creating one. You can verify it’s available by checking the available skills list.

How Skill Matching Works

When Claude Code starts, it scans four locations for skills but only loads the name and description — not the full content.

Enterprise: managed-settings.json
Personal: ˜/.claude/skills
Project: project/.claude/skills
Plugins: project/.claude-plugin/plugin.json

When you send a request, Claude compares your message against the descriptions of all available skills.

Example: “Explain what this function does” would match a skill described as “explain code with visual diagrams” because the intent overlaps.

Once a match is found, Claude asks you to confirm loading the skill. This confirmation step keeps you aware of what context Claude is pulling in. After you confirm, Claude reads the complete SKILL.md file and follows its instructions.

Skill Priority

The priority order (from high to low):

Enterprise — managed settings, highest priority
Personal — your home directory (~/.claude/skills)
Project — the .claude/skills directory inside a repository
Plugins — installed plugins, lowest priority

If your company has an enterprise “code-review” skill and you create a personal “code-review” skill with the same name, the enterprise version takes precedence.

To avoid conflicts, use descriptive names.

Example: Instead of just “review,” use something like “frontend-review” or “backend-review.”

Updating and Removing Skills

Update: Edit its SKILL.md file

Remove: Delete its directory

Restart Claude Code after any changes for them to take effect.

Configuration and Multi-File Skills

Tue, 13 Oct 2026 00:00:00 +0000

Note

TL;DR

name and description are required — allowed-tools and model are optional but powerful additions
A good description answers two questions: What does the skill do? When should Claude use it?
allowed-tools pre-approves the listed tools while the skill is active, so Claude can use them without asking, and it doesn’t limit Claude to those tools
Progressive disclosure: keep SKILL.md under 500 lines and link to supporting files (references, scripts, assets) that Claude reads only when needed
Tell Claude to execute scripts without loading their contents into context — only the output consumes tokens, keeping context efficient

Skill Metadata Fields

The defines the core fields in the SKILL.md frontmatter, and Claude Code adds a few of its own (such as model).

Field	Required?	What it does	Rules and tips
`name`	Yes	Identifies the skill	Lowercase letters, numbers and hyphens only, up to 64 characters. Should match the skill’s folder name.
`description`	Yes	Tells Claude when to use the skill. The lesson calls this the most important field, because Claude matches requests against it.	Up to 1,024 characters. Say what the skill does and when to use it, and include the words people actually use when asking for that task.
`allowed-tools`	No	Lets Claude use the listed tools without asking permission while the skill is active	The approval lasts for the turn that invoked the skill and ends with your next message. It doesn’t stop Claude from using other tools. Plain `Bash` approves all shell commands, so narrow it, e.g. `Bash(git status *)`. If you leave the field out, nothing is pre-approved.
`model`	No	Picks which Claude model runs the skill	Use it when a skill needs a specific model.
`disallowed-tools`	No (a separate Claude Code field the lesson also mentions)	Takes the listed tools away while the skill is active	This is the opposite of `allowed-tools`: it actually removes tools.

Writing Effective Descriptions

Be explicit with your instructions.

A good description answers two questions:

What does the skill do?
When should Claude use it?

Tip

If your skill isn’t triggering when you expect it to, try adding more keywords that match how you actually phrase your requests. The description is what Claude uses to decide whether a skill is relevant, so the language matters.

Pre-Approving Tools with `allowed-tools`

The allowed-tools field pre-approves the tools you list, so Claude can use them without a permission prompt for the rest of the turn that invoked the skill. The grant clears when you send your next message.

Example

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

The allowed-tools field is set to Read, Grep, Glob, Bash. When this skill is active, Claude can use those four tools without asking permission. It doesn’t lose access to anything else: if the skill’s instructions lead Claude to edit or write a file, that goes through your normal permission settings like any other tool call.

Caution

Listing Bash on its own pre-approves shell commands in general, so reserve that for skills you trust, or narrow it to a pattern such as Bash(git status *).

To take tools away while a skill is active, use a separate Claude Code frontmatter field, disallowed-tools, which removes the tools you list from the set Claude can use.s

Progressive Disclosure

Why progressive disclosure is necessary

Skills share Claude’s context window with your conversation. When Claude activates a skill, it loads the contents of that SKILL.md into context. But sometimes you need references, examples, or utility scripts that the skill depends on.

Cramming everything into one 2,000-line file has two problems: it takes up a lot of context window space, and it’s not fun to maintain.

Progressive disclosure: Keep essential instructions in SKILL.md and put detailed reference material in separate files that Claude reads only when needed.

The open standard suggests organizing your skill directory with:

Location	Contains	Notes
`SKILL.md`	Essential instructions, plus links to the supporting files with clear guidance on when to load each one	A good rule of thumb: keep SKILL.md under 500 lines.
`scripts/`	Executable code
`references/`	Additional documentation
`assets/`	Images, templates, or other data files

Example:

my-skill/
├── SKILL.md # short (<500 lines): what to do and when to read the other files.
├── references/
│ └── architecture-guide.md
├── scripts/
│ └── check.py
└── assets/
 └── report-template.md

Using Scripts Efficiently

Key instruction to include in your SKILL.md: Tell Claude to run the script, not read it.

Scripts in your skill directory can run without loading their contents into context. The script executes and only the output consumes tokens.

Python analogy

In Python you call pd.read_csv(path) without pasting the pandas source into your notebook. You care about the result, not the 10,000 lines that produced it. A skill script works the same way for Claude.

This is particularly useful for:

Environment validation
Data transformations that need to be consistent
Operations that are more reliable as tested code than generated code

Example

In a CV evaluation skill, SKILL.md could say:

Run scripts/eval_metrics.py --pred preds.json --gt labels.json and summarize the mAP and per-class results.

Claude executes your tested metric code and sees only a short results table, not the implementation. You get the same mAP calculation every run, instead of Claude improvising one.

Skills vs. Other Claude Code Features

Tue, 13 Oct 2026 00:00:00 +0000

Note

TL;DR

CLAUDE.md loads into every conversation and is best for always-on project standards. Skills load on demand and are best for task-specific expertise
Subagents run in isolated execution contexts — use them for delegated work. Skills add knowledge to your current conversation
Hooks are event-driven (fire on file saves, tool calls). Skills are request-driven (activate based on what you’re asking)
MCP servers provide external tools and integrations — a different category entirely from skills
Each feature handles its own specialty — combine them rather than forcing everything into one approach

CLAUDE.md vs Skills

Use CLAUDE.md for:

Project-wide standards that always apply
Constraints like “never modify the database schema”
Framework preferences and coding style

Use Skills for:

Task-specific expertise
Knowledge that’s only relevant sometimes
Detailed procedures that would clutter every conversation

Tip

Skills can also be called explicitly using /your-skill.

Skills vs Subagents

Subagents run in a separate context. They receive a task, work on it independently, and return results. They’re isolated from the main conversation.

Skills add knowledge to your current conversation. When a skill activates, its instructions join the existing context.

Use Subagents when:

You want to delegate a task to a separate execution context
You need different tool access than the main conversation
You want isolation between delegated work and your main context

Use Skills when:

You want to enhance Claude’s knowledge for the current task
The expertise applies throughout a conversation

Skills vs Hooks

Hooks are event-driven and fire on events. A hook might run a linter every time Claude saves a file, or validate input before certain tool calls.

Skills are request-driven. They activate based on what you’re asking.

Use Hooks for:

Operations that should run on every file save
Validation before specific tool calls
Automated side effects of Claude’s actions

Use Skills for:

Knowledge that informs how Claude handles requests
Guidelines that affect Claude’s reasoning

Putting It All Together

A typical setup might include:

CLAUDE.md — always-on project standards
Skills — task-specific expertise that loads on demand
Hooks — automated operations triggered by events
Subagents — isolated execution contexts for delegated work
MCP servers — external tools and integrations

Each handles its own specialty. Don’t force everything into skills when another option fits better — and you can use multiple at a time.

Use skills when you have knowledge that Claude should apply automatically when the topic is relevant, and combine them with other features for comprehensive customization.

Sharing Skills

Tue, 13 Oct 2026 00:00:00 +0000

Note

TL;DR

Project skills in .claude/skills are shared automatically through Git — anyone who clones the repo gets them
Plugins let you distribute skills across repositories via marketplaces for broader community use
Enterprise managed settings deploy skills organization-wide with the highest priority, ideal for mandatory standards and compliance
Subagents don’t automatically see your skills — you must explicitly list skills in a custom agent’s frontmatter skills field
Built-in agents (Explorer, Plan, Verify) can’t access skills at all — only custom subagents defined in .claude/agents can

Project Skills: Committing Skills to Your Repository

The simplest sharing method is committing skills directly to your repository.

Place them in .claude/skills, and anyone who clones the repo gets those skills automatically — no extra installation needed.
When you push updates, everyone gets them on the next pull.

This approach works well for:

Team coding standards
Project-specific workflows
Skills that reference your codebase structure

The .claude directory contains your agents, hooks, skills, and settings — all version-controlled and shared with the team through normal Git workflows.

Distributing Skills Through Plugins

Plugins are a way to extend Claude Code with custom functionality designed to be shared across teams and projects.

In your plugin project, create a skills directory that follows a similar file structure to the .claude directory — each skill gets its own folder with a SKILL.md file inside. After you distribute your plugin to a marketplace, other users can discover and install it into Claude Code for themselves.

This approach is best when your skills aren’t too project-specific and can be useful to community members.

Enterprise Deployment Through Managed Settings

Administrators can deploy skills organization-wide through managed settings (managed-setting.json).

Enterprise skills take the highest priority — they override personal, project, and plugin skills with the same name.

This is the right choice for mandatory standards, security requirements, compliance workflows, and coding practices that must be consistent across the organization.

Skills and Subagents

Subagents don’t automatically inherit your skills. When you delegate a task to a subagent, it starts with a fresh, clean context.

Important distinctions to understand:

Built-in agents (like Explorer, Plan, and Verify) can’t access skills at all
Custom subagents you define can use skills, but only when you explicitly list them
Skills are loaded when the subagent starts, not on demand like in the main conversation

How to give a subagent skills:

Make sure the skills exist in your .claude/skills directory
Create a new subagent or add the skills field to the frontmatter of an existing agent’s markdown file.

Tip

You can use the /agents command in Claude Code to create a subagent interactively

Example

Here’s what the frontmatter looks like of a subagent looks like:

---
name: frontend-security-accessibility-reviewer
description: "Use this agent when you need to review frontend code for accessibility..."
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
model: sonnet
color: blue
skills: accessibility-audit, performance-check
---

When you delegate to this subagent, it has both skills loaded and applies them to every review.

This pattern works really well when:

You want isolated task delegation with specific expertise
Different subagents need different skills (frontend reviewer vs. backend reviewer)
You want to enforce standards in delegated work without relying on prompts

Troubleshooting Skills

Tue, 13 Oct 2026 00:00:00 +0000

Note

TL;DR

Start with the skills validator tool — it catches structural problems before you spend time debugging other things
If a skill doesn’t trigger, the cause is almost always the description — add trigger phrases that match how you actually phrase requests
If a skill doesn’t load, check that SKILL.md is inside a named directory (not at the skills root) and the file name is exactly SKILL.md
If the wrong skill gets used, your descriptions are too similar — make them more distinct
For runtime errors, check dependencies, file permissions (chmod +x), and path separators (use forward slashes everywhere)

Use the Skills Validator

The first thing to try is the agent skills verifier command.

Installation steps vary by operating system, but using uv is the easiest way to get it set up quickly.

Once installed, either navigate to your skill directory or run the command from anywhere. The validator will catch structural problems before you spend time debugging other things.

The Problems

When skills don’t work, the problem usually falls into one of a few categories: the skill

doesn’t trigger,
doesn’t load,
has conflicts, or
fails at runtime.

Quick troubleshooting checklist:

Not triggering? -> Improve your description and add trigger phrases.
Not loading? -> Check your path, file name, and YAML syntax.
Wrong skill used? -> Make descriptions more distinct from each other.
Being shadowed? -> Check the priority hierarchy and rename if needed.
Plugin skills missing? -> Clear cache and reinstall.
Runtime failure? -> Check dependencies, permissions, and paths.

Skill doesn’t trigger

Problem: Your skill exists and passes validation, but Claude isn’t using it when you expect.

Root cause: The description. Claude uses semantic matching, so your request needs to overlap with the description’s meaning. If there’s not enough overlap, no match.

Fix:

Check your description against how you’re actually phrasing requests
Add trigger phrases users would actually say
Test with variations like “help me profile this,” “why is this slow?”, “make this faster”
If any variation fails to trigger, add those keywords to your description

Skill doesn’t load

Problem: The skill doesn’t appear when you ask Claude “what skills are available”.

Fix:

Check these structural requirements:
- The SKILL.md file must be inside a named directory, not at the skills root
- The file name must be exactly SKILL.md — all caps on “SKILL”, lowercase “md”
Run claude --debug to see loading errors. Look for messages mentioning your skill name.

Wrong skill gets used

Problem: Claude uses the wrong skill or seems confused between skills

Root cause: Your descriptions are probably too similar.

Fix: Make them distinct.

Being as specific as possible doesn’t just help Claude decide when to use your skill — it also prevents conflicts with other similar-sounding skills.

Skill priority conflicts

Problem: Your personal skill is being ignored,

Root cause: An enterprise or higher-priority skill might have the same name.

Fix:

Rename your skill to something more distinct (this is usually the easier path)
Talk to your admin about the enterprise skill

Plugin skills not appearing

Problem: Installed a plugin but can’t see its skills.

Fix:

Clear the cache, restart Claude Code, and reinstall.
If skills still don’t appear after that, the plugin structure might be wrong. -> Use the validator tool.

Runtime errors

Problem: The skill loads but fails during execution.

Root Cause	Fix
Missing dependencies	If your skill uses external packages, they must be installed. Add dependency info to your skill description so Claude knows what’s needed.
Permission issues	Scripts need execute permission. Run `chmod +x` on any scripts your skill references.
Path separators	Use forward slashes everywhere, even on Windows.

Introduction to Agent Skills |

What Are Skills?

TL;DR

What Skills Are

Where Skills Live

Skills vs. CLAUDE.md vs. Slash Commands

When to Use Skills

Creating Your First Skill

TL;DR

Creating a Skill

Testing Your Skill

How Skill Matching Works

Skill Priority

Updating and Removing Skills

Configuration and Multi-File Skills

TL;DR

Skill Metadata Fields

Writing Effective Descriptions

Pre-Approving Tools with allowed-tools

Progressive Disclosure

Using Scripts Efficiently

Skills vs. Other Claude Code Features

TL;DR

CLAUDE.md vs Skills

Skills vs Subagents

Skills vs Hooks

Putting It All Together

Sharing Skills

TL;DR

Project Skills: Committing Skills to Your Repository

Distributing Skills Through Plugins

Enterprise Deployment Through Managed Settings

Skills and Subagents

Troubleshooting Skills

TL;DR

Use the Skills Validator

The Problems

Skill doesn’t trigger

Skill doesn’t load

Wrong skill gets used

Skill priority conflicts

Plugin skills not appearing

Runtime errors

Pre-Approving Tools with `allowed-tools`