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:

1. Introduction: Brief overview of skill purpose
2. When to Use: Specific scenarios for invocation
3. Core Concepts: Key knowledge needed
4. Process/Workflow: Step-by-step guidance
5. Examples: Concrete usage examples
6. Best Practices: Do's and don'ts
7. 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

1. Process Skill - Step-by-step workflows
2. Knowledge Skill - Domain expertise and concepts
3. 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:

1. Reference agents in skill: Mention which agents use this skill
2. Skill-agent coordination: Ensure skill complements agent capabilities
3. 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:

1. Preserve backward compatibility
2. Update description if scope changes
3. Add new sections without removing old ones
4. Update examples to reflect current best practices
5. Maintain clear version history in git

Deprecating Skills

If a skill becomes obsolete:

1. Update description to indicate deprecation
2. Point to replacement skill
3. Keep file for backward compatibility
4. 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:

1. Purpose: Solve specific, well-defined problems
2. Naming: Clear, lowercase, hyphenated names
3. Description: Specific, actionable, includes when-to-use
4. Structure: Well-organized with clear sections
5. Examples: Concrete, realistic usage examples
6. 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.