Skill Creator

Skill Creator

Helps you create well-structured, modularized Claude Code skills with best practices.

When This Skill Activates

Use this skill when the user:

• Wants to create a new skill
• Asks about skill structure or organization
• Wants to improve or refactor existing skills
• Needs help with skill modularization
• Asks about skill best practices

Skill Creation Process

1. Understand Requirements

Ask the user:

• Purpose: What should this skill do?
• Activation: When should it activate?
• Tools: What tools will it need? (Read, Write, Edit, Glob, Grep, Bash, WebFetch, etc.)
• Scope: Is it project-specific or general-purpose?
• Complexity: Will it need reference files or can it be self-contained?

2. Plan the Skill Structure

Based on complexity:

Simple Skills (Self-contained):

.claude/skills/skill-name/
└── SKILL.md

Complex Skills (Modularized):

.claude/skills/skill-name/
├── SKILL.md                  # Main skill definition
├── reference-1.md           # Supporting reference
├── reference-2.md           # Additional reference
└── examples.md              # Code examples/templates

3. Create the Main SKILL.md

The main SKILL.md should include:

Front Matter (Required)

---
name: skill-name
description: Brief description of what the skill does and when to use it
allowed-tools: [Read, Write, Edit]
---

Front Matter Fields:

• name: kebab-case skill name (e.g., code-reviewer, ui-audit)
• description: 1-2 sentences describing the skill and when to use it
• allowed-tools: Array of tools the skill can use

Common Tool Combinations:

• Read-only analysis: [Read, Glob, Grep]
• Code modification: [Read, Write, Edit]
• Full access: [Read, Write, Edit, Glob, Grep, Bash]
• Web research: [Read, Glob, Grep, WebFetch]

Main Content Structure

# Skill Name

Brief description of what this skill does.

## When This Skill Activates

Use this skill when the user:
- [Specific trigger 1]
- [Specific trigger 2]
- [Specific trigger 3]

## Process/Workflow

### 1. Step One
- Instructions for first step
- What to check or do
- Expected outputs

### 2. Step Two
- Instructions for second step
- References to supporting files if needed

### 3. Output Format

How to present results to the user.

## References

Links to relevant documentation, files, or resources.

4. Create Supporting Reference Files

For complex skills, create modular reference files:

When to Modularize:

• Main SKILL.md exceeds 300-400 lines
• Contains extensive checklists or examples
• Has multiple distinct topics/categories
• Would benefit from focused reference materials

Common Reference File Types:

• Checklists: checklist.md, review-checklist.md
• Patterns: patterns.md, anti-patterns.md
• Examples: examples.md, templates.md
• Quick References: quick-ref.md, commands.md
• Guidelines: guidelines.md, standards.md

Reference File Structure:

# Reference Topic

Brief description of this reference.

## Section 1

### Subsection
- Checklist items
- Code examples
- Explanations

## Section 2

[Content organized logically]

## References
[External links if needed]

5. Link References in Main SKILL.md

In the main SKILL.md, reference supporting files:

### 2. Load Reference Materials

Before starting, familiarize yourself with these references:

- **patterns.md** - Common patterns and anti-patterns
- **examples.md** - Code examples and templates
- **checklist.md** - Comprehensive review checklist

Skill Writing Best Practices

Clear Activation Triggers

## When This Skill Activates

Use this skill when the user:
- Asks for code review or quality check
- Mentions "best practices" or "refactoring"
- Wants to improve code quality
- Requests architecture review

Actionable Instructions

// ❌ Vague
- Check the code

// ✅ Specific
- Check for force unwrapping (!)
- Verify all optionals use safe unwrapping patterns
- Flag any instances for review with line numbers

Examples and Templates

Always provide:

• ✅ Good examples (what to do)
• ❌ Bad examples (what to avoid)
• Explanations (why it matters)

### Pattern Example

#### ❌ Anti-pattern
// Bad code example
let value = optional!

#### ✅ Good pattern
// Good code example
guard let value = optional else { return }

#### Why?
Force unwrapping crashes if nil. Guard provides safe unwrapping.

Structured Output Formats

Provide clear output templates:

## Output Format

Present findings in this structure:

