generation_date

received_date

updated_date

Claude Code Skills Reference

Source: Official Anthropic Documentation + Community Research (December 2025) Purpose: Reference for developing Claude Code Skills Last Updated: 2025-12-24 (added activation statistics and community best practices)

Skill Activation Statistics

Real-world testing across 200+ prompts reveals significant variation in activation reliability:

Approach	Success Rate	Key Characteristic
No optimization	~20%	Baseline/default behavior
Simple description	20%	Vague trigger language
Optimized description	50%	Specific USE WHEN patterns
LLM pre-eval hook	80%	API-based pre-screening
Forced eval hook	84%	Explicit evaluation requirement

Key Insight: Properly optimized descriptions can improve activation from 20% to 50%. Adding examples improves it further from 72% to 90%.

What Are Skills?

Agent Skills are modular, filesystem-based capabilities that extend Claude's functionality. They package instructions, metadata, and optional resources that Claude can automatically use when relevant.

Key Characteristics:

Composability - Skills can stack together
Portability - Same format across Claude apps, Claude Code, and API
Efficiency - Only loads necessary information when relevant
Powerful - Can include executable code for precise task completion

Installation Locations

Location	Type	Scope
`~/.claude/skills/`	Personal Skills	User-level, all projects
`.claude/skills/`	Project Skills	Project-specific
Plugin `skills/` subdirectory	Plugin Skills	Bundled with plugins

SKILL.md Structure

The SKILL.md file is the canonical entry point. It begins with YAML frontmatter followed by markdown instructions.

---
name: your-skill-name
description: Brief explanation of what the skill does and when to use it
allowed-tools: [Optional list of permitted tools]
---

# Skill Documentation

## Instructions
Step-by-step guidance for Claude

## Examples
Concrete usage scenarios

YAML Frontmatter Requirements

Field	Required	Constraints
`name`	Yes	Max 64 chars, lowercase letters/numbers/hyphens only, no XML tags, no 'anthropic' or 'claude'
`description`	Yes	Max 1024 chars, non-empty, no XML tags
`allowed-tools`	No	Array of tool names

Naming Conventions

Use gerund form (verb + -ing):

processing-pdfs
analyzing-spreadsheets
managing-databases
searching-vault

Description Writing: The Critical Factor

The description is critical for skill discovery. Claude uses it to choose the right Skill from potentially 100+ available Skills.

The Golden Rule: Third Person Only

The description is injected into the system prompt. Inconsistent point-of-view causes discovery problems.

Good:

description: Processes Excel files and generates reports

Avoid:

description: I can help you process Excel files
description: You can use this to process Excel files

The Two-Part Structure

Every description must answer:

What does it do? (Capability statement)
When to use it? (Trigger conditions)

Effective Pattern:

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.

USE WHEN Patterns

Include "Use when..." language within the description field for explicit triggers:

description: |
  Knowledge Management for Obsidian vault. USE WHEN user asks
  "what do I know about X", "find notes about", "load context
  for project", "save to vault", "capture this", "validate tags".

Specificity Over Generality

Bad (20% activation):

description: Helps with documents
description: Processes data
description: Does stuff with files

Good (50%+ activation):

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Better - Include Context:

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

How Skill Routing Works

Pure LLM Reasoning (No Embeddings)

Skills employ pure LLM reasoning for routing decisions rather than algorithmic matching:

The system formats all available skills into text descriptions embedded in the Skill tool's prompt, allowing Claude's language model to decide which skill matches user intent through its transformer forward pass—no embeddings, classifiers, or pattern matching occur at the code level.

Implications:

You're writing for Claude's language understanding, not keyword matching
Natural language triggers work better than artificial patterns
Context and semantic meaning matter more than exact phrase matching

Progressive Disclosure

Skills use a three-level loading mechanism:

Level	What Loads	When	Token Budget
Level 1	Metadata (name + description)	Always at startup	~100 tokens
Level 2	Main SKILL.md body	When skill is triggered	Under 5k tokens
Level 3	Referenced files (docs/, scripts/)	On-demand via Read tool	As needed

Key Insight: Only name and description are loaded initially. Keep SKILL.md under 500 lines and reference additional files for detailed documentation.

Token Budget: 15,000-character limit for entire available skills list.

The Five Fixes That Actually Work

Based on analysis of 40+ skill failures:

Fix #1: Write Specific Activation Triggers

Include exact keywords from your actual workflow:

# Instead of:
description: Code review tool

# Use:
description: Review code for best practices, potential bugs, and maintainability. Use when reviewing pull requests, checking code quality, analyzing diffs, or when user mentions "review", "PR", "code quality", or "best practices".

Fix #2: Show Real Examples (Not Descriptions)

"Claude learns from examples, not descriptions."

Examples should be longer than your rules section:

## Commit Message Format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

Fix #3: Progressive Disclosure

Keep SKILL.md under 500 lines:

# SKILL.md
## Quick start
[Essential info here]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

Claude reads FORMS.md and REFERENCE.md only when needed.

Fix #4: Set Explicit Boundaries

Define what the skill doesn't do:

## Out of Scope
This skill does NOT:
- Handle scanned PDFs (use OCR skill instead)
- Create PDFs from scratch (use document-generation skill)
- Process password-protected files

Fix #5: Test With Real Work

Evaluation-Driven Development:

