Skill Creator

Create new Claude Code skills following the official format and best practices.

Quick Reference

• Templates and Examples - Skill templates and complete creation examples

When to Use

• Creating a new reusable knowledge module

• Adding specialized guidance for specific tasks

• Building domain-specific expertise into Claude Code

• Need to ensure proper skill format and structure

Skill Structure

A Claude Code skill consists of:

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

SKILL.md Format

name: skill-name description: Clear description of what this skill does and when to use it (max 1024 chars)

Skill Title

[Skill content in Markdown]

Naming Requirements

Skill Name Rules:

• Lowercase letters only

• Numbers allowed

• Hyphens for word separation (no underscores)

• No spaces

• Max 64 characters

• Descriptive and clear

Examples:

• ✅ episode-management

• ✅ test-debugging

• ✅ api-integration

• ✗ Episode_Management (no uppercase, no underscores)

• ✗ test debugging (no spaces)

Description Best Practices

The description is critical - Claude uses it to decide when to invoke the skill.

Good Description Structure:

[Action verb] [what it does] [when to use it]

Examples:

✅ Good:

description: Debug and fix failing tests in Rust projects. Use this skill when tests fail and you need to diagnose root causes, fix async/await issues, or handle race conditions.

✅ Good:

description: Implement new features systematically with proper testing and documentation. Use when adding new functionality to the codebase.

✗ Too vague:

description: Helps with testing

✗ Missing when-to-use:

description: Provides guidance on building APIs

Skill Creation Process

Step 1: Define Purpose

What problem does this skill solve?

• Specific task: [e.g., "Deploy to production"]
• Domain: [e.g., "deployment", "testing", "documentation"]
• User need: [e.g., "Ensure safe deployments"]

Step 2: Choose Name

Skill name: [lowercase-with-hyphens]

• Descriptive: Clearly indicates purpose
• Concise: Not too long
• Unique: Doesn't conflict with existing skills

Step 3: Write Description

description: [Action] [what it does]. Use this when [specific scenarios].

Key elements:

1. Clear action (verb)
2. What problem it solves
3. When to invoke it
4. Keywords Claude can match on

Step 4: Structure Content

Recommended Sections:

• Introduction: Brief overview of skill purpose

• When to Use: Specific scenarios for invocation

• Core Concepts: Key knowledge needed

• Process/Workflow: Step-by-step guidance

• Examples: Concrete usage examples

• Best Practices: Do's and don'ts

• Integration: How this works with other skills/agents

Content Guidelines:

• Clear, concise language

• Actionable instructions

• Concrete examples

• Code snippets where helpful

• Checklists for processes

• Visual diagrams (ASCII art) for complex flows

Step 5: Create Files

Create directory

mkdir -p .claude/skills/skill-name

Create SKILL.md with content

cat > .claude/skills/skill-name/SKILL.md << 'EOF'

name: skill-name description: Your description here

Skill Title

[Your skill content] EOF

Step 6: Test and Validate

Validation Checklist:

• Directory name matches skill name

• SKILL.md file exists

• YAML frontmatter is valid

• Name follows naming rules (lowercase, hyphens)

• Description is clear and specific (< 1024 chars)

• Content is well-structured

• Examples are provided

• Markdown is properly formatted

Skill Templates

See templates-and-examples.md for complete templates including:

Available Templates

• Process Skill - Step-by-step workflows

• Knowledge Skill - Domain expertise and concepts

• Tool Skill - Tool usage and best practices

Each template includes:

• Full YAML frontmatter

• Recommended sections

• Example content

• Best practices structure

Integration with Agent Creator

When creating skills that work with agents:

• Reference agents in skill: Mention which agents use this skill

• Skill-agent coordination: Ensure skill complements agent capabilities

• Invocation clarity: Make clear when skill vs agent is appropriate

Project-Specific Considerations

For Rust Self-Learning Memory Project

Domain-Specific Skills:

• Episode management (start, log, complete)

• Pattern extraction and storage

• Memory retrieval optimization

• Turso/redb synchronization

• Async/Tokio patterns

Skill Naming Convention:

• episode-[operation] for episode-related skills

• storage-[operation] for storage operations

• pattern-[operation] for pattern handling

• memory-[operation] for memory operations

Integration Requirements:

• Reference AGENTS.md standards

• Include examples using project structure

• Consider self-learning memory tracking

Skill Maintenance

Updating Skills

When updating existing skills:

• Preserve backward compatibility

• Update description if scope changes

• Add new sections without removing old ones

• Update examples to reflect current best practices

• Maintain clear version history in git

Deprecating Skills

If a skill becomes obsolete:

• Update description to indicate deprecation

• Point to replacement skill

• Keep file for backward compatibility

• Consider removing after transition period

Best Practices Summary

DO:

✓ Write clear, specific descriptions ✓ Include concrete examples ✓ Structure content logically ✓ Use consistent formatting ✓ Test skill by using it ✓ Update README.md to list new skill ✓ Follow naming conventions

DON'T:

✗ Use vague or generic descriptions ✗ Skip examples ✗ Make names too long or unclear ✗ Forget YAML frontmatter ✗ Use uppercase or underscores in names ✗ Exceed 1024 chars in description

Validation Command

After creating a skill, validate it:

Check structure

test -f .claude/skills/skill-name/SKILL.md && echo "✓ Structure correct"

Check YAML frontmatter

head -n 5 .claude/skills/skill-name/SKILL.md | grep "^name:" && echo "✓ YAML valid"

Check name format

[[ $(grep "^name:" .claude/skills/skill-name/SKILL.md | cut -d' ' -f2) =~ ^[a-z0-9-]+$ ]] && echo "✓ Name format correct"

Quick Creation Script

#!/bin/bash

create-skill.sh

SKILL_NAME=$1 DESCRIPTION=$2

if [ -z "$SKILL_NAME" ] || [ -z "$DESCRIPTION" ]; then echo "Usage: ./create-skill.sh skill-name "Skill description"" exit 1 fi

Validate name format

if ! [[ "$SKILL_NAME" =~ ^[a-z0-9-]+$ ]]; then echo "Error: Skill name must be lowercase with hyphens only" exit 1 fi

Create directory

mkdir -p ".claude/skills/$SKILL_NAME"

Create SKILL.md

cat > ".claude/skills/$SKILL_NAME/SKILL.md" <<EOF

name: $SKILL_NAME description: $DESCRIPTION

${SKILL_NAME^}

[Skill content goes here]

When to Use

• [Scenario 1]
• [Scenario 2]

Process

Step 1: [Action]

[Instructions]

Step 2: [Action]

[Instructions]

Examples

Example 1: [Name]

``` [Example code or workflow] ```

Best Practices

✓ [Do this] ✗ [Don't do this] EOF

echo "✓ Created skill: $SKILL_NAME" echo "✓ Edit: .claude/skills/$SKILL_NAME/SKILL.md"

Summary

Creating effective skills:

• Purpose: Solve specific, well-defined problems

• Naming: Clear, lowercase, hyphenated names

• Description: Specific, actionable, includes when-to-use

• Structure: Well-organized with clear sections

• Examples: Concrete, realistic usage examples

• Testing: Validate structure and use the skill

Skills are the foundation of Claude Code's knowledge. Well-designed skills make Claude more effective at autonomous task execution.

For complete templates and detailed examples, see templates-and-examples.md.