Build Claude Code Skill

# Build Claude Code Skill

Create comprehensive Claude Code Skills through elicitation-driven development

## Instructions

This command orchestrates four specialized agents to build production-ready Claude Code Skills from user requirements. Follow this structured workflow:

### Phase 1: Requirements Elicitation

**Agent**: `skill-elicitation-agent`

1. **Activate Elicitation Agent**
   - Launch the skill-elicitation-agent using the Task tool
   - Provide context: "The user wants to create a new Claude Code Skill"
   - Include any initial requirements or ideas the user has shared

2. **Elicitation Questions**
   - The agent will ask 3-5 targeted questions to understand:
     - Purpose and scope of the skill
     - Complexity and structure requirements
     - Tool permissions needed
     - Context and references
     - Success criteria

3. **Specification Creation**
   - Agent will create a comprehensive skill specification document
   - Includes: metadata, structure, instructions outline, code needs, examples, dependencies
   - Uses progressive disclosure strategy
   - Validates completeness before proceeding

4. **User Approval**
   - Present the specification to the user
   - Confirm understanding and agreement
   - Make adjustments if needed
   - Get explicit approval to proceed to generation

### Phase 2: Skill Generation

**Agent**: `skill-generator-agent`

1. **Activate Generator Agent**
   - Launch the skill-generator-agent using the Task tool
   - Pass the approved specification document
   - Specify target location (personal, project, or plugin skill)

2. **Directory Structure Creation**
   - Agent creates appropriate directory structure:
     ```
     skill-name/
     ├── SKILL.md (required)
     ├── reference.md (if needed)
     ├── examples.md (if needed)
     ├── scripts/ (if needed)
     └── templates/ (if needed)
     ```

3. **SKILL.md Generation**
   - Creates main skill file with proper frontmatter
   - Includes clear instructions and examples
   - Follows progressive disclosure principles
   - Links to supporting files

4. **Supporting Files Generation**
   - Creates reference documentation
   - Generates example files
   - Writes scripts with proper error handling
   - Creates reusable templates

5. **Dependency Documentation**
   - Documents all required packages
   - Provides installation instructions
   - Notes version requirements

6. **Quality Checks**
   - Validates YAML frontmatter
   - Checks file structure
   - Verifies code syntax
   - Tests progressive disclosure

### Phase 3: Validation and Testing

**Agent**: `skill-validator-agent`

1. **Activate Validator Agent**
   - Launch the skill-validator-agent using the Task tool
   - Provide path to generated skill
   - Request comprehensive validation

2. **YAML Validation**
   - Check frontmatter syntax
   - Verify required fields
   - Validate optional fields
   - Test YAML parsing

3. **Description Analysis**
   - Assess discoverability
   - Check trigger keywords
   - Verify clarity and completeness
   - Compare to best practices

4. **Structure Validation**
   - Verify file organization
   - Check all references
   - Test script execution
   - Validate permissions

5. **Code Testing**
   - Syntax validation
   - Security checks
   - Dependency verification
   - Error handling tests

6. **Integration Testing**
   - Test skill loading
   - Verify triggering
   - Check execution flow
   - Validate outputs

7. **Validation Report**
   - Generate comprehensive report
   - Score each category
   - List issues by severity
   - Provide actionable fixes

8. **Issue Resolution**
   - If issues found, work with generator agent to fix
   - Re-validate after fixes
   - Iterate until validation passes

### Phase 4: Documentation Enhancement

**Agent**: `skill-documenter-agent`

1. **Activate Documenter Agent**
   - Launch the skill-documenter-agent using the Task tool
   - Provide skill path and specification
   - Request comprehensive documentation

2. **SKILL.md Enhancement**
   - Refine instructions for clarity
   - Add comprehensive examples
   - Include best practices
   - Create troubleshooting section

3. **Reference Documentation**
   - Create detailed technical reference (if needed)
   - Document API and configuration
   - Provide advanced patterns
   - Include performance tuning tips

4. **Example Collection**
   - Generate beginner to advanced examples
   - Include troubleshooting examples
   - Show integration patterns
   - Provide case studies

5. **README Creation**
   - Create skill directory README (if distributing)
   - Document installation
   - Provide quick start
   - Link to full documentation

6. **Documentation Quality Check**
   - Verify clarity and completeness
   - Test all code examples
   - Check organization
   - Validate accuracy

### Phase 5: Final Delivery

1. **Generate Summary**
   - List all files created
   - Document location (personal/project/plugin)
   - Provide usage instructions
   - Include test scenarios

2. **Installation Verification**
   - Confirm skill is in correct location
   - Verify file permissions
   - Check dependencies documented
   - Test skill loading

3. **Usage Guide**
   - Explain how to trigger the skill
   - Provide example prompts
   - Show expected behavior
   - Link to documentation

