Skills

NEW

Domain expertise defined via SKILL.md files that Claude applies automatically

What are Skills?

A Skill is a SKILL.md file with YAML frontmatter that teaches Claude how to do something specific. When you ask Claude something matching a Skill's description, it automatically applies the skill's instructions, tools, and context.

Automatic Invocation

Claude detects when a Skill is relevant and applies it automatically based on the description

SKILL.md Format

YAML frontmatter for metadata + markdown body for instructions and context

Hot Reload

Skills reload automatically when modified — no session restart needed

Where Skills Live

Location	Path	Applies To
Enterprise	Managed Settings	All users in organization
Personal	~/.claude/skills/	You, across all projects
Project	.claude/skills/	Anyone in this repository
Plugin	skills/ in plugin	Anyone with plugin installed

Priority order: Enterprise > Personal > Project > Plugin (higher wins on name conflicts)

SKILL.md Structure

Simple Skill

---
name: explaining-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---

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
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake?

Advanced Skill with Full Frontmatter

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files.
allowed-tools: Read, Bash(python:*)
model: claude-opus-4-5-20251101
context: fork
---

# 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).

Frontmatter Fields

Field	Required	Description
name	Yes	Lowercase letters, numbers, hyphens (max 64 chars)
description	Yes	What it does and when to use (max 1024 chars)
allowed-tools	No	Restrict tools Claude can use (e.g., Read, Grep, Bash)
model	No	Override model (e.g., claude-opus-4-5-20251101)
context	No	Set to "fork" for isolated sub-agent context
agent	No	Agent type when context: fork (Explore, Plan, etc.)
hooks	No	Define PreToolUse, PostToolUse, Stop handlers
user-invocable	No	Show in slash menu (default: true)

Skills with Hooks

Skills can define hooks that run during the skill's lifecycle. Hooks are scoped to the skill and automatically cleaned up when it finishes.

Example: Security Check Hook

---
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
---

Security-first operations with automatic validation.

Skills vs Other Options

Use This	When You Want To...	When It Runs
Skills	Give Claude specialized knowledge	Claude chooses when relevant
Slash Commands	Create reusable prompts	You type /command
CLAUDE.md	Set project-wide instructions	Loaded every conversation
Subagents	Delegate to separate context	Claude delegates or explicit
Hooks	Run scripts on events	On specific tool events
MCP Servers	Connect to external tools	Claude calls as needed

Multi-File Skills (Progressive Disclosure)

For complex skills, put essential info in SKILL.md and detailed docs in separate files. Claude reads the supporting files only when needed, keeping context lean.

pdf-processing/

├── SKILL.md # Overview and navigation

├── FORMS.md # Loaded when needed

├── REFERENCE.md # Loaded when needed

└── scripts/

├── fill_form.py # Executed, not loaded

└── validate.py

Tip: Keep SKILL.md under 500 lines. Scripts in the skill directory can be executed without loading into context.

Testing Your Skills

View Available Skills

What Skills are available?

Test a Skill

Ask a question matching the skill description, or invoke directly with /skill-name:

How does this code work?

Start Building Skills

Create your first skill to encode your team's standards, workflows, and domain knowledge.

Read Full Documentation