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) ```yaml --- name: skill-name description: Brief description of what the skill does and when to use it allowed-tools: [Read, Write, Edit] last_verified: 2026-07-16 review_by: 2027-06-22 --- ``` **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 - `last_verified`: date (YYYY-MM-DD) the content was last checked against reality — set to today when creating; bump on every material edit - `review_by`: date (YYYY-MM-DD) of the scheduled re-verification — default to ~2 weeks after the next WWDC (the natural decay event). CI requires both dates; a weekly workflow opens rollup issues when skills pass `review_by` - `os_version` (optional): the OS generation the content was verified against (e.g. `iOS 27 / macOS 27`) — add only if the skill cites OS/Swift versions **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 ```markdown # 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:** ```markdown # 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: ```markdown ### 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 ```markdown ## 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 ```markdown // ❌ 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) ```markdown ### 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: ```markdown ## 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: ```markdown ### 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 ```yaml --- 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](https://docs.claude.com/claude-code/skills) - 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