claude-code-meta-skill/QUICK-START-EXAMPLE.md

# Quick Start Example

Here's a complete walkthrough of using the meta-skill-generator to create a PDF processing skill.

## Scenario

You want to create a skill that handles PDF operations. You find yourself repeatedly:
- Converting PDFs to images
- Extracting text from PDFs
- Merging multiple PDFs
- Summarizing PDF contents

## Step 1: Run the Interactive Creator

```bash
cd /path/to/skills
/path/to/meta-skill-generator/scripts/init_skill_with_analysis.py pdf-tools --path .
```

## Step 2: Provide Example Use Cases

```
======================================================================
STEP 1: GATHER EXAMPLE USE CASES
======================================================================

Provide 3-5 example requests that your skill should handle.
Each example should be a concrete user request.
Press Enter twice when done.

Example 1: Convert this PDF to PNG images
Example 2: Extract all text from document.pdf
Example 3: Merge these three PDFs into one
Example 4: Summarize the key points in this research paper
Example 5: 
```

## Step 3: Review Workflow Analysis

```
======================================================================
STEP 2: ANALYZING WORKFLOW
======================================================================

======================================================================
WORKFLOW ANALYSIS REPORT
======================================================================

Total operations identified: 4
  - Go scripts recommended: 3
  - Python scripts recommended: 0
  - Agent workflows recommended: 1

----------------------------------------------------------------------
GO SCRIPTS (Deterministic, Performance-Critical)
----------------------------------------------------------------------

1. Convert this PDF to PNG images
   Reason: Deterministic operation with performance/binary characteristics
   Suggested name: convert-pdf-png

2. Extract all text from document.pdf
   Reason: Deterministic operation suitable for compiled binary
   Suggested name: extract-text-document

3. Merge these three PDFs into one
   Reason: Deterministic operation suitable for compiled binary
   Suggested name: merge-three-pdfs

----------------------------------------------------------------------
AGENT WORKFLOWS (Reasoning Required)
----------------------------------------------------------------------

1. Summarize the key points in this research paper
   Reason: Requires reasoning, context analysis, or decision-making
   Implementation: Keep as natural language workflow in SKILL.md

======================================================================
Does this analysis look correct?
Continue with skill creation? (y/n): y
```

## Step 4: Initialize Skill

```
======================================================================
STEP 3: INITIALIZING SKILL
======================================================================

🚀 Initializing skill: pdf-tools
   Location: .

✅ Created skill directory: ./pdf-tools
✅ Created SKILL.md
✅ Created scripts/example.py
✅ Created references/api_reference.md
✅ Created assets/example_asset.txt
```

## Step 5: Specify Go Scripts

```
======================================================================
STEP 4: SPECIFY GO SCRIPTS
======================================================================

Based on the analysis, let's define the Go scripts.
Enter details for each deterministic operation.

--- Go Script 1 ---
Script name (e.g., pdf-to-images): pdf-to-images
Description: Convert PDF pages to PNG images
Input (e.g., 'PDF file path'): PDF file path
Output (e.g., 'Directory of PNG files'): Directory containing PNG files for each page
Logic (e.g., 'Extract each page at 300 DPI'): Extract each page as separate PNG at 300 DPI
✅ Script 'pdf-to-images' configured

--- Go Script 2 ---
Script name (e.g., pdf-to-images): extract-text
Description: Extract text from PDF
Input (e.g., 'PDF file path'): PDF file path
Output (e.g., 'Directory of PNG files'): Text content to stdout
Logic (e.g., 'Extract each page at 300 DPI'): Parse PDF and extract all text content
✅ Script 'extract-text' configured

--- Go Script 3 ---
Script name (e.g., pdf-to-images): merge-pdfs
Description: Merge multiple PDF files
Input (e.g., 'PDF file path'): Multiple PDF file paths
Output (e.g., 'Directory of PNG files'): Single merged PDF file
Logic (e.g., 'Extract each page at 300 DPI'): Combine all input PDFs into one output PDF
✅ Script 'merge-pdfs' configured

--- Go Script 4 ---
Script name (e.g., pdf-to-images): 
```

## Step 6: Scripts Generated

```
======================================================================
STEP 5: GENERATING GO SCRIPTS
======================================================================

Generating pdf-to-images...
✅ Generated pdf-to-images

Generating extract-text...
✅ Generated extract-text

Generating merge-pdfs...
✅ Generated merge-pdfs
```

## Step 7: Skill Created

