creating-skills

Creating Agent Skills

Quick Start: 5-Step Workflow

Creating an Agent Skill involves planning, designing, and packaging. Follow this workflow:

1. Determine Purpose & Scope - What problem does your Skill solve?
2. Design Using PLANNING.md - Clarify use cases and structure
3. Create SKILL.md from Template - Use SKILL_TEMPLATE.md as your starting point
4. Review with Checklist - Validate against CHECKLIST.md before finalizing
5. Integrate - Add to settings.json and test

Skill Planning

Before writing SKILL.md, use PLANNING.md to clarify:

• Name: Gerund form, kebab-case (e.g., processing-pdfs, analyzing-spreadsheets)
• Description: What it does + when to use it (max 1024 chars)
• Scope: What's included / excluded
• Target Users: Who will use this Skill?
• Use Cases: 2-3 concrete scenarios

Planning prevents unclear Skill designs and ensures the final SKILL.md is discoverable.

SKILL.md Structure

Your Skill needs a SKILL.md file with this structure:

---
name: your-skill-name
description: What this Skill does and when to use it
---

# Your Skill Name

## Quick Start
[Minimal example or 2-3 line overview]

## Key Concepts
[What Claude needs to know to use this Skill]

## Workflows
[Step-by-step instructions for common tasks]

## Examples
[Real input/output pairs]

## Reference
[Link to detailed files: ADVANCED.md, API.md, etc]

Critical Guidelines:

• Keep SKILL.md under 300 lines (progressive disclosure)
• Description must state both "what" and "when to use"
• Naming must use lowercase letters, numbers, hyphens (no spaces, caps, or special chars)
• Examples should include input/output pairs

For detailed structure guidance, see STRUCTURE.md.

Best Practices Summary

Conciseness: SKILL.md body should be ~200-300 lines. Put detailed content in separate files (ADVANCED.md, REFERENCE.md) and reference them from SKILL.md.

Naming: Use gerund form: processing-pdfs not pdf-processor. Names are lowercase only.

Description: Include both capability and discovery keywords.

• ✓ "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."
• ✗ "Processes documents"

Progressive Disclosure: Structure content in levels:

• Level 1: Metadata (YAML frontmatter) - always loaded
• Level 2: SKILL.md body - loaded when Skill triggers
• Level 3: Reference files - loaded only when needed

Testing: Create evaluations before writing extensive docs. Test your Skill with actual use cases.

For comprehensive best practices, see BEST_PRACTICES.md.

Examples & Patterns

Pattern 1: Reference-Heavy Skill

When you have extensive content, structure it like this:

your-skill/
├── SKILL.md (200-250 lines)
├── REFERENCE.md (API, detailed patterns)
├── ADVANCED.md (complex scenarios)
└── EXAMPLES.md (input/output samples)

SKILL.md points to these files; Claude loads them as needed.

Pattern 2: Simple Skill

For straightforward Skills, everything can fit in SKILL.md:

simple-skill/
└── SKILL.md (100-150 lines)

See EXAMPLES.md for real implementations (RsDT, etc).

Validation Checklist

Before finalizing, verify:

• Name: lowercase, hyphens, gerund form
• Description: includes "what" and "when to use" (≤1024 chars)
• SKILL.md ≤300 lines
• Frontmatter has name and description only (no other fields)
• Quick Start section present and minimal
• Examples include concrete input/output
• All file references are one level deep (no nested references)
• No XML tags in name or description
• Tested with actual use case

See CHECKLIST.md for the full quality rubric.

Common Mistakes

Too verbose: SKILL.md tries to include everything. Split into ADVANCED.md, REFERENCE.md.

Unclear description: Doesn't say when Claude should use this Skill. Add keywords: "use when", "use for", etc.

Inconsistent naming: Mix of my-skill, MySkill, my_skill. Stick to gerund form, lowercase, hyphens.

Deeply nested references: SKILL.md → ADVANCED.md → DETAILS.md. Keep references one level deep from SKILL.md.

No examples: Say "extract text from PDFs" but show no code. Always include concrete input/output pairs.

Getting Started

1. Read PLANNING.md to define your Skill
2. Use SKILL_TEMPLATE.md as your starting point
3. Fill in the template section by section
4. Review against CHECKLIST.md
5. For reference, see EXAMPLES.md

Additional Resources

• API/Library Docs: Use context7 MCP to fetch latest documentation
• Web Search: Use WebSearch to find current best practices and patterns
• Official Docs: See https://platform.claude.com/docs/en/agents-and-tools/agent-skills/ for complete Agent Skills documentation

Key Principle: Progressive disclosure keeps your Skill efficient. SKILL.md is the entry point; detailed content lives in reference files accessed only when needed.