create-skill

Interactive wizard for creating new agent skills. This command follows the skill-manager workflow to guide users through creating effective, well-structured skills with all necessary components (SKILL.md, scripts, references, and assets).

Arguments

• •name (string, required): Name of the skill to create
  • •Validation: Must match pattern: ^[a-z][a-z0-9-]*$
  • •Example: pdf-editor, big-query, frontend-app-builder

Workflow

This command follows a structured creation flow with validation at each step:

Phase 1: Initialization and Validation

1. •Validate skill name format (lowercase-with-hyphens)
2. •Check if skill already exists in .claude/skills/ or ~/.claude/skills/
3. •If exists, ask user whether to overwrite or choose different name
4. •Validation checkpoint: Confirm skill name and proceed

Phase 2: Understanding the Skill

This phase follows skill-manager Step 1: Understanding the Skill with Concrete Examples

1. •Ask: "What functionality should this skill support?"
2. •Ask: "Can you give concrete examples of how this skill will be used?"
3. •Ask: "What would a user say that should trigger this skill?"
4. •Summarize understanding of skill purpose and use cases
5. •Validation checkpoint: Confirm understanding is correct

Phase 3: Planning Reusable Content

This phase follows skill-manager Step 2: Planning the Reusable Skill Contents

1. •Analyze examples to identify needed resources:
   • •Scripts: Reusable automation code (e.g., rotate-pdf.sh)
   • •References: Documentation, schemas, specifications (e.g., schema.md)
   • •Assets: Templates, boilerplate files, sample data (e.g., hello-world/)
2. •Present recommended skill structure based on analysis
3. •Ask user if additional scripts/references/assets should be included
4. •Validation checkpoint: Approve skill structure plan

Phase 4: Creating Skill Description

Critical step for proper skill activation

1. •Generate initial description following these rules:
   • •Start with "Use when..."
   • •Focus on triggering conditions only (NOT workflow)
   • •Include concrete symptoms and situations
   • •Use keywords for searchability
   • •Technology-agnostic unless skill is tech-specific
2. •Present generated description for review
3. •Validation checkpoint: Approve description text

Phase 5: Determining Save Location

1. •Ask whether to save as project-local or global skill:
   • •Project-local: .claude/skills/[skill-name]/
   • •Global: ~/.claude/skills/[skill-name]/
2. •Create directory structure at chosen location
3. •Validation checkpoint: Confirm save location

Phase 6: Generating Skill Files

This phase follows skill-manager Step 3 & 4: Initializing and Editing the Skill

1. •Create SKILL.md with:
   • •YAML front matter (name, description, metadata)
   • •"When to Activate This Skill" section
   • •"When NOT to Use This Skill" section
   • •"How to Use" section with workflow steps
   • •"Examples" section with concrete use cases
   • •"Important Notes" section
2. •Create subdirectories as needed:
   • •scripts/ (if scripts identified in Phase 3)
   • •references/ (if references identified in Phase 3)
   • •assets/ (if assets identified in Phase 3)
3. •For each subdirectory, create placeholder README.md explaining purpose
4. •Save all files to chosen location

Phase 7: Completion and Next Steps

1. •Display success message with skill location
2. •Show statistics (files created, directories, size)
3. •Offer to:
   • •Add example scripts immediately
   • •Add reference documentation immediately
   • •Test the skill with a sample query
   • •Create related command that uses this skill

Statistics Reporting

Output includes:

• •Skill name and location (project-local vs global)
• •Files created (SKILL.md, README files, etc.)
• •Directories created (scripts/, references/, assets/)
• •Description length and keyword count
• •Validation checkpoints passed
• •Total creation time

Example:

Created skill: pdf-editor
Location: ~/.claude/skills/pdf-editor/ (global)

Skill structure:
- SKILL.md (1.2 KB)
- scripts/ (1 file: rotate-pdf.sh)
- references/ (1 file: README.md)
- Description: 45 words, 8 keywords

Validation checkpoints: 5/5 passed
Created in 3m 15s

Example with assets:

Created skill: frontend-app-builder
Location: .claude/skills/frontend-app-builder/ (project)

