Agent Skills

Agent Skills

Create, manage, and share Skills in Claude Code to extend Claude's capabilities.

This guide shows how to create, use, and manage Agent Skills in Claude Code. For background on how Skills work across Claude products, see What are Skills?.

A Skill is a markdown file that teaches Claude how to perform a specific task. Review PRs using your team's standards, generate commit messages in your preferred format, or query your company's database schema. Ask Claude for something that matches the Skill's purpose, and Claude automatically applies it.

Create Your First Skill

This example creates a personal Skill that teaches Claude to explain code using visual diagrams and analogies. Unlike Claude's default explanations, this Skill ensures every explanation includes ASCII diagrams and real-world analogies.

```
What Skills are available?
```

Claude will list all currently loaded Skills. You may have none, or you may have plugins or organization Skills.

```bash  theme={null}
mkdir -p ~/.claude/skills/explaining-code
```

The `description` is particularly important because Claude uses it to decide when to apply the Skill.

Create `~/.claude/skills/explaining-code/SKILL.md`:

```yaml  theme={null}
---
name: explaining-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.
```

```
What Skills are available?
```

You should see `explaining-code` listed with its description.

```
How does this code work?
```

Claude should ask to use the `explaining-code` Skill, then include analogies and ASCII diagrams in the explanation. If the Skill doesn't trigger, try rephrasing to include more keywords from the description like "explain how this works".

The rest of this guide covers how Skills work, configuration options, and troubleshooting.

How Skills Work

Skills are model-invoked: Claude decides which Skills to use based on your request. You don't need to explicitly invoke a Skill. Claude automatically applies relevant Skills when your request matches their description.

When you send a request, Claude follows these steps to find and use relevant Skills:

Where Skills Live

Where you store a Skill determines who can use it:

When two Skills have the same name, higher rows take precedence: managed overrides personal, personal overrides project, project overrides plugin.

When to Use Skills vs Other Options

Claude Code provides several ways to customize behavior. Key difference: Skills are triggered automatically by Claude based on your request, while slash commands require you to explicitly type /command.

Skills vs subagents: Skills add knowledge to the current conversation. Subagents run in a separate context with their own tools. Use Skills for instructions and standards, subagents when you need isolation or different tool access.

Skills vs MCP: Skills tell Claude how to use tools. MCP provides tools. For example, an MCP server connects Claude to your database, while a Skill teaches Claude your data models and query patterns.

Configure Skills

This section covers Skill file structure, supporting files, tool restrictions, and deployment options.

Write SKILL.md

The SKILL.md file is the only required file for a Skill. It consists of two parts: YAML metadata at the top (the section between --- markers) and markdown instructions that tell Claude how to use the Skill:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

Available Metadata Fields

The following fields are available in YAML frontmatter:

For complete writing guidelines including validation rules, see the best practices guide.

Update or Delete Skills

To update a Skill, edit the SKILL.md file directly. To remove a Skill, delete its directory. Changes take effect immediately.

Add Supporting Files with Progressive Disclosure

Skills share Claude's context window with conversation history, other Skills, and your requests. To keep context focused, use progressive disclosure: put essential information in SKILL.md and detailed reference materials in separate files that Claude reads only when needed.

This approach lets you bundle comprehensive documentation, examples, and scripts without consuming context upfront. Claude loads additional files only when the task requires them.

For optimal performance, keep SKILL.md under 500 lines. If your content exceeds this, split detailed reference material into separate files.

Example: Multi-File Skill Structure

Claude discovers supporting files through links in SKILL.md. The following example shows a Skill with detailed documentation in separate files and utility scripts that Claude can execute without reading:

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

The SKILL.md file references these supporting files so Claude knows they exist:

## Overview

[Essential instructions here]

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

## Utility scripts

To validate input files, run the helper script. It checks for required fields and returns any validation errors:
```bash
python scripts/helper.py input.txt
```

Keep references one level deep. Link directly from SKILL.md to reference files. Deeply nested references (file A links to file B which links to file C) may cause Claude to read files partially.

Bundle utility scripts for 0-context execution. Scripts in the Skill directory can be executed without loading their contents into context. Claude executes the script and only the output consumes tokens. This is useful for:

• Complex validation logic too verbose to explain in prose
• Data processing more reliable with tested code than generated code
• Operations that benefit from consistency across uses

In SKILL.md, instruct Claude to execute, not read, the script:

Run the validation script to check the form:
python scripts/validate_form.py input.pdf

For complete guidelines on structuring Skills, see the best practices guide.

Restrict Tool Access with allowed-tools

Use the allowed-tools frontmatter field to restrict which tools Claude can use when the Skill is activated. You can specify tools as a comma-separated string or YAML list:

---
name: reading-files-safely
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

Or use YAML-style list for better readability:

---
name: reading-files-safely
description: Read files without making changes. Use when you need read-only file access.
allowed-tools:
  - Read
  - Grep
  - Glob
---

When this Skill is activated, Claude can only use the specified tools (Read, Grep, Glob) without asking permission. This is useful for:

• Read-only Skills that should not modify files
• Limited scope Skills: for example data analysis only, no file writing
• Security-sensitive workflows where you want to restrict capabilities

Omitting allowed-tools means the Skill does not restrict tools. Claude uses the standard permission model and may ask to approve tool usage.

Run Skills in a Forked Context

Use context: fork to run a Skill in an isolated sub-agent context with its own conversation history. This is useful for Skills that perform complex multi-step tasks without cluttering the main conversation:

---
name: code-analysis
description: Analyze code quality and generate detailed reports
context: fork
---

Define Hooks for Skills

Skills can define hooks that execute during the Skill's lifecycle. Use the hooks field to specify PreToolUse, PostToolUse, or Stop handlers:

