Skill Wizard

Overview

Skill Wizard is an interactive tool that guides users through creating custom skills via conversation. Instead of manually writing SKILL.md files and organizing directories, users answer questions about their needs, and the wizard automatically generates a complete, properly-structured skill.

Key Benefits:

• No need to understand skill structure beforehand
• Automatic analysis of use cases to recommend appropriate structure
• Generates customized SKILL.md with real content (no TODOs)
• Suggests similar skills to reference
• Creates only needed resource directories (scripts/references/assets)
• Provides concrete next steps for customization

When to Use This Skill

Use the skill wizard when:

1. User wants to create a new skill but doesn't know where to start
2. User has a use case but is unsure how to structure it as a skill
3. User prefers guided creation over reading documentation
4. User wants recommendations on skill structure and resources
5. User asks "how do I create a skill" or similar questions

Don't use when:

• User explicitly wants to use the manual skill-creator tools directly
• User is just asking about what skills are or how they work (informational only)

Interactive Workflow

The wizard follows this conversational flow:

Phase 1: Gather Requirements

Ask the user these questions in a natural, conversational way:

1. Purpose: "What would you like this skill to help you with?"

   • Get a clear description of the skill's purpose
   • Example answers: "Help me analyze financial data", "Automate report generation", "Work with custom file formats"

2. Use Cases: "Can you give me 3-5 specific examples of how you'd use this skill?"

   • Collect concrete scenarios
   • Example: "Extract tables from PDF reports", "Generate monthly summary charts", "Convert data to Excel format"
   • If user gives fewer than 3, ask for more examples to ensure good recommendations

3. Triggering: "What words or phrases should trigger this skill?"

   • Understand when the skill should activate
   • Example: "When I say 'analyze sales data' or 'create sales report'"

4. Skill Name: "What should we call this skill?"

   • Suggest a name based on the use cases (hyphen-case format)
   • Example: "financial-analyzer", "report-generator", "pdf-data-extractor"
   • Must be: lowercase, hyphens only, max 40 characters

Phase 2: Analyze and Recommend

After gathering requirements, create a JSON configuration and call the wizard script:

# Create a config file with the collected information
cat > /tmp/skill-config.json <<'EOF'
{
  "name": "skill-name",
  "description": "Complete description including what it does and when to use it. Include specific triggers, file types, and scenarios.",
  "use_cases": [
    "Use case 1",
    "Use case 2",
    "Use case 3"
  ]
}
EOF

# Run the wizard
python3 ~/.claude/skills/skill-wizard/scripts/wizard.py \
  --from-json /tmp/skill-config.json \
  --output /tmp \
  --skill-creator ~/.claude/skills/skill-creator/scripts

The wizard will:

• Analyze the use cases for patterns
• Recommend skill type (workflow-based, task-based, reference-based, capabilities-based)
• Determine which resource directories are needed (scripts/references/assets)
• Suggest similar existing skills to reference
• Generate a complete, customized SKILL.md
• Create RECOMMENDATIONS.md with specific next steps

Phase 3: Review and Iterate

After the wizard creates the skill:

1. Show the user the generated structure
2. Display the recommendations
3. Ask if they want to adjust anything
4. Explain the next steps for customization

Important: The generated skill is a strong starting point but will need customization:

• Add actual script implementations
• Fill in reference documentation
• Add real assets/templates
• Test the skill in practice

Example Interaction

User: I want to create a skill to help me work with JSON data

Claude: I'd be happy to help you create a JSON data skill! Let me ask a few questions to understand your needs better.

What would you like this skill to help you with specifically? For example:
- Validate JSON files?
- Transform JSON data?
- Extract information from JSON?
- Generate JSON from other formats?

User: I want to validate JSON schemas, transform JSON structures, and generate JSON reports from our database

Claude: Great! Can you give me 3-5 specific examples of how you'd use this?

User:
1. Validate API responses against our schema definitions
2. Transform nested JSON into flat CSV format
3. Convert database query results to formatted JSON reports
4. Merge multiple JSON configuration files
5. Extract specific fields from large JSON files

Claude: Perfect! What words or phrases should trigger this skill? When should I know to use it?

User: Whenever I mention "JSON", "validate schema", "transform JSON", or "JSON report"

Claude: Excellent! Based on your use cases, I'd suggest calling this "json-toolkit". Does that work for you?

User: Yes, that's perfect!

Claude: [Creates the skill using the wizard script]

Great! I've created your json-toolkit skill. Here's what was generated:

✅ Skill structure created
✅ Customized SKILL.md (no TODOs!)
✅ Recommended as "task-based" skill (multiple operations)
✅ Created scripts/ directory (for validation/transformation scripts)
✅ Similar skills to reference: xlsx, pdf

Next steps:
1. Review the generated SKILL.md at /tmp/json-toolkit/
2. Read RECOMMENDATIONS.md for specific suggestions
3. Add your actual validation and transformation scripts
4. Test it by installing to ~/.claude/skills/
5. Package it when ready with package_skill.py

Would you like me to help you implement any of the scripts?

Tips for Best Results

1. Encourage specificity: Ask follow-up questions if use cases are vague
2. Collect enough examples: 3-5 use cases give better recommendations than 1-2
3. Clarify the domain: Understanding the domain helps suggest similar skills
4. Explain the output: Show users what was created and why
5. Offer next steps: Help users understand how to customize the generated skill

Resources

scripts/

The wizard.py script is the core of this skill. It:

• Accepts user requirements in JSON format
• Analyzes use cases using keyword detection
• Recommends skill structure and resources
• Generates customized SKILL.md files
• Creates helpful RECOMMENDATIONS.md files
• Integrates with skill-creator's init_skill.py

Usage by Claude:

python3 scripts/wizard.py \
  --from-json <config.json> \
  --output <output-path> \
  --skill-creator <path-to-skill-creator-scripts>

The wizard script is designed to be called programmatically after collecting requirements through conversation.