name	claude-skill-creator
description	Guide for creating effective Claude Code skills with proper YAML frontmatter, directory structure, and best practices. Use when creating new skills, updating existing skills, or learning about skill development.

Claude Skill Creator Guide

This guide helps you create well-structured, effective skills for Claude Code that extend capabilities with specialized knowledge, workflows, or tool integrations.

When to Use This Skill

Use this skill when:

Creating a new skill from scratch
Updating an existing skill
Learning about skill structure and best practices
Troubleshooting why a skill isn't being activated
Converting documentation into a skill format

What Are Skills?

Skills extend Claude's capabilities through organized folders containing instructions and resources. They are model-invoked—Claude autonomously decides when to use them based on request context, unlike slash commands which require explicit user activation.

Directory Structure

Skills can be stored in three locations:

Personal Skills: ~/.claude/skills/skill-name/
- Available across all projects for the user
- Perfect for personal workflows and preferences
Project Skills: .claude/skills/skill-name/
- Specific to a project, committed to git
- Shared with team members automatically
Plugin Skills: Bundled with installed plugins
- Distributed as packages

Creating a New Skill

Step 1: Create the Directory Structure

# For personal skills
mkdir -p ~/.claude/skills/my-skill-name

# For project skills
mkdir -p .claude/skills/my-skill-name

Step 2: Create SKILL.md with Required Frontmatter

Every skill MUST have a SKILL.md file with YAML frontmatter:

---
name: skill-identifier
description: Brief description of what this skill does and when to use it
---

# Skill Name

[Your skill content here]

Critical Requirements:

name:
- Lowercase letters, numbers, hyphens only
- Maximum 64 characters
- Example: comprehensive-testing, api-docs-writer, db-migration-helper
description:
- Must describe BOTH what the skill does AND when to use it
- Maximum 1024 characters
- Include trigger keywords users would mention
- Be specific, not generic

Good Description Examples:

# ✅ GOOD: Specific with clear triggers
description: Implement comprehensive tests with test design tables, equivalence partitioning, boundary value analysis, and 100% branch coverage. Use when writing tests, adding test cases, or improving test coverage for React Native/Expo TypeScript code with Jest.

# ✅ GOOD: Clear functionality and use case
description: Analyze Excel spreadsheets, generate pivot tables, create charts from CSV data. Use when working with Excel files, spreadsheet analysis, or data visualization tasks.

# ❌ BAD: Too vague
description: Helps with data processing

# ❌ BAD: Missing when to use
description: This skill handles database migrations and schema changes

Step 3: Write the Skill Content

Follow this recommended structure:

---
name: my-skill-name
description: [What it does and when to use it]
---

# Skill Title

Brief introduction explaining the skill's purpose.

## When to Use This Skill

Explicitly list scenarios:
- Use case 1
- Use case 2
- Use case 3

## Core Concepts / Philosophy

Explain the underlying principles or approach.

## Instructions

Provide clear, step-by-step guidance:

1. **Step 1**: Do this
2. **Step 2**: Then do this
3. **Step 3**: Finally do this

## Examples

Show concrete, practical examples:

### Example 1: [Scenario]

```[language]
[code or content example]

Example 2: [Another Scenario]

[code or content example]

Best Practices

Practice 1
Practice 2
Practice 3

Common Patterns

[Common use cases with templates]

Troubleshooting

Common issues and solutions:

Issue: [Problem] Solution: [How to fix]

AI Assistant Instructions

Specific guidance for Claude on how to use this skill:

When invoked, you should:

[Instruction 1]
[Instruction 2]
[Instruction 3]

Always/Never:

Always do X
Never do Y

Additional Resources

[Link to documentation]
[Link to related tools]


## Optional: Tool Restrictions

Use `allowed-tools` to limit Claude's capabilities when the skill is active:

```yaml
---
name: safe-file-reader
description: Safely read and analyze files without making modifications
allowed-tools: Read, Grep, Glob
---

This restricts Claude to only specified tools, useful for:

Read-only operations
Safety-critical workflows
Preventing accidental modifications

Optional: Supporting Files

Organize additional resources alongside SKILL.md:

my-skill-name/
├── SKILL.md              # Main skill file (required)
├── reference.md          # Additional reference documentation
├── templates/
│   ├── template1.txt
│   └── template2.txt
└── examples/
    ├── example1.ts
    └── example2.ts

Reference these files from SKILL.md:

See [reference documentation](reference.md) for more details.

Use this [template](templates/template1.txt) as a starting point.

Best Practices for Skill Creation

1. Keep Skills Focused

✅ DO: One skill = one capability

api-docs-writer: Generate API documentation
test-strategy: Implement comprehensive tests
db-migration: Handle database schema changes

❌ DON'T: Create broad, multi-purpose skills

developer-helper: Does everything (too vague)
backend-tools: Mixed unrelated capabilities

2. Write Trigger-Rich Descriptions

Include keywords users would naturally use:

# ✅ GOOD: Rich with triggers
description: Generate OpenAPI/Swagger documentation from Express routes, FastAPI endpoints, or GraphQL schemas. Use when documenting APIs, creating API specs, or working with OpenAPI, Swagger, REST, or GraphQL.

