claude-code-meta-skill/source/meta-skill-generator/SKILL.md

---
name: meta-skill-generator
description: Creates Claude Code skills with intelligent separation of deterministic operations into Go scripts. Use when users want to create a new skill or improve an existing skill by identifying repetitive code patterns that should be extracted into compiled Go scripts for performance and reliability. Analyzes workflows to determine what requires agent interaction versus what can be pre-compiled into efficient Go binaries.
---

# Meta Skill Generator

## Overview

This skill generates high-quality Claude Code skills with intelligent workflow analysis. It identifies deterministic operations that don't require agent interaction and generates efficient Go scripts for them, while preserving dynamic agent-based workflows for tasks requiring reasoning and adaptation.

## Workflow

Creating a skill follows these steps:

1. **Understanding phase**: Gather concrete examples and use cases
2. **Analysis phase**: Identify deterministic vs dynamic operations
3. **Planning phase**: Design skill structure with appropriate degrees of freedom
4. **Implementation phase**: Generate Go scripts, Python utilities, and SKILL.md
5. **Testing phase**: Validate scripts and skill structure
6. **Packaging phase**: Create distributable .skill file

## Step 1: Understanding the Skill with Concrete Examples

Begin by gathering concrete examples of how the skill will be used. Ask targeted questions:

- What specific tasks should this skill handle?
- Can you provide 3-5 example user requests?
- What would trigger this skill?
- Are there existing workflows or tools this should integrate with?

**Example questions for an image-processing skill:**
- "What image operations do you need? Resizing, format conversion, filtering?"
- "Can you show me an example image and what you'd want to do with it?"
- "How would you phrase a request to use this skill?"

Conclude when you have clear use cases and triggering patterns.

## Step 2: Analyze for Deterministic vs Dynamic Operations

For each concrete example, categorize operations:

**Deterministic operations** (candidates for Go scripts):
- File format conversions (PDF → images, DOCX → text)
- Data transformations with fixed logic (CSV parsing, JSON manipulation)
- Batch operations on multiple files
- Validation checks with clear pass/fail criteria
- Template-based generation with fixed structure
- Mathematical computations
- File system operations (copying, organizing, renaming)

**Dynamic operations** (keep as agent workflows):
- Content analysis requiring understanding (sentiment, summarization)
- Decision-making based on context
- Creative generation (writing, design suggestions)
- Interactive troubleshooting
- Adapting to unexpected inputs
- Multi-step reasoning chains

**Indicators for Go script extraction:**
1. Same code pattern rewritten >3 times
2. Performance-critical operations (large files, many iterations)
3. Binary/low-level data manipulation
4. Zero decision-making required
5. Clear input/output contract

## Step 3: Plan Skill Structure

Design the skill's organization based on complexity:

**Simple skills** (1-3 operations):
- SKILL.md with direct instructions
- 1-3 Go scripts in `scripts/`
- Optional: single reference file

**Medium skills** (4-10 operations):
- SKILL.md with workflow decision tree
- Multiple Go scripts organized by function
- References for detailed documentation
- Optional: assets for templates

**Complex skills** (10+ operations):
- SKILL.md with high-level workflow
- Multiple reference files by category
- Go scripts organized in subdirectories
- Assets for templates and examples
- Consider: Go package with multiple binaries

### Degrees of Freedom

Match specificity to task fragility:

**High freedom** (natural language instructions):
```markdown
Analyze the document and identify key themes, then structure your
findings based on what you discover.
```

**Medium freedom** (parameterized scripts):
```markdown
Run: ./scripts/analyze --format=json --depth=2 input.txt
Interpret the results and determine next steps.
```

**Low freedom** (specific scripts, fixed sequence):
```markdown
1. Run: ./scripts/extract_fields input.pdf > fields.json
2. Run: ./scripts/validate_fields fields.json
3. If validation passes, run: ./scripts/fill_form fields.json template.pdf
```

