claude-code-meta-skill/META-SKILL-GENERATOR-GUIDE.md

# Meta Skill Generator - User Guide

## What Is This?

The Meta Skill Generator is a Claude Code skill that creates other Claude Code skills. It intelligently analyzes your requirements and separates operations into:

1. **Go scripts** - For deterministic, performance-critical operations
2. **Python scripts** - For operations requiring specialized libraries
3. **Agent workflows** - For tasks requiring reasoning and context

## Key Features

✅ **Workflow analysis** - Automatically identifies which operations should be scripts vs workflows
✅ **Go script generation** - Creates efficient, production-ready Go binaries
✅ **Best practices** - Follows skill-creator patterns and conventions
✅ **End-to-end workflow** - From requirements gathering to packaged .skill file
✅ **Comprehensive references** - Go patterns, workflow analysis, and examples

## Quick Start

### 1. Interactive Skill Creation

```bash
scripts/init_skill_with_analysis.py my-new-skill --path ./skills
```

This will guide you through:
- Gathering example use cases
- Analyzing which operations should be scripts
- Specifying Go script details
- Generating the complete skill structure

### 2. Generate Individual Go Scripts

```bash
scripts/generate_go_script.py \
  --name pdf-to-images \
  --description "Convert PDF pages to PNG images" \
  --input "PDF file path" \
  --output "Directory of PNG files" \
  --logic "Extract each page as separate image at 300 DPI" \
  --skill-path ./my-skill
```

This creates:
- Complete Go source code with error handling
- Build script for compilation
- Documentation in SKILL.md

### 3. Analyze Existing Requirements

```bash
# Save your requirements to a file
cat > requirements.txt << EOF
Extract text from PDF files
Convert CSV to JSON format
Analyze sentiment in documents
Rotate images by 90 degrees
EOF

# Run analysis
scripts/analyze_workflow.py --examples requirements.txt
```

This shows which operations should be Go scripts, Python scripts, or agent workflows.

## How It Works

### Workflow Analysis Algorithm

The analyzer looks for keywords to categorize operations:

**Deterministic keywords** → Go/Python scripts:
- convert, transform, parse, extract, validate
- format, encode, decode, compress, resize
- sort, filter, calculate, merge, split

**Dynamic keywords** → Agent workflows:
- analyze, understand, interpret, decide
- suggest, recommend, summarize, explain
- evaluate, assess, identify, classify

**Performance indicators** → Go preferred:
- large file, batch, thousands, concurrent
- parallel, binary, low-level, stream

**Library indicators** → Python preferred:
- pandas, numpy, machine learning, plot
- api client, visualization

### Go Script Template

Generated scripts include:

- **CLI parsing** with `--help` and `--verbose` flags
- **Input validation** before processing
- **Error handling** with descriptive messages
- **Progress reporting** for long operations
- **Proper exit codes** (0=success, 1=error, 2=invalid input)
- **Helper functions** based on operation type

### Skill Structure

```
my-skill/
├── SKILL.md              # Main skill documentation
├── scripts/
│   ├── script1.go        # Generated Go source
│   ├── script2.go
│   ├── build_script1.sh  # Build scripts
│   ├── build_script2.sh
│   └── bin/              # Compiled binaries
│       ├── script1
│       └── script2
├── references/           # Detailed documentation
│   └── advanced-guide.md
└── assets/               # Templates, images, etc.
    └── template.txt
```

## Examples

### Example 1: PDF Processing Skill

**Requirements:**
- Extract text from PDFs
- Convert PDFs to images
- Merge multiple PDFs
- Summarize PDF content

**Analysis Result:**
- `pdf-extract-text` → Go script (deterministic, parsing)
- `pdf-to-images` → Go script (deterministic, binary)
- `merge-pdfs` → Go script (deterministic, file ops)
- Summarize → Agent workflow (requires understanding)

### Example 2: Data Analytics Skill

**Requirements:**
- Convert CSV to JSON
- Validate data against schema
- Plot trends
- Find insights

**Analysis Result:**
- `csv-to-json` → Go script (simple conversion)
- `validate-schema` → Go script (deterministic rules)
- `plot-data` → Python script (needs matplotlib)
- Find insights → Agent workflow (interpretation)

## Best Practices

### When to Create a Skill

Create a skill when:
- ✅ You're doing the same operations repeatedly
- ✅ Operations have clear, reusable patterns
- ✅ You want consistent behavior across tasks
- ✅ Performance matters (batch processing, large files)

Don't create a skill for:
- ❌ One-off tasks
- ❌ Highly variable, context-dependent operations
- ❌ Tasks that change frequently

### Go vs Python vs Agent

**Use Go for:**
- File format conversions
- Batch processing (1000s of items)
- Binary/low-level operations
- Performance-critical paths

**Use Python for:**
- Data science (pandas, numpy)
- ML/AI tasks
- Complex API clients
- Visualization

**Use Agent workflows for:**
- Content analysis
- Creative tasks
- Decision-making
- Context-dependent branching

### Skill Design Tips

1. **Start with examples** - Gather 3-5 concrete use cases
2. **Identify patterns** - Look for repeated code or workflows
3. **Separate concerns** - Scripts for deterministic, workflows for reasoning
4. **Keep SKILL.md lean** - Move details to references
5. **Test everything** - Run scripts before packaging
6. **Document clearly** - Include examples for every operation

## Reference Documentation

### Included References

- **go-patterns.md** - Battle-tested Go patterns for common operations
  - File processing (streaming, line-by-line)
  - Concurrent processing (worker pools, rate limiting)
  - Progress reporting
  - Error handling
  - CLI patterns
  - Data processing (CSV, JSON)

- **workflow-analysis.md** - Deep dive on deterministic vs dynamic
  - Decision framework
  - Real-world examples
  - Common patterns
  - Anti-patterns to avoid

- **skill-examples.md** - Complete examples of well-designed skills
  - PDF Tools
  - Data Processor
  - Image Tools
  - Pattern analysis

## Troubleshooting

### "Go compiler not found"

Install Go: https://go.dev/doc/install

Or skip Go generation:
```bash
scripts/init_skill_with_analysis.py my-skill --path . --skip-go
```

### "Script compilation failed"

Check the error message. Common issues:
- Missing imports (add to imports in template)
- Undefined functions (implement TODOs)
- Syntax errors (review generated code)

### "Skill validation failed"

Common validation errors:
- Missing description in frontmatter
- Description too short (<50 chars)
- SKILL.md not found
- Invalid skill name (use hyphen-case)

## Advanced Usage

### Customize Go Template

Edit `generate_go_script.py` to modify:
- Template structure
- Import inference logic
- Helper function generation
- CLI flag patterns

### Add Custom Analysis Rules

Edit `analyze_workflow.py` to:
- Add domain-specific keywords
- Adjust scoring thresholds
- Create custom operation types

### Extend References

Add your own patterns:
```bash
cd my-skill/references
echo "# My Patterns" > custom-patterns.md
# Add your documentation
```

Reference from SKILL.md:
```markdown
For advanced patterns, see [references/custom-patterns.md](references/custom-patterns.md)
```

## Support

This skill follows the skill-creator guidelines. For questions about:
- Skill structure → See skill-creator SKILL.md
- Go patterns → See references/go-patterns.md
- Workflow analysis → See references/workflow-analysis.md
- Examples → See references/skill-examples.md

## License

This skill is created using the skill-creator framework and includes example patterns from the Claude Code skill ecosystem.