# ❌ BAD: Missing triggers
description: Helps with API documentation

3. Provide Concrete Examples

Users and Claude learn best from examples:

## Example: Creating a REST API Endpoint

```typescript
// Given this Express route
app.get('/users/:id', async (req, res) => {
  const user = await db.getUser(req.params.id);
  res.json(user);
});

// Generate this OpenAPI spec
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string


### 4. Be Explicit About Workflow

Tell Claude exactly what to do:

```markdown
## AI Assistant Instructions

When this skill is activated:

1. **First**: Analyze the codebase structure
2. **Then**: Ask clarifying questions if needed
3. **Next**: Generate the initial version
4. **Finally**: Validate and test the output

Always:
- Use TypeScript for type safety
- Include error handling
- Add JSDoc comments

Never:
- Skip validation steps
- Generate code without examples
- Assume user preferences

5. Test Your Skills

After creating a skill, test it:

Test Activation: Does it trigger with expected keywords?
Test Instructions: Does Claude follow the workflow correctly?
Test Examples: Are they clear and helpful?
Test Edge Cases: Does it handle unusual scenarios?

6. Context Window is a Shared Resource

Skills consume context tokens when activated. Write efficiently:

✅ DO:

Assume Claude's base knowledge (don't explain programming basics)
Include only task-specific context
Keep SKILL.md under 500 lines
Use reference files for extensive documentation

❌ DON'T:

Explain concepts Claude already knows
Include unnecessary background information
Create monolithic skill files

7. Test Across Different Models

Skills that work well with Claude Opus may need more detail for Haiku:

Opus: Can handle more implicit instructions
Sonnet: Good balance of capability and speed
Haiku: Needs more explicit, step-by-step guidance

Test your skill with all models you plan to support.

8. Use Progressive Disclosure for Large Skills

For complex skills with extensive documentation:

Structure:

my-skill-name/
├── SKILL.md              # Core instructions (< 500 lines)
├── reference.md          # Detailed reference (loaded on-demand)
├── examples.md           # Extended examples (loaded on-demand)
└── templates/            # Reusable templates

In SKILL.md, reference other files:

For detailed API reference, see [reference.md](reference.md).
More examples available in [examples.md](examples.md).

Claude will only load these files when needed, saving context tokens.

9. Provide Utility Scripts for Complex Tasks

Checklisted Workflows: Include ordered steps Claude can track progress through

Pre-written Scripts: For deterministic operations, provide ready-to-use scripts rather than having Claude generate them

More reliable
Saves tokens
Faster execution

Choose the Right Language:

Use Shell Scripts (.sh) for:

Simple, single-purpose operations
File handling and command chaining
Logging, notifications, quick validation
Operations with minimal logic (5 lines or less)

Use Python Scripts (.py) for:

Complex logic and conditional operations
Data processing and transformation
Cross-platform compatibility (especially if Windows users exist)
Reusable modules and libraries

Cross-Platform Considerations:

Shell scripts require WSL/Git Bash on Windows
Python offers better cross-platform support for team-shared skills
Use POSIX-compliant commands if you choose shell scripts

Example:

scripts/
├── setup.sh          # Shell: Simple environment setup
├── validate.py       # Python: Complex validation logic
├── format.py         # Python: Data transformation
└── notify.sh         # Shell: Simple notifications

Reference from SKILL.md:

Run validation: `python scripts/validate.py`
Run setup: `bash scripts/setup.sh`

Common Skill Patterns

Pattern 1: Code Generation Skill

---
name: component-generator
description: Generate React/Vue/Angular components with TypeScript, tests, and stories. Use when creating new components, scaffolding UI elements, or building component libraries.
---

# Component Generator

## Instructions

1. Ask user for component type (React/Vue/Angular)
2. Request component name and props
3. Generate:
   - Component file with TypeScript
   - Test file with comprehensive tests
   - Storybook story file
4. Follow project conventions from existing components

Pattern 2: Analysis Skill

---
name: code-complexity-analyzer
description: Analyze code complexity, identify refactoring opportunities, calculate cyclomatic complexity, and suggest improvements. Use when reviewing code, planning refactoring, or improving code quality.
---

# Code Complexity Analyzer

## Instructions

1. Scan provided code files
2. Calculate metrics:
   - Cyclomatic complexity
   - Function length
   - Nesting depth
3. Identify issues:
   - Functions > 50 lines
   - Complexity > 10
   - Deep nesting > 3 levels
4. Suggest specific refactorings

Pattern 3: Documentation Skill

---
name: readme-generator
description: Generate comprehensive README files with installation, usage, API docs, and examples. Use when creating new projects, improving documentation, or standardizing README format.
---

# README Generator

## Instructions

1. Analyze project structure and package.json
2. Generate sections:
   - Project description
   - Installation steps
   - Usage examples
   - API documentation
   - Contributing guidelines
3. Include badges for CI, coverage, license
4. Add table of contents for long READMEs