4. **Next Steps**
   - Suggest testing approach
   - Recommend improvements
   - Explain maintenance
   - Note future enhancements

## Agent Coordination

### Sequential Flow
```
User Request
    ↓
skill-elicitation-agent (Requirements)
    ↓
User Approval
    ↓
skill-generator-agent (Creation)
    ↓
skill-validator-agent (Testing)
    ↓
Fixes if needed (loop back to generator)
    ↓
skill-documenter-agent (Enhancement)
    ↓
Final Delivery
```

### Agent Communication

**Between Agents**:
- Elicitation → Generator: Pass specification document
- Generator → Validator: Pass skill location and files
- Validator → Generator: Pass validation issues (if any)
- Generator → Documenter: Pass skill for enhancement
- Documenter → User: Final documentation

**With User**:
- Get approval after elicitation
- Confirm location preference (personal/project)
- Review validation results
- Approve final deliverable

## Best Practices

1. **Always Start with Elicitation**
   - Don't skip the question phase
   - Understand deeply before building
   - Get user approval on specification

2. **Use All Four Agents**
   - Each has specialized expertise
   - Complete flow ensures quality
   - Don't shortcut the process

3. **Iterate Based on Validation**
   - Fix issues immediately
   - Re-validate after changes
   - Don't proceed with failures

4. **Test Comprehensively**
   - Manual trigger testing
   - Script execution testing
   - Integration testing
   - Real-world scenario testing

5. **Document Thoroughly**
   - Clear instructions
   - Comprehensive examples
   - Troubleshooting guides
   - Best practices

## Location Options

### Personal Skills (`~/.claude/skills/`)
Use for:
- Individual workflows
- Experimental skills
- Personal preferences
- Private tools

### Project Skills (`.claude/skills/`)
Use for:
- Team-shared workflows
- Project-specific expertise
- Version-controlled skills
- Collaborative tools

### Plugin Skills (Plugin directory structure)
Use for:
- Distributable skills
- Marketplace deployment
- Public sharing
- Bundled capabilities

## Output Format

Provide the user with a comprehensive summary:

```
🎉 Skill Created Successfully!

📋 Skill: [Skill Name]
📁 Location: [path]
📝 Type: [simple/multi-file/tool-restricted/code-execution]

📄 Files Created:
✅ SKILL.md - Main skill instructions
✅ reference.md - Technical reference (if created)
✅ examples.md - Comprehensive examples (if created)
✅ scripts/[name].py - Helper scripts (if created)
✅ README.md - Installation guide (if created)

🧪 Validation: ✅ PASSED (Score: X/10)

📦 Dependencies:
[List if any, or "None"]

🎯 Usage:
Trigger this skill by saying:
- "[Example trigger 1]"
- "[Example trigger 2]"

Or explicitly: "Use [skill-name] to [task]"

✨ Test with:
[Specific test scenario]

📚 Documentation:
- See SKILL.md for instructions
- See examples.md for comprehensive examples
- See reference.md for technical details

🚀 Next Steps:
1. Test the skill with provided scenarios
2. Refine based on usage
3. Share with team (if project skill)
4. Consider adding more examples over time
```

## Troubleshooting

**Agent Not Found**: Ensure `.claude/agents/skill-builder/` exists with all agent files

**Permission Errors**: Check file permissions with `chmod +x scripts/*.py`

**YAML Errors**: Validator will catch and report these

**Agent Confusion**: Use explicit agent names: "Launch skill-elicitation-agent"

## Examples

### Example 1: Simple Instruction-Only Skill

**Request**: "Create a skill for writing conventional commit messages"

**Flow**:
1. Elicitation asks about commit style, projects, examples
2. Generates simple single-file SKILL.md
3. Validates structure and description
4. Documents with examples and best practices

### Example 2: Multi-File Skill with Scripts

**Request**: "Create a skill for PDF form filling"

**Flow**:
1. Elicitation asks about PDF types, operations, dependencies
2. Generates SKILL.md + scripts/fill_form.py + FORMS.md
3. Validates code execution and file structure
4. Documents with comprehensive examples and API reference

### Example 3: Tool-Restricted Read-Only Skill

**Request**: "Create a skill for security code analysis"

**Flow**:
1. Elicitation determines read-only requirement
2. Generates SKILL.md with allowed-tools: Read, Grep, Glob
3. Validates tool restrictions
4. Documents security patterns and analysis techniques

## Remember

- **Quality over speed** - Take time for thorough elicitation
- **User involvement** - Get approval at key stages
- **Comprehensive validation** - Test everything
- **Excellent documentation** - Make skills easy to use
- **Iterative improvement** - Skills can evolve over time

This command ensures every skill is production-ready, well-documented, and follows Claude Code best practices!