## Step 4: Implementation

### Initialize the Skill

```bash
python3 /mnt/skills/examples/skill-creator/scripts/init_skill.py <skill-name> --path <output-dir>
```

### Generate Go Scripts

For each deterministic operation identified in Step 2, use `scripts/generate_go_script.py`:

```bash
scripts/generate_go_script.py \
  --name <operation-name> \
  --description "<what it does>" \
  --input "<input description>" \
  --output "<output description>" \
  --logic "<transformation logic>" \
  --skill-path <path/to/skill>
```

**Example:**
```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, 300 DPI" \
  --skill-path ./my-pdf-skill
```

The script will:
1. Generate efficient Go code with proper error handling
2. Include CLI argument parsing
3. Add progress reporting for long operations
4. Create binary in `scripts/bin/`
5. Update SKILL.md with usage instructions

### Python Utilities

For operations requiring Python libraries (data science, ML, complex APIs), create Python scripts instead. Use Go for performance-critical, low-level operations.

### Write SKILL.md

Follow the skill-creator patterns:

**Frontmatter:**
```yaml
---
name: skill-name
description: Comprehensive description including WHAT it does and WHEN to use it. Mention specific triggers: file types, keywords, task patterns.
---
```

**Body structure:**
1. Overview (1-2 sentences)
2. Workflow or Quick Start
3. Detailed sections for each major capability
4. Reference to scripts with clear usage examples
5. Troubleshooting (if applicable)

**Writing style:**
- Imperative/infinitive form ("Extract text" not "Extracts text")
- Concise - every word must justify its token cost
- Examples over explanations
- Reference bundled resources clearly

### Reference Files

Create reference files for:
- API documentation
- Complex workflows (>10 steps)
- Domain knowledge (schemas, specifications)
- Large examples (>100 lines)

Keep SKILL.md lean by moving detailed content to references:

```markdown
## Advanced Features

For form field extraction, see [references/form-fields.md](references/form-fields.md)
For batch processing patterns, see [references/batch-operations.md](references/batch-operations.md)
```

### Assets

Include files to be used in output:
- Templates (.pptx, .docx, .html)
- Images (logos, icons)
- Boilerplate code (starter projects)
- Fonts, stylesheets

## Step 5: Testing

Test each Go script:

```bash
cd scripts/bin
./script-name --help  # Verify CLI works
./script-name test-input.txt  # Test with real data
./script-name invalid-input  # Test error handling
```

Test Python scripts:

```bash
cd scripts
python3 script-name.py test-input
```

Verify SKILL.md:
- All script references are accurate
- Examples run successfully
- No broken links to references/assets

## Step 6: Package the Skill

```bash
python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py <path/to/skill>
```

This automatically validates:
- YAML frontmatter completeness
- Naming conventions
- File organization
- Script executability

Fix any validation errors and repackage.

## Go Script Best Practices

**Performance:**
- Use goroutines for parallel operations
- Stream large files instead of loading into memory
- Buffer I/O operations

**Error handling:**
- Return descriptive error messages
- Use exit codes (0=success, 1=error, 2=invalid input)
- Validate inputs before processing

**CLI design:**
- Support `--help` flag
- Use standard flags package
- Accept input from stdin or file
- Write output to stdout or file

**Logging:**
- Progress indicators for long operations
- Verbose mode for debugging (`--verbose` flag)
- Errors to stderr, output to stdout

## Resources

### scripts/
- `generate_go_script.py`: Generate Go scripts from specifications
- `test_skill_scripts.py`: Automated testing for all scripts
- `init_skill_with_analysis.py`: End-to-end skill creation with workflow analysis

### references/
- `go-patterns.md`: Common Go patterns for skill scripts
- `workflow-analysis.md`: Detailed guide for identifying deterministic operations
- `skill-examples.md`: Real-world examples of well-structured skills

Run `scripts/generate_go_script.py --help` for detailed usage.