claude-code-meta-skill/README.md

---
> **Note:** This repository is published for reference. The contents below were
> auto-generated by Claude Code (Anthropic) as a deliverable in November 2025.
> The core concept — separating deterministic operations from agent reasoning —
> is sound, but my approach has since evolved. I now use
> [Pi.dev](https://pi.dev) with a more conversational prompting style, favouring
> **extensions** (in-process deterministic plugins that are ~10× faster than
> shell scripts and easier to debug) over compiled Go binaries generated by this
> skill. The lines between stored prompts, plugins, and ad-hoc instructions have
> blurred; this repo documents an earlier point in that journey.
---

# Meta Skill Generator - Deliverables

## 📦 What You're Getting

I've created a comprehensive meta-skill for Claude Code that generates other skills with intelligent separation of deterministic operations into Go scripts, exactly as you requested!

## 🎯 Core Functionality

### 1. Workflow Analysis Engine
Automatically analyzes user requirements and classifies operations as:
- **Go scripts** - Deterministic, performance-critical operations
- **Python scripts** - Library-heavy operations (pandas, ML, etc.)
- **Agent workflows** - Tasks requiring reasoning and context

### 2. Go Script Generator
Creates production-ready Go code with:
- Complete CLI framework (--help, --verbose, proper flags)
- Error handling and validation
- Progress reporting for long operations
- Best practice patterns
- Automatic build scripts
- SKILL.md integration

### 3. End-to-End Skill Creation
Interactive workflow that:
- Gathers concrete examples
- Analyzes and recommends implementation
- Generates complete skill structure
- Creates all Go scripts
- Validates and packages

## 📄 Files Included

### Main Deliverable
**[meta-skill-generator.skill](./meta-skill-generator.skill)** (43 KB)

> **What is a `.skill` file?** It's a ZIP archive containing the full skill
> source. The Python scripts, SKILL.md, and reference documents are all packaged
> inside. If you clone this repo and wonder where the source code went — it's in
> the `.skill` file. Extract it with:
> ```bash
> unzip meta-skill-generator.skill -d ./source
> ```
> This has already been done; the extracted source lives in
> [`source/meta-skill-generator/`](./source/meta-skill-generator/).

- Complete packaged skill (ZIP format) ready for Claude Code
- Source extracted to [`source/`](./source/meta-skill-generator/) for reference

### Documentation
1. **[META-SKILL-GENERATOR-GUIDE.md](computer:///mnt/user-data/outputs/META-SKILL-GENERATOR-GUIDE.md)** - Complete user guide
   - How to use the skill
   - Examples and patterns
   - Troubleshooting

2. **[QUICK-START-EXAMPLE.md](computer:///mnt/user-data/outputs/QUICK-START-EXAMPLE.md)** - Step-by-step walkthrough
   - Creating a PDF tools skill from scratch
   - Shows the interactive workflow
   - Example generated code

3. **[SUMMARY.md](computer:///mnt/user-data/outputs/SUMMARY.md)** - Technical overview
   - Architecture decisions
   - File statistics
   - Design rationale

## 🚀 Quick Start

### Install the Skill
```bash
# Copy meta-skill-generator.skill to your Claude Code skills directory
# The skill will be available for use immediately
```

### Create Your First Skill
```bash
# Interactive mode (recommended)
scripts/init_skill_with_analysis.py my-skill --path ./skills

# Or generate individual Go scripts
scripts/generate_go_script.py \
  --name operation-name \
  --description "What it does" \
  --input "Input description" \
  --output "Output description" \
  --logic "Transformation logic" \
  --skill-path ./my-skill
```

### Analyze Requirements
```bash
# Analyze what should be scripts vs workflows
scripts/analyze_workflow.py --examples requirements.txt
```

## 💎 Key Features

### Smart Classification
Uses multiple signals to determine the best implementation:
- **Keyword analysis** - Identifies deterministic vs dynamic operations
- **Performance indicators** - Detects batch/parallel/large-file operations
- **Library requirements** - Identifies when Python is needed
- **Context sensitivity** - Recognizes when agent reasoning is required

### Production-Ready Templates
Generated Go scripts include:
- ✅ Proper CLI argument parsing
- ✅ Input validation before processing
- ✅ Descriptive error messages
- ✅ Progress indicators for long operations
- ✅ Verbose mode for debugging
- ✅ Proper exit codes (0/1/2)
- ✅ Helper functions based on operation type
- ✅ Concurrent processing patterns where appropriate

### Comprehensive References
Included reference documentation:
- **go-patterns.md** (426 lines) - Battle-tested Go patterns
  - File processing, streaming, concurrent operations
  - Progress reporting, error handling
  - CLI design, data processing (CSV, JSON)
  
- **workflow-analysis.md** (346 lines) - Decision framework
  - When to use Go vs Python vs Agent
  - Real-world examples
  - Common patterns and anti-patterns
  
- **skill-examples.md** (426 lines) - Complete examples
  - PDF Tools, Data Processor, Image Tools
  - Pattern analysis across skills

## 🎨 Design Philosophy

### Based on Skill-Creator Best Practices
Follows all skill-creator guidelines:
- Progressive disclosure (metadata → SKILL.md → references)
- Appropriate degrees of freedom
- Token-efficient design
- Clear separation of concerns

### Intelligent Separation
Not everything should be scripted! The skill identifies:
- **What benefits from compilation** → Go scripts
- **What needs reasoning** → Agent workflows
- **What needs libraries** → Python scripts

### Performance Where It Matters
Go scripts for:
- Format conversions (PDF→images, CSV→JSON)
- Batch processing (1000s of files)
- Binary/low-level operations
- Stream processing of large files

## 📊 What's Inside the Skill

### Scripts (4 files, ~1,050 lines)
1. **generate_go_script.py** - Main generator with templates
2. **analyze_workflow.py** - Classification engine
3. **init_skill_with_analysis.py** - End-to-end creator
4. **test_skill_scripts.py** - Validation and testing

### SKILL.md (283 lines)
Complete documentation with:
- 6-step workflow process
- Detailed implementation guidance
- Best practices and examples

### References (3 files, ~1,200 lines)
In-depth guides covering patterns, analysis, and examples

## ✅ Quality Assurance

All components tested:
- ✅ Python syntax validation
- ✅ Executable permissions
- ✅ Script generation tested
- ✅ Skill packaging successful
- ✅ Documentation comprehensive

## 🎯 Use Cases

Perfect for:
- Creating PDF processing skills
- Building data transformation tools
- Image manipulation skills
- File conversion utilities
- Batch processing systems
- Any skill with repetitive deterministic operations

## 🔧 Technical Highlights

### Template-Based Generation
- Intelligent import inference based on operation description
- Automatic validation logic based on input type
- Helper function generation for common patterns
- Progress reporting for batch operations

### Analysis Algorithm
- Keyword-based classification (deterministic vs dynamic)
- Performance indicator detection
- Library requirement identification
- Confidence scoring for recommendations

### Integration
- Seamless integration with skill-creator
- Automatic SKILL.md updates
- Build script generation
- Package validation ready

## 📖 Example Output

When generating a Go script:

```go
package main

import (
    "flag"
    "fmt"
    "log"
    "os"
    "io"
    "path/filepath"
)

// Convert PDF pages to PNG images
// Generated by meta-skill-generator

var (
    verbose = flag.Bool("verbose", false, "Enable verbose logging")
    help    = flag.Bool("help", false, "Show this help message")
)

func main() {
    flag.Usage = usage
    flag.Parse()
    
    if *help {
        usage()
        os.Exit(0)
    }
    
    if err := validateArgs(); err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        usage()
        os.Exit(2)
    }
    
    if err := run(); err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        os.Exit(1)
    }
}

// ... complete implementation ...
```

## 🎓 Learning Resources

The skill includes extensive documentation:
- **User Guide** - How to use each feature
- **Quick Start** - Step-by-step example
- **Go Patterns** - Reusable code patterns
- **Workflow Analysis** - Classification guidelines
- **Skill Examples** - Complete working examples

## 🚦 Next Steps

1. **Install the skill** - Copy to your skills directory
2. **Read the guide** - Start with QUICK-START-EXAMPLE.md
3. **Create a skill** - Try the interactive workflow
4. **Explore references** - Learn the patterns
5. **Iterate** - Improve based on real usage

## 💡 Key Innovation

The meta-skill doesn't just generate code—it **analyzes workflows to determine what should be deterministic scripts versus what requires agent reasoning**. This is exactly what you requested: identifying the parts that don't need interaction with the agent harness and generating efficient Go scripts for them.

## 🙏 Inspiration

Based on:
- **skill-creator** - Framework and best practices
- **Your vision** - Meta-skill with Go generation
- **Taches pattern** - Intelligent workflow analysis

## 📦 Ready to Use

Everything is packaged and ready:
- ✅ Complete skill file
- ✅ Comprehensive documentation
- ✅ Working examples
- ✅ Tested and validated

Start creating better Claude Code skills today!