claude-code-meta-skill/README.md

Note: This repository is published for reference. The contents below were auto-generated by Claude Code 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 with a more conversational prompting style, favouring extensions (in-process deterministic plugins that are faster than shell calls inside skills and easier to debug) over compiled Go binaries generated by this skill. At the moment I work in a more improvisational, conversational way with stored prompts, plugins, and ad-hoc instructions ; this repo documents an earlier point in that journey.

All text in this repository, apart from this line, have been generated conversationally with Claude Code (November 2025, the week before Opus 4.5) and Pi.dev with Deepseek v4 flash. The idea of a meta-skill some people found interesting in conversations, and I had a need to respond to a comment on LinkedIn where this would be a good explanation of something I tried, and liked. I used this to make a set of skills that let long running agents implement most of QWAN Tracker while I kept an eye on the user experience. Enjoy, Willem van den Ende.

FYI if you like Software Archeology, you can read the transcript of the Pi.dev session I needed to figure out where the sources of the agent skill had gone.

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

unzip meta-skill-generator.skill -d ./source

This has already been done; the extracted source lives in source/meta-skill-generator/.

• Complete packaged skill (ZIP format) ready for Claude Code
• Source extracted to source/ for reference

Documentation

1. META-SKILL-GENERATOR-GUIDE.md - Complete user guide

   • How to use the skill
   • Examples and patterns
   • Troubleshooting

2. 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 - Technical overview

   • Architecture decisions
   • File statistics
   • Design rationale

🚀 Quick Start

Install the Skill

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

Create Your First Skill

# 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

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

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!