### ✅ Strengths
- [List strengths]

### ⚠️ Issues Found
**[Category]**
**[Priority]: [File:Line]** - [Description]
// Current code
// Suggested fix
// Reason

### 📋 Recommendations
1. High priority items
2. Medium priority items
3. Low priority items

Tool Selection

Choose appropriate tools:

Checklists

Use checklists for systematic reviews:

### Review Checklist

#### Category 1
- [ ] Check item 1
- [ ] Check item 2
- [ ] Check item 3

#### Category 2
- [ ] Check item 4
- [ ] Check item 5

Example Skills

Simple Skill Example

---
name: greeting-responder
description: Responds to user greetings with helpful information about the project
allowed-tools: [Read]
---

# Greeting Responder

Provides helpful project context when users greet Claude.

## When This Skill Activates

Use this skill when the user:
- Says "hello", "hi", or similar greetings
- Asks "what can you help with?"

## Process

1. Greet the user warmly
2. Provide brief overview of the project
3. List 3-5 common tasks you can help with
4. Invite them to ask questions

## Example Output

"Hello! I can help you with this Swift/iOS project. Here are some things I can do:

- Review code for best practices
- Help implement new features
- Debug issues
- Refactor code
- Write tests

What would you like to work on?"

Complex Skill Example

See the existing coding-best-practices or ui-review skills as examples of well-modularized complex skills.

Skill Maintenance

When to Refactor

Refactor a skill when:

• Main SKILL.md exceeds 400-500 lines
• Adding new content becomes difficult
• Multiple distinct topics exist
• Reference material is repeated
• Finding information takes too long

How to Refactor

1. Identify logical sections in the main SKILL.md 2. Extract sections into focused reference files 3. Update main SKILL.md to reference new files 4. Test the skill to ensure references work 5. Update descriptions if scope changed

File Organization

.claude/skills/skill-name/
├── SKILL.md                      # Main entry point
├── process.md                    # Detailed workflow
├── patterns/
│   ├── good-patterns.md
│   └── anti-patterns.md
├── references/
│   ├── checklist.md
│   └── examples.md
└── templates/
    └── output-template.md

Testing Your Skill

After creating a skill:

1. Verify metadata: Check front matter is valid YAML 2. Test activation: Ensure description triggers appropriately 3. Check references: Verify all referenced files exist 4. Run through workflow: Follow the process end-to-end 5. Validate output: Ensure output format is clear and useful

Common Pitfalls

❌ Avoid

• Vague activation criteria
• Missing tool permissions
• Overly complex single-file skills
• No examples or templates
• Unclear output formats
• Broken reference links

✅ Do

• Clear, specific activation triggers
• Appropriate tool selection
• Modularize complex skills
• Provide examples for everything
• Define structured output formats
• Keep references organized

Skill Naming Conventions

Name Format: kebab-case

Good Names:

• code-reviewer
• ui-audit
• test-generator
• api-analyzer

Bad Names:

• CodeReviewer (PascalCase)
• code_reviewer (snake_case)
• reviewer (too vague)
• cr (too abbreviated)

Templates

See the following reference files for templates:

• skill-template.md - Basic skill template
• complex-skill-template.md - Modularized skill template

References

• Claude Code Skills Documentation
• Existing skills in .claude/skills/ for examples
• This project's coding-best-practices and ui-review skills

Notes

• Keep skills focused on a single purpose
• Use modularization for maintainability
• Provide clear examples and templates
• Test skills after creation
• Update skills as needs evolve

Complex Skill Template

Template for creating modularized skills with supporting reference files.

When to Use This Template

Use for complex skills that:

• ✅ Have extensive checklists (50+ items)
• ✅ Cover multiple distinct topics
• ✅ Include lots of code examples
• ✅ Need comprehensive reference material
• ✅ Would exceed 400-500 lines in a single file

Recommended Structure

.claude/skills/skill-name/
├── SKILL.md                    # Main skill definition (200-300 lines)
├── checklist.md               # Comprehensive checklists
├── patterns.md                # Code patterns and anti-patterns
├── examples.md                # Extensive code examples
├── quick-ref.md               # Quick reference guide
└── guidelines.md              # Detailed guidelines

