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

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

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

# 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:

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:

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

Reference from SKILL.md:

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.