Troubleshooting

Issue: Claude Doesn't Use the Skill

Possible Causes:

Description lacks trigger keywords
- ✅ Fix: Add specific terms users would mention
- Example: Add "Jest", "testing", "test coverage" to description
Skill name has invalid characters
- ✅ Fix: Use only lowercase, numbers, hyphens
- Example: Change My_Skill_Name to my-skill-name
YAML frontmatter is malformed
- ✅ Fix: Validate YAML syntax
- Check for proper --- delimiters
- Ensure no tabs (use spaces)
File is not named SKILL.md
- ✅ Fix: Rename to SKILL.md (exact case)
Directory structure is wrong
- ✅ Fix: Ensure path is ~/.claude/skills/skill-name/SKILL.md

Issue: Skill Activates at Wrong Times

Possible Causes:

Description is too broad
- ✅ Fix: Make description more specific
- Example: Instead of "helps with files", use "analyze CSV files and generate reports"
Trigger keywords overlap with other skills
- ✅ Fix: Use more specific, unique keywords

Issue: Skill Doesn't Follow Instructions

Possible Causes:

Instructions are unclear or ambiguous
- ✅ Fix: Use numbered steps, be explicit
Examples don't match instructions
- ✅ Fix: Ensure examples demonstrate the workflow
Missing AI Assistant Instructions section
- ✅ Fix: Add explicit guidance for Claude

Sharing Skills with Teams

For Project Skills

Create skill in .claude/skills/skill-name/

Commit to git:

git add .claude/skills/skill-name/
git commit -m "feat: add [skill-name] skill"
git push

Team members get the skill automatically on git pull

For Plugin Distribution

Package skill as npm module
Include installation instructions
Document required dependencies
Provide usage examples

Quick Reference: Skill Checklist

When creating a skill, ensure:

Directory created: ~/.claude/skills/skill-name/ or .claude/skills/skill-name/
File named exactly SKILL.md
YAML frontmatter present with --- delimiters
name field: lowercase, hyphens, <64 chars
description field: describes what + when, <1024 chars
Description includes trigger keywords
Clear "When to Use This Skill" section
Step-by-step instructions provided
Concrete examples included
Best practices documented
AI Assistant Instructions added
Tested with realistic scenarios
No typos or formatting issues

Example: Complete Skill Template

---
name: example-skill
description: [What this does] and [specific use case]. Use when [trigger scenario 1], [trigger scenario 2], or [working with keyword1, keyword2].
---

# Example Skill

Brief introduction to the skill's purpose and value.

## When to Use This Skill

- Scenario 1
- Scenario 2
- Scenario 3

## Core Concepts

Explain the underlying approach or methodology.

## Instructions

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

## Examples

### Example 1: Common Use Case

```typescript
// Code example here

Example 2: Advanced Use Case

// Another example

Best Practices

Practice 1
Practice 2

Common Patterns

Pattern templates or reusable snippets.

Troubleshooting

Issue: Problem description Solution: How to resolve

AI Assistant Instructions

When this skill is activated:

Always do X
Never do Y
Follow this workflow: [steps]

Additional Resources

[Documentation link]
[Tool link]


---

## Additional Tips for Effective Skills

1. **Start Simple**: Begin with basic functionality, iterate based on usage
2. **Use Real Examples**: Draw from actual use cases, not hypothetical ones
3. **Be Specific**: Avoid vague language like "helps with" or "handles"
4. **Document Assumptions**: Clarify prerequisites, dependencies, or required knowledge
5. **Iterate Based on Feedback**: Skills improve with real-world usage—update accordingly
6. **Consider Performance**: Every token in your skill uses context window space
7. **Write for Autonomous Use**: Claude should be able to use the skill without asking clarifying questions

Install Skill

SKILL.md

Claude Skill Creator Guide

When to Use This Skill

What Are Skills?

Directory Structure

Creating a New Skill

Step 1: Create the Directory Structure

Step 2: Create SKILL.md with Required Frontmatter

Step 3: Write the Skill Content

Example 2: [Another Scenario]

Best Practices

Common Patterns

Troubleshooting

AI Assistant Instructions

Additional Resources

Optional: Supporting Files

Best Practices for Skill Creation

1. Keep Skills Focused

2. Write Trigger-Rich Descriptions

3. Provide Concrete Examples

5. Test Your Skills

6. Context Window is a Shared Resource

7. Test Across Different Models

8. Use Progressive Disclosure for Large Skills

9. Provide Utility Scripts for Complex Tasks

Common Skill Patterns

Pattern 1: Code Generation Skill

Pattern 2: Analysis Skill

Pattern 3: Documentation Skill

Troubleshooting

Issue: Claude Doesn't Use the Skill

Issue: Skill Activates at Wrong Times

Issue: Skill Doesn't Follow Instructions

Sharing Skills with Teams

For Project Skills

For Plugin Distribution

Quick Reference: Skill Checklist

Example: Complete Skill Template

Example 2: Advanced Use Case

Best Practices

Common Patterns

Troubleshooting

AI Assistant Instructions

Additional Resources