Creating Skills

Creating Skills

Skills are instruction folders that teach Claude specialized workflows. The core principle is progressive disclosure: minimize tokens while maintaining expertise.

Skill Structure

skill-name/
├── SKILL.md           # Required. Frontmatter + instructions
├── references/        # Optional. Deep documentation (loaded on-demand)
├── scripts/           # Optional. Executable code
└── assets/            # Optional. Templates, icons

SKILL.md Template

---
name: kebab-case-name
description: Use when [trigger conditions]. [What it does]. [When to apply it].
---

# Skill Title

## Overview
One paragraph: what this skill does and the core principle.

## Instructions
Step-by-step guidance or reference content.

## References
- Link to [references/detail.md](references/detail.md) for deep content

Writing the Description

The description field is the most critical part. It's always loaded in Claude's system prompt and determines auto-invocation.

Rules:

• Start with "Use when..." followed by trigger conditions
• Include natural keywords users would say
• Keep under 1024 characters
• Be specific about what AND when

Good:

description: Use when creating new skills, editing existing skills, or reviewing skill quality. Use when user mentions building, writing, or improving a SKILL.md file.

Bad:

description: Helps with skills

Content Guidelines

Be Concise

The context window is shared. Claude is already smart — only add domain-specific knowledge it doesn't have. Keep SKILL.md body under 500 lines.

Match Degrees of Freedom to Task

Use Consistent Terminology

Pick one term per concept. Don't alternate between "skill", "command", and "instruction" — use "skill" throughout.

Progressive Disclosure (3 Levels)

1. Frontmatter — Always loaded. Just enough for Claude to know when to use it
2. SKILL.md body — Loaded when skill is invoked. Full instructions
3. Referenced files — Loaded on-demand. Deep documentation, examples, APIs

Frontmatter Reference

Skill Types

Reference skills — Add knowledge Claude applies to current work (conventions, patterns, domain knowledge). Run inline with conversation context.

Task skills — Step-by-step instructions for specific actions. Often use disable-model-invocation: true and context: fork.

String Substitutions

Distribution

Priority: Enterprise > Personal > Project > Plugin.

Testing Checklist

Run these three test types before considering a skill complete:

1. Triggering Test

• Ask Claude something that should activate the skill (without /invoking it)
• Verify the description keywords match natural language triggers
• Test phrases that should NOT trigger it

2. Functional Test

• Invoke with /skill-name directly
• Verify Claude follows instructions correctly
• Test with and without arguments
• Check edge cases

3. Performance Test

• Is SKILL.md under 500 lines?
• Does Claude complete tasks in reasonable steps?
• Are referenced files loaded only when needed?

Common Mistakes

References

• Anthropic Official Guide — Condensed content from the 32-page PDF
• Patterns & Troubleshooting — 5 reusable patterns + debugging