creating-skills

Creating Agent Skills for Claude Code

This skill guides you through creating Agent Skills—packaged prompts that extend Claude Code's capabilities for specific workflows.

What you'll learn:

• Design skill structure with progressive disclosure
• Write token-efficient YAML frontmatter and instructions
• Choose appropriate workflow patterns
• Apply best practices and avoid common pitfalls

Output: A complete, well-structured skill ready for use in Claude Code.

When to Use This Skill

Use this skill when:

• Creating a new skill: Building from scratch with proper structure

Trigger phrases: "create skill", "build skill", "new agent skill", "skill development"

Prerequisites

Before creating a skill:

• Clear understanding of the task/workflow your skill will address

Note on Guidelines: Guideline files contain examples at the end. Refer to them if something is unclear or if the guideline notes the example is opinionated.

Core Workflow

1. Understand the Need: Identify the capability gap and specific tasks the skill will handle
2. Choose Workflow Pattern: Select from guidelines/workflow-patterns-guide.md and confirm with user
3. Create Structure:
   • Create directory: .claude/skills/skill-name/ or ~/.claude/skills/skill-name/
   • Create SKILL.md with YAML frontmatter (see Creating Frontmatter)
4. Write Core Content:
   • Add main workflow instructions (keep main file <5k tokens)
   • Create supporting files in guidelines/ for detailed content
   • Reference guidelines using relative paths

See Supporting Workflows for detailed guidance on each step.

Supporting Workflows

Creating Frontmatter

Write YAML frontmatter at the top of SKILL.md:

---
name: skill-name          # Use gerund form: "verb-ing"
description: What it does. Use when [trigger phrases].
allowed-tools: [Read, Write, Bash]  # Optional: restrict tools
---

Details: See guidelines/frontmatter-guide.md

Structuring Files

Use progressive disclosure:

• SKILL.md: Core workflow (<5k tokens)
• guidelines/: Detailed content loaded on-demand (optional)
• templates/: Reusable templates (optional)
• scripts/: Executable helpers (optional)

Details: See guidelines/file-structure-guide.md

Writing Instructions

Match instruction specificity to task fragility:

• High freedom: Creative tasks
• Low freedom: Critical operations requiring exact steps

Use clear, actionable language. Avoid choice overload.

Details: See guidelines/instruction-writing-guide.md

Optimizing Tokens

• Challenge every word: "Does Claude already know this?"
• Keep SKILL.md under 5k tokens
• Move verbose content to supporting files
• Use executable scripts instead of long code listings

Details: See guidelines/token-efficiency-guide.md

Guidelines Reference

Detailed guides available on-demand:

• frontmatter-guide.md: YAML specifications, naming conventions, description formats
• file-structure-guide.md: Progressive disclosure patterns, directory organization
• instruction-writing-guide.md: Freedom levels, instruction patterns, writing clear steps
• token-efficiency-guide.md: Token budgets, optimization strategies
• workflow-patterns-guide.md: 6 workflow patterns (linear, conditional, validation loop, multi-phase, iterative, parallel)
• anti-patterns-guide.md: Common mistakes and how to avoid them
• examples-guide.md: Example placement strategies (templates vs guidelines)

Common Patterns & Anti-Patterns

✅ Do

• Use gerund form for names: creating-reports, analyzing-data
• Include trigger phrases in description
• Keep SKILL.md under 5k tokens
• Use progressive disclosure with supporting files
• Provide one clear default approach
• Use forward slashes in all paths
• Match instruction specificity to task fragility

❌ Don't

• Vague names: helper, tool
• Missing trigger phrases in description
• Monolithic files (>10k tokens)
• Choice overload: "Use A or B or C or D"
• Windows-style backslashes in paths
• Over-explaining what Claude already knows
• Nested file references (more than one level deep)

See guidelines/anti-patterns-guide.md for detailed examples.

Best Practices

1. Token Efficiency First: Challenge every word. Does Claude already know this?
2. Progressive Disclosure: Load content on-demand via supporting files. Use clear file structure and section mapping (e.g., table of contents) to help Claude quickly identify which files are most relevant
3. Clear Defaults: Provide one recommended approach, not multiple options
4. Actionable Instructions: Specific steps that are verifiable
5. Consistent Terminology: Use the same terms throughout
6. Appropriate Freedom: Match instruction specificity to task fragility

Remember: A well-crafted skill should be concise, clear, and immediately actionable.