skill-creator

name	skill-creator
description	Create new Claude Code skills with proper structure and documentation. Use when the user asks to create, design, or build a new skill, or needs help structuring skill files.

Skill Creator

This skill helps you create new Claude Code skills following Anthropic's latest best practices and documentation standards.

When to Use This Skill

Use this skill when the user requests:

• Creating a new skill
• Designing a custom skill
• Building a skill template
• Understanding skill structure
• Setting up a skill with proper documentation

Instructions

Step 1: Gather Requirements

Ask the user clarifying questions using the AskUserQuestion tool:

1. Skill purpose: What should this skill do? What problem does it solve?
2. Skill type: Should this be a personal skill (~/.claude/skills/) or project skill (.claude/skills/)?
3. Skill name: What should the skill be called? (lowercase, hyphens only, e.g., "pdf-analyzer")
4. Tool restrictions: Should the skill have restricted tool access (read-only, specific tools)?
5. Supporting files: Will the skill need scripts, templates, or reference documentation?

Step 2: Determine Skill Scope

Following Anthropic's best practice to "Keep Skills Focused":

• Each skill should address a single capability
• Avoid broad, multi-purpose skills
• If the user describes multiple capabilities, suggest splitting into separate skills

Example: Instead of "document-processor" that handles PDFs AND Excel, create separate "pdf-analyzer" and "excel-analyzer" skills.

Step 3: Create Directory Structure

Based on the skill type, create the appropriate directory:

Personal Skill (only for this user):

mkdir -p ~/.claude/skills/<skill-name>

Project Skill (committed to git, shared with team):

mkdir -p .claude/skills/<skill-name>

Optional subdirectories (create only if needed):

mkdir -p ~/.claude/skills/<skill-name>/scripts
mkdir -p ~/.claude/skills/<skill-name>/templates

Step 4: Write SKILL.md with Proper Frontmatter

Create the SKILL.md file with this structure:

---
name: skill-name
description: Specific description including what the skill does, when to use it, and keywords/file types involved
allowed-tools: Read, Write, Grep, Glob, Bash  # Optional: only include if restricting tools
---

# Skill Name

Brief introduction to what this skill accomplishes.

## When to Use This Skill

Use this skill when the user requests:
- Specific trigger phrase or scenario 1
- Specific trigger phrase or scenario 2
- File type or format handling (e.g., "working with .xlsx files")

## Instructions

### Basic Usage

1. **Step 1**: First action to take
2. **Step 2**: Second action
3. **Step 3**: Final action

### Parameters (if applicable)

#### Required Parameters
- `param1`: Description of what this parameter does

#### Optional Parameters
- `param2`: Description (default: value)

## Examples

### Example 1: Basic Usage
User request: "Example user query"

Expected action: What Claude should do in response

### Example 2: Advanced Usage
User request: "More complex example"

Expected action: More detailed workflow

## Technical Details

- **Dependencies**: List any required tools or packages
- **File formats**: Supported file types
- **Limitations**: Any known constraints

## Notes

- Best practices
- Common pitfalls to avoid
- Tips for optimal usage

Step 5: Validate YAML Frontmatter

Critical validation checks:

• Opening --- must be on line 1
• Closing --- must come before Markdown content
• Use spaces, not tabs for indentation
• name: lowercase letters, numbers, hyphens only (max 64 chars)
• description: clear, specific (max 1024 chars)
• allowed-tools: comma-separated list (optional)

Step 6: Write Specific Description

The description field is critical for skill activation. Include:

Good description elements:

• Concrete examples of what the skill accomplishes
• Specific triggers or keywords users would mention
• File types or formats involved
• When to use the skill

Example of effective description:

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files or .xlsx format.

Example of weak description (avoid):

description: Helps with data

Step 7: Add Concrete Examples

Include real-world usage examples that show:

• What the user might ask
• What Claude should do in response
• Expected workflow or command execution
• Edge cases or variations

Step 8: Create Supporting Files (Optional)

