Skill Builder

Skill Builder

Generate complete Claude Code skills through requirements gathering, pattern selection, and template-based generation.

Principle: Most skills should be pure SKILL.md. Python only when it adds clear value.

Arguments

Parse from $ARGUMENTS:

• skill-name: Required — Name for the new skill (kebab-case)
• --type: Optional — Hint skill type (research, automation, tool, simple)

Workflow

Phase 1: Parse Request

Extract:

• Skill name from arguments
• Type hint if provided
• Any description in user message

If no skill name provided, ask user.

Phase 2: Detect Skill Type

Analyze user's description to determine type:

Default: simple (avoid over-engineering)

Phase 3: Gather Requirements

Load questions from questions/:

• base-questions.md — Always ask (3-4 questions)
• {type}-questions.md — Type-specific (2-3 questions)

Ask 5-7 total questions via AskUserQuestion tool.

Question categories:

1. Purpose and trigger ("When would you use this?")
2. Inputs ("What information do you provide?")
3. Outputs ("What should it produce?")
4. Sources/data ("Where does data come from?")
5. Quality criteria ("How do you know it's good?")

Store answers for template customization.

Phase 4: Assess Python Need

Python warranted ONLY if:

• External API calls (not web search)
• Complex computation Claude can't do
• Binary/structured format parsing
• Rate limiting or pagination logic

Ask explicitly if unclear:

"This skill involves [X]. Would you benefit from a Python script for [specific task], or should Claude handle it directly?"

Default: No Python. Simpler is better.

Phase 5: Select Patterns

Based on answers, select from patterns/:

Load selected patterns for template generation.

Phase 6: Generate Skill

6a. Create directory:

.claude/skills/[skill-name]/

6b. Generate SKILL.md:

Load templates/skill-base.md, customize with:

• User's answers
• Detected type
• Selected patterns
• Concrete examples from answers

6c. Generate supporting files (if needed):

• output-template.md — If structured output required
• sources.md — If multiple data sources
• checklist.md — If complex quality requirements

6d. If Python needed:

• Create scripts/ directory
• Generate pyproject.toml from templates/pyproject-template.toml
• Generate script skeleton (user completes implementation)

Phase 7: Verify

Load checklist.md and verify:

• SKILL.md has valid YAML frontmatter
• All phases have concrete steps
• No placeholder text ("TODO", "fill in", etc.)
• Arguments documented
• Error handling defined
• Output format specified
• Python only if justified

Phase 8: Output Summary

Write all files, then show:

# Generated Skill: [name]

**Location:** .claude/skills/[name]/
**Type:** [detected-type]
**Python:** [Yes/No]

## Files Created
- SKILL.md — Main skill definition
- [other files if any]

## How to Use

/[skill-name] [example-args]

## Next Steps
- Review SKILL.md for accuracy
- [If Python] Implement script logic
- Test with example invocation

Type-Specific Generation

Research Skills

Include:

• Phase for multi-source search (WebSearch patterns)
• Phase for synthesis/deduplication
• State management for incremental runs
• Source attribution in output

Automation Skills

Include:

• State file patterns (.last-run, .processed)
• Conditional skip logic
• Incremental processing
• Cleanup/rotation for state files

Tool Skills

Include:

• Clear input/output contract
• Validation of inputs
• Structured output format
• Error handling with actionable messages

Simple Skills

Include:

• Minimal phases (2-3)
• Focused scope
• Direct execution
• No state management unless needed

Error Handling

• No skill name: Ask user for name
• Ambiguous type: Default to simple, note in output
• Unclear Python need: Ask user explicitly, default to no
• Missing questions file: Use base questions only

Quality Principles

From SKILL-GUIDELINES.md:

1. Concrete over generic — Actual commands, real examples
2. Self-contained — Complete instructions in SKILL.md
3. Minimal complexity — Simplest solution that works
4. Python only when valuable — Most skills are pure markdown