Identify gaps - Run Claude without skill, document failures
Create evaluations - Build 3+ test scenarios
Establish baseline - Measure performance without skill
Write minimal instructions - Just enough to pass evaluations
Iterate - Test, compare, refine

Anti-Patterns to Avoid

Vague Triggers:

description: Helps with files

Too Many Options:

You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or...

Deeply Nested References:

# SKILL.md → See advanced.md
# advanced.md → See details.md
# details.md → [actual info]

Time-Sensitive Info:

If you're doing this before August 2025, use the old API.

Instead, Use "Old Patterns" Section:

## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
[Historical context here]
</details>

The Conciseness Principle

Default assumption: Claude is already very smart

Only add context Claude doesn't already have. Challenge each piece of information:

"Does Claude really need this explanation?"
"Can I assume Claude knows this?"
"Does this paragraph justify its token cost?"

Good (50 tokens):

## Extract PDF text

Use pdfplumber for text extraction:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Bad (150 tokens):

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing...

Recommended Folder Structure

skill-name/
├── SKILL.md              # Entry point (required, <500 lines)
├── docs/                 # Reference documentation
│   ├── CLI-REFERENCE.md
│   ├── CONCEPTS.md
│   └── EXAMPLES.md
├── workflows/            # Operational procedures
│   ├── workflow-a.md
│   └── workflow-b.md
├── scripts/              # Executable helpers
│   └── helper.py
└── templates/            # Reusable templates
    └── template.txt

Best Practices:

Keep SKILL.md as a 'menu' that routes to detailed docs
Use forward slashes for file paths
Avoid deeply nested references (one level from SKILL.md)
Organize reference files logically by topic

Description Template

---
name: [verb]-[noun] (e.g., processing-pdfs)
description: [Core capability statement]. [Secondary capabilities]. Use when [trigger condition 1], [trigger condition 2], or when user mentions "[keyword1]", "[keyword2]", "[keyword3]".
---

Optimization Checklist:

Written in third person (no "I" or "you")
Under 1024 characters
Contains both WHAT and WHEN
Includes 5+ specific trigger keywords
Uses exact terms from actual user requests
Mentions file types, formats, or domains
Tested with 3+ real scenarios

Three-Tier Activation Strategy

Level 1: Description Optimization (Low Effort, 50% Success)

Use specific "Use when" language
Include exact keywords from workflows
Add file type mentions (.xlsx, .pdf, etc.)

Level 2: CLAUDE.md References (Medium Effort, 60-70% Success)

Document skill usage patterns in project CLAUDE.md
Reference specific skills for common tasks
Create workflow documentation

Level 3: Custom Hooks (High Effort, 84% Success)

Implement forced evaluation hooks
Require explicit skill reasoning
Create commitment mechanisms

Recommendation: Start with Level 1 for all skills, escalate to Level 3 only for critical workflows.

Common Patterns

Workflow Routing

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **Ingestion** | 'save this', 'capture' | `workflows/ingestion.md` |
| **Search** | 'find notes', 'what context' | `workflows/search.md` |
| **Maintenance** | 'vault health', 'check' | `workflows/maintenance.md` |

Two-Phase Operations

For operations where Claude should wait for user input:

## Core Pattern: Two-Phase Retrieval

**CRITICAL:** Search and Load are ALWAYS separate turns.

Turn 1: Search → Show table → STOP
Turn 2: User says 'load 1,3,5' → Load content

NEVER run load in same turn as search.

Quick Reference Tables

## Quick Reference

| Intent | Command |
|--------|---------|
| Search by meaning | `ctx semantic 'query'` |
| Search by tag | `ctx search --tag X` |
| Save content | `ingest direct --tags 'X'` |

Best Practices Checklist

Structure

SKILL.md under 500 lines
YAML frontmatter with name and description
Clear section headers (Instructions, Examples)
References to detailed docs for complex topics

Description

Written in third person
Includes 'USE WHEN' trigger patterns
Specific key terms for discovery
Under 1024 characters

Examples

Concrete, not abstract scenarios
Show expected Claude behavior
Include common variations
Demonstrate multi-turn workflows if applicable
Examples longer than rules section

Testing

Test with team members
Test across Claude models (Haiku, Sonnet, Opus)
Verify discovery triggers correctly
Check progressive loading works

Maintenance

No time-sensitive information
Consistent terminology throughout
Version history documented
Clear ownership

Security Considerations

Only use Skills from trusted sources
Skills can execute code in the runtime environment
Potential risks include unauthorized system access
Review scripts before installation

Supported Platforms

Skills work across:

Claude API
Claude Code
Claude.ai (Pro, Max, Team, Enterprise)
Claude Agent SDK

Related Resources

Official Anthropic Documentation:

Skill Authoring Best Practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
Agent Skills Overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Claude Code Memory Docs: https://code.claude.com/docs/en/memory
Anthropic Skills GitHub: https://github.com/anthropics/skills

Community Analysis & Research:

Writing Claude Skills That Actually Work: https://medium.com/@creativeaininja/writing-claude-skills-that-actually-work
Claude Agent Skills Deep Dive: https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/
How to Make Skills Activate Reliably: https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably
40+ Skill Failures Analysis: https://cashandcache.substack.com/p/i-analyzed-40-claude-skills-failures

Document compiled from official Anthropic documentation and community research, December 2025 Updated 2025-12-24 with activation statistics and community best practices

mellanon/2025-12-17-Claude Code Skills Structure and Usage Guide.md