Create Skill

create_skill

Guide for creating well-structured Claude Code skills following best practices.

Skill Structure

A skill should be organized as a directory with multiple files:

skills/
└── skill_name/
    ├── SKILL.md        # Main documentation (required)
    ├── examples.md     # Usage examples
    ├── reference.md    # Quick reference / cheatsheet
    └── templates/      # Reusable templates
        └── *.sh, *.py, etc.

SKILL.md Structure

The main skill file must start with YAML frontmatter for discoverability:

---
name: skill_name
description: One-line summary of what the skill does.
---

Then include:

1. Title - Skill name as H1 header (must match directory name)
2. Description - One-line summary of what the skill does
3. Core Content - The main instructions, commands, or guidance
4. Sections - Organized by topic with H2 headers

Best Practices

1. Design for Context Efficiency

Skills are loaded into Claude's context window. Keep them:

• Concise - Include only essential information
• Scannable - Use tables, lists, and code blocks
• Actionable - Focus on commands and procedures, not explanations

2. Use the 3-File Pattern

3. Include Templates

For repetitive tasks, provide templates in templates/ directory:

• Job scripts
• Config files
• Boilerplate code

4. Write for Search

Use clear, searchable headings:

• "## Job Submission" not "## How to Submit"
• "## GPU Jobs" not "## Using Graphics Cards"

5. Prefer Tables Over Prose

Tables are scannable and dense:

| Command | Description |
|---------|-------------|
| `cmd1` | Does X |
| `cmd2` | Does Y |

6. Use Consistent Code Blocks

Always specify the language:

# Shell commands
command --flag value

# Python code
def example():
    pass

Creating a New Skill

1. Create the directory structure:

   mkdir -p skills/my_skill/templates
   

2. Create SKILL.md with:

   • H1 title matching directory name
   • Brief description
   • Core commands/concepts

3. Add examples.md with real-world workflows

4. Add reference.md with quick-lookup tables

5. Add templates for common tasks

Installation Locations

Skills can be installed globally or kept in a local repository.

Global Skills (~/.claude/skills/)

Available in all Claude Code sessions:

cp -r skills/my_skill ~/.claude/skills/

Local Repository Skills

Keep skills in a git repository for version control and sharing:

my_skills_repo/
├── .claude/
│   └── settings.json    # Register skills path
└── skills/
    └── my_skill/
        └── SKILL.md

Create .claude/settings.json in your repo root:

{
  "skills": {
    "paths": ["skills"]
  }
}

Or add to existing project:

{
  "skills": {
    "paths": [".claude/skills"]
  }
}

Skills are discovered when Claude Code runs in that directory.

Comparison

Skill Naming

• Use snake_case for directory and file names
• Keep names short but descriptive
• Prefix with domain if needed (e.g., aws_lambda, docker_compose)