rshankras/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:

| Task | Tools | |------|-------| | Reading code | Read, Glob, Grep | | Modifying code | Read, Write, Edit | | Running tests | Read, Bash | | Web research | WebFetch | | File operations | Read, Write, Glob |

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