---
name: secure-operations
description: Perform operations with additional security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
---

The once: true option runs the hook only once per session. After the first successful execution, the hook is removed.

Hooks defined in a Skill are scoped to that Skill's execution and are automatically cleaned up when the Skill completes.

See Hooks for the full hook configuration format.

Control Skill Visibility

Skills can be invoked in three ways:

1. Manual invocation: Type /skill-name in your prompt
2. Programmatic invocation: Claude invokes through the Skill tool
3. Auto-discovery: Claude reads Skill descriptions and loads when relevant to conversation

The user-invocable field controls only manual invocation. Setting it to false hides the Skill from the slash command menu, but Claude can still invoke it programmatically or discover it automatically.

To block programmatic invocation via the Skill tool, use disable-model-invocation: true instead.

When to Use Each Setting

Example: Model-Only Skill

Set user-invocable: false to hide a Skill from the slash menu while allowing Claude to invoke it programmatically:

---
name: internal-review-standards
description: Apply internal code review standards when reviewing pull requests
user-invocable: false
---

With this setting, users won't see the Skill in the / menu, but Claude can still invoke it via the Skill tool or discover it automatically based on context.

Skills and Subagents

There are two ways Skills and subagents can work together:

Give Subagents Access to Skills

Subagents don't automatically inherit Skills from the main conversation. To give a custom subagent access to specific Skills, list them in the subagent's skills field:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Review code for quality and best practices
skills: pr-review, security-check
---

Listed Skills are loaded into the subagent's context when it starts. Omitting the skills field means no Skills are preloaded for that subagent.

Run a Skill in Subagent Context

Use context: fork and agent to run a Skill in a forked subagent with its own separate context. See run Skills in a forked context for details.

Deploy Skills

You can share Skills in several ways:

• Project Skills: Commit .claude/skills/ to version control. Everyone who clones the repository gets the Skills.
• Plugins: To share Skills across multiple repositories, create a skills/ directory with Skill folders containing SKILL.md files in a plugin. Distribute through plugin marketplaces.
• Managed: Administrators can deploy Skills organization-wide via managed settings. See the managed Skill path in where Skills live.

Examples

These examples show common Skill patterns from minimal single-file Skills to multi-file Skills with supporting documentation and scripts.

Simple Skill (Single File)

A minimal Skill requires only a SKILL.md file with frontmatter and instructions. This example helps Claude generate commit messages by reviewing staged changes:

commit-helper/
└── SKILL.md

---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best practices

- Use present tense
- Explain what and why, not how

Using Multiple Files

For complex Skills, use progressive disclosure to keep the main SKILL.md focused while providing detailed documentation in supporting files. This PDF processing Skill includes reference documentation, utility scripts, and uses allowed-tools to restrict Claude to specific tools:

pdf-processing/
├── SKILL.md              # Overview and quick start
├── FORMS.md              # Form field mappings and filling instructions
├── REFERENCE.md          # API details for pypdf and pdfplumber
└── scripts/
    ├── fill_form.py      # Utility to populate form fields
    └── validate.py       # Checks PDFs for required fields

SKILL.md:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
allowed-tools: Read, Bash(python:*)
---

# PDF Processing

## Quick start

Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

## Requirements

Packages must be installed in your environment:
```bash
pip install pypdf pdfplumber
```

Troubleshooting

View and Test Skills

To check which Skills Claude has access to, ask Claude questions like "What Skills are available?" Claude loads the name and description of all available Skills into its context window when a conversation starts, so it can list which Skills it currently has access to.

To test a specific Skill, ask Claude to perform a task that matches the Skill's description. For example, if a Skill's description says "review pull requests for code quality", ask Claude to "review the changes in the current branch." Claude will automatically use the Skill when your request matches its description.

Skill Not Triggering

The description field is how Claude decides whether to use a Skill. A vague description like "helps with documentation" doesn't give Claude enough information to match the Skill to relevant requests.

Good descriptions answer two questions:

1. What does this Skill do? List specific capabilities.
2. When should Claude use it? Include trigger terms users would mention.

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

This description works because it names specific actions (extract, fill, merge) and includes keywords users would say (PDF, forms, document extraction).

Skill Not Loading

Check file paths. Skills must be in the correct directory with the exact filename SKILL.md (case-sensitive):

Check YAML syntax. Invalid YAML in frontmatter prevents Skills from loading. Frontmatter must start with --- on line 1 (no blank lines before), end with --- before markdown content, and use spaces for indentation (not tabs).

Run debug mode. Use claude --debug to see Skill loading errors.

Skill Has Errors

Verify dependencies are installed. If a Skill uses external packages, you must install them in your environment before Claude can use them.

Check script permissions. Scripts require execute permissions: chmod +x scripts/*.py

Check file paths. Use forward slashes (Unix-style) in all paths. Use scripts/helper.py, not scripts\helper.py.

Multiple Skills Conflicting

If Claude uses the wrong Skill or seems confused between similar Skills, the descriptions are probably too similar. Differentiate each description with specific trigger terms.

For example, instead of both Skills having "data analysis", make one "sales data from Excel files and CRM exports" and the other "log files and system metrics". The more specific the trigger terms, the easier Claude can find the right Skill to match your request.

Plugin Skills Not Appearing

Symptom: You installed a plugin from a marketplace but Skills don't appear when you ask Claude "What Skills are available?"

Solution: Clear the plugin cache and reinstall:

rm -rf ~/.claude/plugins/cache

Then restart Claude Code and reinstall the plugin:

/plugin install plugin-name@marketplace-name

This forces Claude Code to re-download and re-register the plugin's Skills.

If Skills still don't appear, verify the plugin's directory structure is correct. Skills must be in a skills/ directory at the plugin root:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt