---

name: create-skill description: Create effective Claude Code skills with specialized workflows, tool integrations, and domain expertise. Analyzes task complexity to recommend optimal model configuration. ultrathink: true execution_model: haiku

Skill Creation Meta-Agent

Create modular, self-contained skills that transform Claude from general-purpose into specialized agents.

MANDATORY PRE-EXECUTION STEPS

1. Read Official Documentation

MUST fetch and analyze Claude Code skill documentation before proceeding:

• https://docs.claude.com/en/docs/claude-code/skills.md
• Use WebFetch tool to retrieve latest specifications

2. Check for Existing Similar Skills

MUST use the provided utility script before creating a new skill:

python references/check_existing_skills.py "skill-name" "skill description" [--model MODEL] [--ultrathink]

This script analyzes:

• Existing skill metadata (name, description, execution_model, ultrathink)
• Similarity scores based on name, description, and keyword overlap
• Potential conflicts or overlap opportunities
• Suggestions for improvement or consolidation

Review the output and proceed accordingly:

• If high similarity (>60%): Consider extending existing skill instead
• If name conflict: Choose a different name
• Otherwise: Proceed with skill creation

3. Gather Context with EXPLORER

MUST use Task tool with subagent_type=Explore to:

• Investigate .claude/skills/agent_skills_spec.md if it exists
• Search for existing skills in .claude/skills/ to understand patterns
• Identify any project-specific skill conventions
• Report findings back before starting skill creation

Wait for Explorer results before continuing.

Skill Anatomy

.claude/skills/skill-name/
├── SKILL.md (required, <200 lines)
│   ├── YAML frontmatter
│   └── Markdown instructions
└── Optional Resources
    ├── scripts/        # Node.js/Python preferred
    ├── references/     # Detailed docs
    └── assets/         # Templates, configs

Model Selection by Complexity

Analyze user requirements and propose base model configuration:

Simple Tasks (haiku):

• Single-purpose utilities
• Basic file operations
• Simple transformations
• Template generation

Medium Tasks (sonnet):

• Multi-step workflows
• Code analysis/refactoring
• Integration of 2-3 tools
• Domain-specific operations

Complex Tasks (opus):

• Architectural decisions
• Multi-file codebase changes
• Advanced reasoning chains
• Research + implementation

Add to SKILL.md frontmatter:

execution_model: haiku|sonnet|opus

Creation Workflow

Step 1: Understand Requirements

Extract from user prompt:

• Primary purpose and use case
• Required tools/integrations
• Input/output expectations
• Complexity indicators

Step 2: Plan Structure

Determine:

• Skill name (hyphen-case)
• Bundled resources needed (scripts, references, assets)
• Progressive disclosure levels
• Model configuration based on complexity

Step 3: Write SKILL.md

Frontmatter Template:

---
name: skill-name
description: Clear one-liner describing purpose
execution_model: [haiku|sonnet|opus]
ultrathink: [true|false]  # Enable for complex reasoning
---

Content Structure:

1. Purpose statement (2-3 lines)
2. Core workflow steps (numbered, verb-first)
3. Tool usage instructions
4. Expected outputs
5. References to bundled resources

Writing Style:

• Imperative/infinitive form (verb-first: "Analyze", "Generate", "Execute")
• Objective, instructional language for AI consumption
• Sacrifice grammar for brevity
• Under 200 lines total

Step 4: Create Bundled Resources

Scripts (.py or .js preferred):

• Include .env.example for configuration
• Add basic tests or usage examples
• Document parameters clearly

References:

• External documentation links
• Code examples
• API specifications
• Best practices guides

Assets:

• Configuration templates
• Starter files
• Example outputs

Step 5: Package and Validate

Create complete skill structure:

.claude/skills/skill-name/
├── SKILL.md
├── scripts/
│   ├── main.py
│   └── .env.example
├── references/
│   └── api-docs.md
└── assets/
    └── template.json

Verify:

• SKILL.md has valid YAML frontmatter
• File paths use hyphen-case
• Scripts are executable and documented
• Total SKILL.md under 200 lines

Helper Utilities

Use the provided utility scripts in the references/ folder to streamline skill creation:

check_existing_skills.py

Check for similar existing skills before creating a new one.

Usage:

python references/check_existing_skills.py "skill-name" "description" [--model MODEL] [--ultrathink]

What it does:

• Analyzes all existing skills in .claude/skills/
• Calculates similarity scores based on metadata
• Identifies potential conflicts or overlap
• Suggests consolidation opportunities

When to use:

• ALWAYS before creating a new skill
• Part of mandatory pre-execution steps

create_skill_from_template.py

Generate a complete skill structure from template.

Usage:

python references/create_skill_from_template.py \\
  --name "skill-name" \\
  --description "One-line description" \\
  --model sonnet \\
  [--ultrathink]

What it does:

• Creates skill directory with SKILL.md
• Generates proper YAML frontmatter
• Creates references/, scripts/, assets/ directories
• Auto-normalizes names to hyphen-case

When to use:

• After verifying no conflicts with existing skills
• To bootstrap new skill structure quickly

skill_template.md

Template file for SKILL.md with placeholder variables.

Template variables:

• {{SKILL_NAME}} - Hyphen-case skill name
• {{ONE_LINE_DESCRIPTION}} - Brief description
• {{haiku|sonnet|opus}} - Choose execution model
• {{true|false}} - Ultrathink flag
• Plus content sections for workflow, best practices, etc.

When to use:

• Automatically used by create_skill_from_template.py
• Can be used manually for custom skill structures

Progressive Disclosure

Three loading levels:

1. Metadata (always loaded): frontmatter only
2. Instructions (when skill invoked): SKILL.md body
3. Resources (as needed): scripts/references/assets

Keep SKILL.md concise; move detailed content to references.

Best Practices

Combine Related Skills:

• Group by domain (e.g., docker + kubernetes → devops)
• Share common references/scripts
• Reduce metadata overhead

Optimize for AI Parsing:

• Clear section headers
• Numbered steps for workflows
• Code blocks with language tags
• Explicit tool names and parameters

Testing Iteration:

1. Create minimal viable skill
2. Test with real use cases
3. Refactor based on failures
4. Update documentation
5. Repeat

Output Format

Provide user with:

1. Proposed model configuration with reasoning
2. Complete skill file structure ready to write
3. SKILL.md content following all specifications
4. Optional bundled resources with full code
5. Testing suggestions for validation
6. Reminder to use utility scripts:
   • python references/check_existing_skills.py before starting
   • python references/create_skill_from_template.py for structure

Example Invocation Analysis

User: "Create a skill for PostgreSQL database migrations"

Analysis:

• Complexity: Medium (multi-step workflow, error handling)
• Proposed model: sonnet
• Tools needed: Bash for psql commands, file operations
• Resources: migration template scripts, SQL references

Proposed frontmatter:

---
name: postgres-migrations
description: Manage PostgreSQL schema migrations with version control and rollback support
execution_model: sonnet
ultrathink: false
---

Present complete structure before writing files.