Creating Claude Code Skills

A meta-skill for creating well-structured, discoverable, and effective Claude Code skills.

Overview

Claude Skills are markdown files that teach Claude specialized knowledge. They're automatically discovered based on their description, so writing effective descriptions is critical.

Quick Start

1. Choose location based on scope:
   • Personal: ~/.claude/skills/your-skill/
   • Project: .claude/skills/your-skill/
2. Create directory and SKILL.md:

   mkdir -p .claude/skills/your-skill

3. Write SKILL.md with required frontmatter:

   ---
   name: your-skill-name
   description: [Trigger-rich description]
   ---

4. Validate using CHECKLIST.md

The Golden Rule: Description Is Everything

Claude uses the description field to decide when to apply your skill. A poor description means your skill never triggers.

Description Formula

[What it does] + [Specific capabilities] + [Trigger phrases]

Bad vs Good Descriptions

Skill Structure

Minimal (Single File)

your-skill/
└── SKILL.md

Standard (With Supporting Docs)

your-skill/
├── SKILL.md           # Overview + quick start (< 500 lines)
├── REFERENCE.md       # Detailed documentation
├── EXAMPLES.md        # Usage examples
└── CHECKLIST.md       # Validation checklist

Advanced (With Scripts)

your-skill/
├── SKILL.md
├── docs/
│   ├── api.md
│   └── patterns.md
└── scripts/
    ├── setup.sh       # Executed, not loaded as context
    └── validate.py

SKILL.md Template

See TEMPLATES.md for ready-to-use templates.

---
name: skill-name              # Lowercase, hyphens only (max 64 chars)
description: [description]    # Max 1024 chars - MOST IMPORTANT FIELD
allowed-tools: Read, Grep     # Optional - restrict tool access
---

# Skill Name

## Overview
[1-2 sentence summary of what this skill does]

## When to Use
[Specific scenarios, triggers, and use cases]

## Instructions
[Step-by-step guidance - numbered for clarity]

## Examples
[Concrete usage examples with expected outcomes]

## Resources
[Links to supporting files if applicable]

Tool Restrictions

Use allowed-tools to limit Claude's capabilities when the skill is active:

# Read-only skill
allowed-tools: Read, Grep, Glob

# Python automation only
allowed-tools: Bash(python:*)

# Multiple specific commands
allowed-tools: Read, Bash(git:*, npm:*, pnpm:*)

When to restrict:

• Read-only analysis (prevent accidental writes)
• Specific tooling (Python scripts, Git operations)
• Security-sensitive workflows

Progressive Disclosure

Keep SKILL.md focused. Link to supporting files for detail:

## Quick Reference
[Essential info here]

## Detailed Documentation
For complete API reference, see [REFERENCE.md](REFERENCE.md).
For troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

Why it matters:

• Claude loads SKILL.md first
• Supporting files load on-demand
• Keeps context focused for better performance
• Scripts execute without consuming tokens

Common Mistakes to Avoid

1. Vague descriptions - Include specific trigger keywords
2. Too broad scope - One skill = one purpose
3. Missing dependencies - Document required packages
4. No examples - Always include concrete usage
5. Monolithic SKILL.md - Use progressive disclosure for >500 lines
6. Similar descriptions - Make each skill's description distinct

Quality Checklist

Use CHECKLIST.md to validate your skill before committing.

Examples

See EXAMPLES.md for complete, production-ready skill examples.