Complete guide to Agent Skills - modular capabilities that extend Claude's functionality. Use when user asks about creating Skills, Skill structure, progressive disclosure, or custom capabilities for Claude.
Extends Claude with modular capabilities that automatically trigger based on context. Use when users ask about creating custom skills, structuring SKILL.md files with YAML frontmatter, configuring tool access controls, or implementing progressive disclosure for complex workflows.
/plugin marketplace add reggiechan74/claude-plugins/plugin install claude-code-metaskill@claude-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Agent Skills are modular capabilities that extend Claude's functionality by packaging instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant. They transform Claude from a general-purpose assistant into a domain specialist.
Skills operate within Claude's virtual machine environment with filesystem access. They use progressive disclosure—loading information in stages as needed rather than consuming context upfront.
Level 1 - Metadata (Always loaded) YAML frontmatter provides discovery information (~100 tokens per Skill):
---
name: pdf-processing
description: Extract text, fill forms, merge documents
---
Level 2 - Instructions (Loaded when triggered) Main SKILL.md body contains procedural guidance (under 5k tokens). Claude reads this file only when the Skill matches the user's request.
Level 3 - Resources (Loaded as needed) Additional files (FORMS.md, scripts, reference materials) are accessed only when referenced—effectively unlimited content without token penalty.
skill_id parameter.claude/skills/Anthropic provides ready-to-use Skills:
Every Skill needs a SKILL.md file with YAML frontmatter:
---
name: your-skill-name
description: What this does and when to use it
---
# Your Skill Name
## Instructions
[Step-by-step guidance]
## Examples
[Concrete usage examples]
Requirements:
name: Maximum 64 characters, lowercase letters/numbers/hyphens onlydescription: Non-empty, maximum 1024 characters~/.claude/skills/skill-name/.claude/skills/skill-name/ (shared via git)Skills can include additional resources:
Claude loads these progressively based on context.
Use allowed-tools frontmatter to restrict Claude's capabilities when using a Skill:
allowed-tools: Read, Grep, Glob
This limits tool usage without requiring permission prompts.
Tools That Require Permission:
Tools That Don't Require Permission:
Read-only Skill:
allowed-tools: Read, Grep, Glob
Analysis Skill with web access:
allowed-tools: Read, Grep, Glob, WebFetch
Code generation Skill:
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
Research Skill:
allowed-tools: Read, WebFetch, WebSearch, TodoWrite
Conciseness: Context windows are shared resources. Only include information Claude doesn't already possess. Challenge each piece: "Does Claude really need this?"
Degrees of Freedom: Match specificity to task fragility:
Multi-Model Testing: Verify Skills work across Haiku, Sonnet, and Opus since effectiveness depends on the underlying model.
Frontmatter Requirements:
name: 64 characters max, lowercase letters/numbers/hyphens onlydescription: Non-empty, 1024 characters max, specific about what and when to useNaming: Use gerund form ("processing-pdfs") for clarity and consistency across skill collections.
Descriptions: Write in third person, be specific with key terms, explain both functionality and use cases. Avoid vague descriptions like "helps with documents."
Keep SKILL.md under 500 lines. Bundle additional content (reference files, examples, domain-specific guides) that Claude loads only when needed. Structure as:
Avoid time-sensitive information. Use consistent terminology throughout ("API endpoint" not mixed with "URL" or "route").
Create evaluations before extensive documentation. Build three representative scenarios, establish baselines, write minimal instructions addressing identified gaps, then iterate based on results.
Iterative Development: Work with one Claude instance ("Claude A") to design Skills tested by other instances ("Claude B"), observing real behavior and refining accordingly.
\)Description Specificity: Vague descriptions prevent discovery. Include both functionality and usage triggers with concrete terminology users would mention.
File Paths: Use Unix-style forward slashes consistently.
YAML Validation: Ensure proper opening/closing --- delimiters and correct indentation (spaces only).
Recommended approach: distribute via plugins. Alternative: commit Skills to project repositories; team members automatically access them after pulling changes.
Only use Skills from trusted sources. Malicious Skills could direct Claude to misuse tools or expose data. Thoroughly audit all bundled files, scripts, and external resource references before deploying.
Use slash commands for: Simple, frequently-used prompts that fit in one file.
Use Skills for: Complex capabilities requiring multiple files, scripts, or organizational structure.
Key difference: Commands require explicit invocation; Skills are discovered automatically based on context.
Quality:
Code:
Testing:
Create employment contracts, offer letters, and HR policy documents following legal best practices. Use when drafting employment agreements, creating HR policies, or standardizing employment documentation.
Implement GDPR-compliant data handling with consent management, data subject rights, and privacy by design. Use when building systems that process EU personal data, implementing privacy controls, or conducting GDPR compliance reviews.