Main SKILL.md Template

---
name: skill-name
description: Brief description of what the skill does and when to use it
allowed-tools: [Read, Write, Edit, Glob, Grep]
---

# Skill Name

One-paragraph description of the skill's purpose and capabilities.

## When This Skill Activates

Use this skill when the user:
- [Specific trigger 1]
- [Specific trigger 2]
- [Specific trigger 3]
- [Additional triggers as needed]

## Review Process

### 1. Identify Scope

- How to determine what to review
- What to prioritize
- Scope clarification steps

### 2. Load Reference Materials

Before starting, familiarize yourself with these references in `.claude/skills/skill-name/`:

- **patterns.md** - Common patterns and anti-patterns
- **checklist.md** - Comprehensive review checklist
- **examples.md** - Code examples and templates
- **quick-ref.md** - Quick reference for common issues
- **guidelines.md** - Detailed guidelines and standards

### 3. Review Categories

Apply these review categories:

**Category 1:**
- High-level checks
- What to look for
- Key considerations

**Category 2:**
- Another set of checks
- Related concerns
- Important patterns

**Category 3:**
- Additional checks
- Special cases
- Edge cases

### 4. Output Format

Present findings in this structure:

#### ✅ Strengths Found
- [List well-implemented patterns]
- [Highlight good practices]

#### ⚠️ Issues Found

**Category: [Category Name]**

**[Priority]: [File:Line]** - [Description]

// Current code [problematic code]

// Suggested fix [improved code]

// Reason: [explanation]

#### 📊 Quality Score

**Overall: X/10**

- Category 1: X/10
- Category 2: X/10
- Category 3: X/10

#### 📋 Recommendations

1. **High Priority**: [Critical issues]
2. **Medium Priority**: [Improvements]
3. **Low Priority**: [Nice-to-haves]

#### 🔧 Quick Wins

List 3-5 easy fixes that provide immediate value

## Quick Reference Checklist

Brief, high-level checklist for quick validation:

### Essential Checks
- [ ] Critical item 1
- [ ] Critical item 2
- [ ] Critical item 3

(Full checklist available in checklist.md)

## Tips for Effective Reviews

### Be Constructive
- Provide examples
- Explain reasoning
- Be educational

### Consider Context
- Some patterns have valid uses
- Balance idealism with pragmatism
- Consider project constraints

### Prioritize Impact
- Correctness first
- Performance second
- Style last

## References

- [External documentation link]
- [Related resource link]
- Supporting files in this skill directory

## Notes

- Important considerations
- Known limitations
- Future enhancements

patterns.md Template

# Patterns and Anti-Patterns

Common patterns and anti-patterns for [skill topic].

## Category 1

### Anti-patterns

// ❌ Bad - [Why it's bad] [problematic code example]

// ❌ Bad - [Another reason] [another bad example]

### Good Patterns

// ✅ Good - [Why it's good] [good code example]

// ✅ Good - [Another good pattern] [another good example]

### When to Use

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

### When to Avoid