```
======================================================================
STEP 6: FINALIZING SKILL.MD
======================================================================

✅ Updated SKILL.md with 4 example use cases

======================================================================
✅ SKILL CREATED SUCCESSFULLY
======================================================================

Skill location: ./pdf-tools

Next steps:
1. Review and customize SKILL.md:
   - Complete the description in frontmatter
   - Add detailed workflow instructions
   - Remove TODO placeholders

2. Build Go scripts:
   cd ./pdf-tools
   ./scripts/build_pdf-to-images.sh
   ./scripts/build_extract-text.sh
   ./scripts/build_merge-pdfs.sh

3. Test the scripts:
   ./scripts/bin/pdf-to-images --help
   ./scripts/bin/extract-text --help
   ./scripts/bin/merge-pdfs --help

4. Package the skill:
   python3 /path/to/skill-creator/scripts/package_skill.py ./pdf-tools
```

## What Was Created

### Directory Structure

```
pdf-tools/
├── SKILL.md                      # Main documentation
├── scripts/
│   ├── pdf-to-images.go          # Generated Go source
│   ├── extract-text.go
│   ├── merge-pdfs.go
│   ├── build_pdf-to-images.sh   # Build scripts
│   ├── build_extract-text.sh
│   └── build_merge-pdfs.sh
├── references/
│   └── api_reference.md          # For detailed docs
└── assets/
    └── example_asset.txt          # For templates
```

### Generated Go Script Example

**pdf-to-images.go** (partial):

```go
package main

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

// Convert PDF pages to PNG images
// Generated by meta-skill-generator for Claude Code skills

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)
    }

    // Validate and process...
}

func usage() {
    fmt.Fprintf(os.Stderr, "Usage: %s [options] <input-file>\n", os.Args[0])
    fmt.Fprintf(os.Stderr, "\nConvert PDF pages to PNG images\n\n")
    fmt.Fprintf(os.Stderr, "Input:  PDF file path\n")
    fmt.Fprintf(os.Stderr, "Output: Directory containing PNG files for each page\n\n")
    fmt.Fprintf(os.Stderr, "Options:\n")
    flag.PrintDefaults()
}

// ... validation and processing logic ...
```

### SKILL.md Example

```markdown
---
name: pdf-tools
description: [TODO: Complete description with when to use this skill]
---

# Pdf Tools

## Overview

[TODO: 1-2 sentences]

## Example Use Cases

1. Convert this PDF to PNG images
2. Extract all text from document.pdf
3. Merge these three PDFs into one
4. Summarize the key points in this research paper


### pdf-to-images

Convert PDF pages to PNG images

**Input:** PDF file path  
**Output:** Directory containing PNG files for each page

**Usage:**
```bash
scripts/bin/pdf-to-images [options] <input>
scripts/bin/pdf-to-images --help
```

# ... more documentation ...
```

## Next: Customize and Complete

### 1. Edit SKILL.md

```yaml
---
name: pdf-tools
description: Comprehensive PDF manipulation toolkit. Use for converting PDFs to images, extracting text, merging documents, and analyzing PDF content. Triggers: mentions of PDF, .pdf files, document processing.
---
```

Add workflow sections, usage examples, etc.

### 2. Implement TODOs in Go Scripts

The generated Go scripts have `// TODO:` comments where you need to add the actual PDF processing logic. You might use libraries like:

```go
// Add PDF processing library
import "github.com/pdfcpu/pdfcpu/pkg/api"
```

### 3. Build the Scripts

```bash
cd pdf-tools
chmod +x scripts/build_*.sh
./scripts/build_pdf-to-images.sh
./scripts/build_extract-text.sh
./scripts/build_merge-pdfs.sh
```

### 4. Test

```bash
./scripts/bin/pdf-to-images test.pdf output/
./scripts/bin/extract-text test.pdf
./scripts/bin/merge-pdfs file1.pdf file2.pdf merged.pdf
```

### 5. Package

```bash
python3 /path/to/skill-creator/scripts/package_skill.py pdf-tools
```

This creates `pdf-tools.skill` ready to share!

## Key Takeaways

1. **Interactive workflow** - Guides you through the entire process
2. **Smart analysis** - Automatically identifies what should be scripts
3. **Production-ready code** - Generates complete, working templates
4. **Best practices** - Follows skill-creator conventions
5. **Fast iteration** - From idea to packaged skill in minutes

## Customization

You can customize the generated scripts by:
- Adding actual implementation for TODOs
- Importing necessary libraries
- Adding more CLI flags
- Enhancing error handling
- Adding more helper functions

The template provides the structure; you add the domain-specific logic.

## Result

You now have a complete, well-structured skill with:
- ✅ Separated deterministic operations (Go scripts)
- ✅ Identified reasoning tasks (agent workflows)
- ✅ Clean directory structure
- ✅ Production-ready templates
- ✅ Comprehensive documentation
- ✅ Ready to package and share

All created in one interactive session!