create-skill

Creating Claude Code Skills

Overview

Skills are reusable instruction sets that extend Claude Code's capabilities. They're stored as SKILL.md files with YAML frontmatter and Markdown instructions.

Skill Locations

Instructions

When creating a skill:

1. Determine scope: Ask if the skill should be personal (~/.claude/skills/) or project-level (.claude/skills/)

2. Create directory structure:

   .claude/skills/<skill-name>/
   └── SKILL.md
   

3. Write the SKILL.md file with required frontmatter:

   ---
   name: skill-name
   description: What this skill does. Use when [trigger conditions].
   ---
   
   # Skill Name
   
   ## Instructions
   Step-by-step guidance...
   
   ## Examples
   Concrete examples...
   

Required Frontmatter Fields

Optional Frontmatter Fields

Naming Rules

• Use only lowercase letters, numbers, and hyphens
• Directory name should match the skill name
• File must be exactly SKILL.md (case-sensitive)

Best Practices

1. Write trigger-focused descriptions: Include keywords users would naturally say
2. Keep SKILL.md under 500 lines: Use progressive disclosure for detailed content
3. Include concrete examples: Show exactly how the skill should behave
4. Link supporting files: If you need reference material, put it in separate .md files and link from SKILL.md
5. Bundle utility scripts: Place helper scripts in a scripts/ subdirectory

Example: Simple Skill

---
name: commit-message
description: Generate commit messages from staged changes. Use when writing commits or reviewing diffs.
---

# Commit Message Generator

## Instructions

1. Run `git diff --staged` to see changes
2. Create a commit message with:
   - Summary under 50 characters (imperative mood)
   - Blank line
   - Detailed description of what and why

## Example Output

Add user authentication middleware

Implement JWT-based authentication that validates tokens on protected routes. Includes refresh token support and automatic token renewal.

Example: Multi-File Skill

api-testing/
├── SKILL.md
├── PATTERNS.md
└── scripts/
    └── mock_server.py

SKILL.md:

---
name: api-testing
description: Test REST APIs with mocking and assertions. Use when testing endpoints or writing API tests.
allowed-tools: Read, Write, Bash
---

# API Testing

## Quick Start
...

For common patterns, see [PATTERNS.md](PATTERNS.md).

After Creating

Remind the user to restart Claude Code or start a new conversation for the skill to be available.