- [Scenario where pattern doesn't apply]
- [Edge case to watch for]

## Category 2

[Repeat structure for each category]

## Pattern Comparison Table

| Pattern | Use When | Avoid When | Complexity |
|---------|----------|------------|------------|
| Pattern A | [Use case] | [Avoid case] | Low |
| Pattern B | [Use case] | [Avoid case] | Medium |
| Pattern C | [Use case] | [Avoid case] | High |

## References

- [Pattern documentation]
- [Best practices guide]

checklist.md Template

# Comprehensive Checklist

Detailed checklist for [skill topic] review.

## Category 1

### Subcategory 1.1
- [ ] Check item 1
- [ ] Check item 2
- [ ] Check item 3

### Subcategory 1.2
- [ ] Check item 4
- [ ] Check item 5
- [ ] Check item 6

## Category 2

### Subcategory 2.1
- [ ] Check item 7
- [ ] Check item 8
- [ ] Check item 9

### Subcategory 2.2
- [ ] Check item 10
- [ ] Check item 11
- [ ] Check item 12

## Category 3

[Continue with additional categories]

## Priority Matrix

| Priority | Category | Items |
|----------|----------|-------|
| High | [Category] | [Item numbers] |
| Medium | [Category] | [Item numbers] |
| Low | [Category] | [Item numbers] |

## Quick Check

Essential items to always verify:
- [ ] Critical item 1
- [ ] Critical item 2
- [ ] Critical item 3

examples.md Template

# Code Examples and Templates

Comprehensive examples for [skill topic].

## Example 1: [Scenario Name]

### Description
What this example demonstrates and when to use it.

### Before (Anti-pattern)

// ❌ Problematic code [bad code example]

**Problems:**
- [Issue 1]
- [Issue 2]
- [Issue 3]

### After (Good Pattern)

// ✅ Improved code [good code example]

**Improvements:**
- [Improvement 1]
- [Improvement 2]
- [Improvement 3]

### Why It Matters
[Explanation of impact and benefits]

## Example 2: [Another Scenario]

[Repeat structure]

## Templates

### Template 1: [Template Name]

// Template for [purpose] [code template with placeholders]

**Usage:**
1. Replace [placeholder1] with [description]
2. Replace [placeholder2] with [description]
3. [Additional steps]

### Template 2: [Another Template]

[Repeat structure]

## Real-World Examples

### Example from [Project/Context]

[Complete, realistic example with full context]

[full code example]

**Analysis:**
- [What's good]
- [What could be improved]
- [Lessons learned]

quick-ref.md Template

# Quick Reference

Fast lookup guide for common [skill topic] issues and solutions.

## Common Issues

### Issue 1: [Issue Name]

**Problem:**

[problematic code]

**Solution:**

[fixed code]

**Quick Fix:** [One-line explanation]

### Issue 2: [Another Issue]

[Repeat structure]

## Common Patterns

### Pattern 1: [Pattern Name]

**When:** [When to use]

**Code:**

[pattern code]

**Note:** [Important consideration]

## Command Reference

| Command/Syntax | Description | Example |
|----------------|-------------|---------|
| [Syntax 1] | [What it does] | `[example]` |
| [Syntax 2] | [What it does] | `[example]` |

## Keyboard Shortcuts

| Action | Shortcut | Notes |
|--------|----------|-------|
| [Action 1] | [Keys] | [When to use] |
| [Action 2] | [Keys] | [When to use] |

## Decision Trees

### When to use Pattern A vs Pattern B

Start ├─ Need [Feature X]? │ ├─ Yes → Use Pattern A │ └─ No → Continue └─ Need [Feature Y]? ├─ Yes → Use Pattern B └─ No → Use default

## Resources

- [Quick link 1]
- [Quick link 2]

guidelines.md Template

# Detailed Guidelines

Comprehensive guidelines for [skill topic].

## Philosophy

Core principles behind these guidelines:
1. [Principle 1]
2. [Principle 2]
3. [Principle 3]

## Category 1: [Category Name]

### Overview
What this category covers and why it matters.

### Guidelines

#### Guideline 1.1: [Guideline Name]

**Description:**
Detailed explanation of the guideline.

**Rationale:**
Why this guideline exists and what problems it solves.

**Examples:**

// ❌ Violates guideline [bad example]

// ✅ Follows guideline [good example]

**Exceptions:**
- [Scenario where exception is valid]
- [Another valid exception]

#### Guideline 1.2: [Another Guideline]

[Repeat structure]

## Category 2: [Another Category]

[Repeat structure]

## Best Practices Summary

### Must Do (Critical)
- [Critical practice 1]
- [Critical practice 2]

### Should Do (Recommended)
- [Recommended practice 1]
- [Recommended practice 2]

### Could Do (Optional)
- [Optional practice 1]
- [Optional practice 2]

## Anti-Patterns to Avoid

### Anti-Pattern 1: [Name]

**Description:** [What it is]

**Why Avoid:** [Problems it causes]

**Better Approach:** [What to do instead]

## Decision Guidelines

### When to Choose Option A
- [Criterion 1]
- [Criterion 2]

### When to Choose Option B
- [Criterion 1]
- [Criterion 2]

## References

- [Authoritative source 1]
- [Best practices documentation]
- [Style guide reference]

Modularization Strategy

Step 1: Identify Topics

Break down your skill into logical topics:

• Core concepts
• Patterns and practices
• Examples and templates
• Reference materials
• Guidelines and standards

Step 2: Assign Files

Map topics to files:

• Main logic → SKILL.md
• Comprehensive lists → checklist.md
• Code patterns → patterns.md
• Examples → examples.md
• Quick lookup → quick-ref.md
• Detailed rules → guidelines.md

Step 3: Cross-Reference

In SKILL.md, reference supporting files:

### 2. Load Reference Materials

Before starting, read:
- **patterns.md** - [Brief description]
- **checklist.md** - [Brief description]

Step 4: Keep SKILL.md Lean

Main SKILL.md should be:

• 200-300 lines ideally
• High-level process and workflow
• References to detailed materials
• Essential checklists only
• Output format definition

File Size Guidelines

Testing Your Complex Skill

1. Verify structure: All referenced files exist 2. Check links: References are accurate 3. Test workflow: Follow process end-to-end 4. Validate output: Output format works as expected 5. Review modularization: Information is well-organized

Example: Existing Complex Skills

See these skills for reference:

• coding-best-practices - Well-modularized code review skill
• ui-review - UI/accessibility review with references

Tips

• Start with basic template, modularize when needed
• Keep each file focused on one topic
• Use consistent formatting across files
• Cross-reference related information
• Update all files when changing structure
• Test after major refactoring

References

• [Claude Code Skills Documentation]
• Example skills in .claude/skills/

Basic Skill Template

Template for creating simple, self-contained skills.

Template Structure

---
name: skill-name
description: Brief description of what the skill does and when to use it. Keep it to 1-2 sentences that clearly explain the purpose.
allowed-tools: [Read, Write, Edit]
---

# Skill Name

One-paragraph description of what this skill does and its primary purpose.

## When This Skill Activates

Use this skill when the user:
- [Specific trigger phrase or action 1]
- [Specific trigger phrase or action 2]
- [Specific trigger phrase or action 3]
- [Additional triggers as needed]

## Process

### 1. [First Step Name]

- Clear instruction about what to do first
- What to check or verify
- Expected outcomes or decisions

### 2. [Second Step Name]

- Instructions for the second step
- What data to gather or analyze
- How to process the information

### 3. [Third Step Name]

- Instructions for the third step
- How to synthesize findings
- What to prepare for output

### 4. Output Format

How to present results to the user:

#### [Section 1 Name]
- Format for first section
- What information to include

#### [Section 2 Name]
- Format for second section
- Structure and content

#### [Section 3 Name]
- Format for third section
- Final recommendations or next steps

## Checklist

Use this checklist to ensure completeness:

### [Category 1]
- [ ] Check item 1
- [ ] Check item 2
- [ ] Check item 3

### [Category 2]
- [ ] Check item 4
- [ ] Check item 5
- [ ] Check item 6

## Examples

### Example 1: [Scenario Name]

**Input:**

[Example input or code]

**Expected Output:**

[Example output format]

### Example 2: [Another Scenario]

**Input:**

[Another example]

**Expected Output:**

[Corresponding output]

## Tips

- [Helpful tip 1]
- [Helpful tip 2]
- [Best practice 1]
- [Best practice 2]

## References

- [Link to relevant documentation]
- [Link to related resources]
- [Internal file references if any]

## Notes

- Additional context or considerations
- Edge cases to be aware of
- Limitations of the skill

Fill-In Guide

When using this template:

name

Use kebab-case (lowercase with hyphens):

• ✅ code-reviewer
• ✅ test-generator
• ❌ CodeReviewer
• ❌ code_reviewer

description

Keep it concise (1-2 sentences):

• Start with what the skill does
• End with when to use it
• Example: "Reviews Swift/iOS code for best practices and common issues. Use when performing code quality checks or refactoring."

allowed-tools

Choose appropriate tools:

• Read-only: [Read, Glob, Grep]
• Code changes: [Read, Write, Edit]
• Full access: [Read, Write, Edit, Glob, Grep, Bash]
• Web research: [Read, WebFetch]

When This Skill Activates

List specific phrases or situations:

• User says "review my code"
• User mentions "best practices"
• User asks "how can I improve this?"

Process Steps

Break down the workflow: 1. What to do first 2. What to do second 3. How to synthesize 4. How to output

Checklist

Create actionable items:

• Each item should be verifiable
• Group related items
• Use clear, specific language

Examples

Provide concrete examples:

• Show input and output
• Use realistic scenarios
• Cover common use cases

When to Use This Template

Use the basic skill template when:

• ✅ Skill has a single, focused purpose
• ✅ Process can be described in <400 lines
• ✅ No extensive reference material needed
• ✅ Examples fit within the main file
• ✅ Checklist is concise

Don't use when:

• ❌ Skill needs extensive checklists (>50 items)
• ❌ Multiple distinct topics/categories
• ❌ Lots of code examples
• ❌ Complex reference material

For complex skills, use the complex-skill-template.md instead.

Example Usage

Here's a filled-out example:

---
name: function-documenter
description: Generates comprehensive documentation for Swift functions including parameter descriptions, return values, and usage examples. Use when documenting code or improving API documentation.
allowed-tools: [Read, Write, Edit]
---

# Function Documenter

Automatically generates comprehensive documentation for Swift functions.

## When This Skill Activates

Use this skill when the user:
- Asks to "document this function"
- Mentions "add documentation"
- Requests "generate docs for this code"
- Wants to improve API documentation

## Process

### 1. Analyze Function Signature

- Read the function signature
- Identify all parameters and their types
- Determine return type
- Note any throws/async keywords

### 2. Understand Functionality

- Read function implementation
- Identify the primary purpose
- Note any side effects
- Understand error conditions

### 3. Generate Documentation

- Write clear summary line
- Document each parameter
- Describe return value
- Note any errors thrown
- Add usage example

### 4. Output Format

Generate documentation in this format:

/// [One-line summary of what the function does] /// /// [Detailed description if needed] /// /// - Parameters: /// - parameter1: Description of parameter1 /// - parameter2: Description of parameter2 /// - Returns: Description of what is returned /// - Throws: Description of errors that can be thrown /// /// Example: /// ``swift /// let result = functionName(parameter1: value1, parameter2: value2) /// `` func functionName(parameter1: Type1, parameter2: Type2) throws -> ReturnType { // implementation }

## Checklist

### Documentation Completeness
- [ ] One-line summary present
- [ ] All parameters documented
- [ ] Return value described
- [ ] Errors documented (if throws)
- [ ] Usage example provided

### Quality Checks
- [ ] Summary is clear and concise
- [ ] Parameter descriptions explain purpose, not just type
- [ ] Example is runnable and realistic
- [ ] Documentation uses proper markdown formatting

## Example

### Input Function

func calculateTotal(items: [Item], discount: Double) throws -> Double { guard !items.isEmpty else { throw CalculationError.emptyCart } let subtotal = items.reduce(0) { $0 + $1.price } return subtotal * (1 - discount) }

### Generated Documentation

/// Calculates the total cost of items after applying a discount. /// /// Sums up the prices of all items and applies the discount percentage /// to calculate the final total. /// /// - Parameters: /// - items: The items to calculate the total for. Must not be empty. /// - discount: The discount to apply, as a decimal (e.g., 0.1 for 10%) /// - Returns: The total cost after discount /// - Throws: CalculationError.emptyCart if items array is empty /// /// Example: /// ``swift /// let items = [Item(price: 10.0), Item(price: 20.0)] /// let total = try calculateTotal(items: items, discount: 0.1) /// // total = 27.0 (30.0 - 10%) /// `` func calculateTotal(items: [Item], discount: Double) throws -> Double { guard !items.isEmpty else { throw CalculationError.emptyCart } let subtotal = items.reduce(0) { $0 + $1.price } return subtotal * (1 - discount) }

## Tips

- Keep summary line under 80 characters
- Use imperative mood ("Calculates..." not "This calculates...")
- Provide meaningful examples, not just syntax
- Document what, not how (implementation is visible)

## References

- [Swift Documentation Markup](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/)

## Notes

- For complex functions, break down the description into sections
- Include edge cases in examples
- Update documentation when function signature changes