Creating Agent Skills

Overview

Agent Skills are modular capabilities that extend Claude's functionality by packaging domain expertise, instructions, and resources into reusable components. This skill guides you through the complete process of creating effective Skills that follow progressive disclosure principles and industry best practices.

When to Use This Skill

Use this skill when you need to:

• Create a new Agent Skill from scratch
• Improve or restructure an existing Skill
• Understand progressive disclosure patterns
• Integrate scripts and executable resources
• Validate and test Skill effectiveness

Core Principles

Progressive Disclosure: Load information in three levels:

1. Metadata - Brief descriptions for recognition (always loaded)
2. Instructions - Detailed guidance in SKILL.md (loaded when triggered)
3. Resources - Supporting files accessed as needed (loaded selectively)

Context Efficiency: The context window is a shared resource. Only include information Claude doesn't already possess.

Appropriate Freedom: Match specificity to task requirements:

• High freedom: Flexible tasks (code reviews, analysis)
• Medium freedom: Preferred patterns (templates, conventions)
• Low freedom: Error-prone operations (migrations, deployments)

Skill Creation Workflow

1. Plan Your Skill

Before writing, answer these questions:

• What specific task or domain does this Skill address?
• What procedural knowledge are you capturing?
• Does Claude lack this capability natively?
• Can this be reused across multiple use cases?

2. Structure Your Skill

Create a directory containing:

• SKILL.md - Main file with metadata and instructions (under 500 lines)
• Supporting files for detailed content
• Scripts for deterministic operations
• Templates and reference materials

See skill-structure.md for detailed organization guidance.

3. Write Metadata and Descriptions

Craft clear, actionable metadata that helps Claude recognize when to use your Skill:

• Name using gerund form (verb + -ing)
• Description in third person stating what it does and when to use it
• Keep descriptions concise but specific

See writing-metadata.md for naming conventions and examples.

4. Organize Content with Progressive Disclosure

Structure your content so Claude loads only what's needed:

• High-level instructions in SKILL.md
• Detailed content in referenced files
• One-level-deep references (avoid chains)

See progressive-disclosure.md for patterns and strategies.

5. Integrate Scripts and Code

Provide executable resources for deterministic operations:

• Pre-written scripts for reliable, repeatable tasks
• Utility functions that handle edge cases
• Error handling that solves problems rather than punting to Claude

See scripts-and-code.md for integration techniques.

6. Test and Validate

Ensure your Skill works effectively:

• Test across Haiku, Sonnet, and Opus models
• Verify progressive disclosure works as intended
• Validate scripts execute correctly
• Confirm instructions are clear and actionable

See testing-validation.md for comprehensive testing approaches.

7. Deploy and Enable

Make your Skill available to Claude:

• Copy to .claude/skills/ directory (Claude Code)
• Upload via UI (Claude.ai)
• Reference via API (Claude API)
• Set proper file permissions
• Install script dependencies

See deployment-setup.md for detailed deployment instructions.

Quick Reference

File Naming Conventions:

• Main file: SKILL.md (all caps)
• Supporting files: lowercase with hyphens (e.g., skill-structure.md)
• Scripts: descriptive names (e.g., extract_pdf_fields.py)

YAML Metadata Structure:

---
name: Skill Name in Gerund Form
description: Third-person description of what the skill does and when to use it. Keep under 200 characters for optimal display.
---

Content Guidelines:

• Keep SKILL.md under 500 lines
• Use consistent terminology throughout
• Avoid time-sensitive information
• Provide concrete examples
• Include validation loops where appropriate

Examples

For complete worked examples of Skills, see skill-examples.md.

Common Pitfalls to Avoid

Overloading SKILL.md: Don't put everything in one file. Use progressive disclosure to separate concerns.

Vague Descriptions: "Helps with PDFs" is too vague. "Extracts text from PDFs and fills forms. Use when working with PDF files" is specific.

Missing Error Handling: Scripts should handle errors explicitly, not leave problems for Claude to debug.

Inconsistent Terminology: Choose one term and stick with it (e.g., always "API endpoint," never mix with "route" or "URL").

Time-Sensitive Content: Don't reference specific dates or versions. Use "Old Patterns" sections for deprecated methods.

Next Steps

1. Review the detailed guidance in the supporting files
2. Create your Skill directory structure
3. Write and test your SKILL.md file
4. Add supporting resources as needed
5. Validate across multiple models and use cases
6. Deploy to .claude/skills/ or your target platform

For platform-specific implementation details, consult the official Anthropic documentation at https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview