creating-skills

Creating Skills

Overview

Skills are reference guides for proven techniques, patterns, or tools. Write them to help future Claude instances quickly find and apply effective approaches.

Skills must be discoverable (Claude can find them), scannable (quick to evaluate), and actionable (clear examples).

Core principle: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.

When to Use

Create a skill when:

• Technique wasn't intuitively obvious
• Pattern applies broadly across projects
• You'd reference this again
• Others would benefit

Don't create for:

• One-off solutions specific to single project
• Standard practices well-documented elsewhere
• Project conventions (put those in .claude/CLAUDE.md)

Required Structure

Frontmatter (YAML)

---
name: skill-name-with-hyphens
description: Use when [triggers/symptoms] - [what it does and how it helps]
tags: relevant-tags
---

Rules:

• Only name and description fields supported (max 1024 chars total)
• Name: letters, numbers, hyphens only (max 64 chars). Use gerund form (verb + -ing)
• Avoid reserved words: "anthropic", "claude" in names
• Description: Third person, starts with "Use when..." (max 1024 chars)
• Include BOTH triggering conditions AND what skill does
• Match specificity to task complexity (degrees of freedom)

Document Structure

# Skill Name

## Overview
Core principle in 1-2 sentences. What is this?

## When to Use
- Bullet list with symptoms and use cases
- When NOT to use

## Quick Reference
Table or bullets for common operations

## Implementation
Inline code for simple patterns
Link to separate file for heavy reference (100+ lines)

## Common Mistakes
What goes wrong + how to fix

## Real-World Impact (optional)
Concrete results from using this technique

Degrees of Freedom

Match specificity to task complexity:

• High freedom: Flexible tasks requiring judgment
  • Use broad guidance, principles, examples
  • Let Claude adapt approach to context
  • Example: "Use when designing APIs - provides REST principles and patterns"