Skill structure:
- SKILL.md (2.1 KB)
- assets/hello-world/ (12 files)
- references/ (2 files: README.md, best-practices.md)
- Description: 38 words, 6 keywords

Validation checkpoints: 5/5 passed
Created in 5m 42s

Examples

# Interactive mode - guided through all steps
create:skill pdf-editor

# Create a domain-specific skill
create:skill big-query

# Create a workflow skill
create:skill test-driven-development

# Create a file processing skill
create:skill image-optimizer

Validation Checkpoints

This command implements 5 validation checkpoints:

1. •Skill Name Validation: User confirms skill name and handles conflicts
2. •Purpose Understanding: User confirms skill purpose is correctly understood
3. •Structure Approval: User approves planned scripts/references/assets
4. •Description Validation: User approves generated description text
5. •Location Confirmation: User confirms save location (project vs global)

At each checkpoint, user can:

• •Approve and continue
• •Request modifications
• •Go back to previous step
• •Cancel skill creation

Interactive Question Flow

The command asks structured questions throughout the process:

Purpose Questions (Phase 2)

• •"What functionality should this skill support?"
• •"Can you give concrete examples of how this skill will be used?"
• •"What would a user say that should trigger this skill?"

Structure Questions (Phase 3)

• •"Based on your examples, I recommend including [list]. Does this look correct?"
• •"Should any additional scripts be included?"
• •"Should any additional references be included?"
• •"Should any additional assets be included?"

Description Review (Phase 4)

• •"Here's the generated description: [description]. Does this accurately describe when to use this skill?"
• •"Are there additional keywords or triggers to include?"

Location Questions (Phase 5)

• •"Should this skill be saved as project-local (.claude/skills/) or global (~/.claude/skills/)?"

Best Practices

This command enforces best practices:

Skill Naming:

• •Validates lowercase-with-hyphens format
• •Rejects generic names (process, handle, helper)
• •Suggests improvements for unclear names

Description Quality:

• •Enforces "Use when..." format
• •Prevents workflow summarization in description
• •Validates keyword coverage for searchability
• •Ensures concrete triggering conditions included

Structure Planning:

• •Recommends scripts for repeated code patterns
• •Recommends references for schemas and documentation
• •Recommends assets for boilerplate and templates
• •Warns against over-structuring simple skills

Documentation Completeness:

• •Requires "When to Activate" section
• •Requires "When NOT to Use" section
• •Requires concrete examples
• •Validates workflow clarity

Error Handling

The command handles common errors:

Invalid Skill Name:

Error: Skill name "PDFEditor" invalid
- Must be lowercase with hyphens
- Example: pdf-editor

Skill Already Exists:

Warning: Skill "pdf-editor" already exists in ~/.claude/skills/
Options:
1. Overwrite existing skill
2. Choose a different name
3. Cancel

Missing Required Information:

Error: Cannot generate skill description
- Missing: concrete usage examples
- Please provide examples of how this skill would be used

Invalid Save Location:

Error: Cannot create directory ~/.claude/skills/pdf-editor/
- Directory ~/.claude/ does not exist
- Create global skills directory first: mkdir -p ~/.claude/skills/

Integration with skill-manager Skill

This command is built on the skill-manager skill and follows its workflow:

1. •Phase 2 implements skill-manager Step 1: Understanding with Concrete Examples
2. •Phase 3 implements skill-manager Step 2: Planning Reusable Contents
3. •Phase 6 implements skill-manager Steps 3 & 4: Initializing and Editing

The key enhancement is the interactive, checkpoint-based flow that ensures:

• •No missing information
• •User approval at critical decision points
• •Consistent skill quality
• •Proper description format (triggers only, no workflow)
• •Appropriate resource planning (scripts/references/assets)

Notes

• •Skills are saved as directories with SKILL.md as the main file
• •YAML front matter in SKILL.md includes: name, description, metadata (author, version)
• •Directory structure follows AgentSkills.io specification
• •Description field is CRITICAL for skill activation - follows strict format
• •Skills can be tested immediately after creation
• •Use skill-manager skill directly for more complex skill creation scenarios