If the skill requires scripts, templates, or additional reference documentation:

Scripts (TypeScript/Python/etc):

touch ~/.claude/skills/<skill-name>/scripts/<script-name>.ts

Reference documentation:

touch ~/.claude/skills/<skill-name>/REFERENCE.md

Templates:

touch ~/.claude/skills/<skill-name>/templates/<template-name>.txt

Reference these files in SKILL.md:

For advanced usage, see [REFERENCE.md](REFERENCE.md)

Step 9: Test the Skill

After creating the skill:

1. Restart Claude Code (skills are loaded at startup)
2. Test with matching queries: Ask questions that match the description
3. Verify activation: Claude should autonomously activate the skill
4. Debug if needed:
   • Run claude --debug to see loading errors
   • Check YAML syntax
   • Verify file location
   • Refine description with more specific keywords

Step 10: Document and Version

Consider adding version tracking to the skill content:

## Version History
- v1.0.0 (2025-11-20): Initial release

Examples

Example 1: Creating a Simple Read-Only Skill

User request: "Create a skill for analyzing log files"

Actions:

1. Ask clarifying questions about scope and type
2. Create directory: mkdir -p ~/.claude/skills/log-analyzer
3. Create SKILL.md with:

   ---
   name: log-analyzer
   description: Analyze application log files, extract error patterns, and generate summaries. Use when working with .log files or debugging application logs.
   allowed-tools: Read, Grep, Glob
   ---
   

4. Add instructions for reading logs, pattern matching, and summarization
5. Include examples showing different log analysis scenarios

Example 2: Creating a Skill with Scripts

User request: "Make a skill that converts images between formats"

Actions:

1. Determine project vs personal scope
2. Create structure:

   mkdir -p .claude/skills/image-converter/scripts
   

3. Create SKILL.md with detailed conversion instructions
4. Create TypeScript script at scripts/convert-image.ts
5. Include examples showing how to invoke the script:

   npx tsx .claude/skills/image-converter/scripts/convert-image.ts \
     --input source.jpg \
     --output result.png
   

Example 3: Creating a Multi-Purpose Skill (Split It!)

User request: "Create a skill for processing documents - PDFs, Word, Excel, everything"

Actions:

1. Recognize this violates "Keep Skills Focused" principle
2. Suggest splitting into separate skills:
   • pdf-processor: For PDF operations
   • excel-analyzer: For spreadsheet work
   • word-formatter: For Word documents
3. Create each skill separately with focused descriptions
4. Each skill has its own clear activation triggers

Technical Details

• Location: Personal skills in ~/.claude/skills/, project skills in .claude/skills/
• Required file: SKILL.md with YAML frontmatter
• Optional files: Supporting scripts, templates, reference docs
• Activation: Autonomous - Claude decides based on description matching
• Reload: Restart Claude Code after creating or modifying skills
• Tool restrictions: Use allowed-tools for read-only or security-sensitive skills

Best Practices from Anthropic

1. Keep Skills Focused: One capability per skill
2. Write Specific Descriptions: Include keywords, file types, and triggers
3. Document with Examples: Show concrete usage scenarios
4. Validate YAML: Ensure proper frontmatter syntax
5. Test Thoroughly: Verify activation with matching queries
6. Version Tracking: Document changes over time
7. Team Sharing: Use project skills for team collaboration

Reference Documentation

For complete official documentation, see REFERENCE.md which includes:

• Full file structure specifications
• Advanced tool access restrictions
• Testing and debugging strategies
• Sharing and distribution methods
• Plugin bundling for team distribution

For a ready-to-use template, see TEMPLATE.md.

Notes

• Skills are loaded when Claude Code starts - restart after creating/modifying
• Description quality directly impacts skill activation
• Use allowed-tools to create read-only or restricted skills
• Personal skills (~/.claude) are not committed to git
• Project skills (.claude) are committed and shared with the team
• Skills autonomously activate - no explicit invocation needed