# Skill Examples

Real-world examples of well-structured skills with Go scripts and agent workflows.

## Example 1: PDF Tools Skill

### Structure
```
pdf-tools/
├── SKILL.md
├── scripts/
│   ├── pdf-to-images.go
│   ├── merge-pdfs.go
│   ├── extract-text.go
│   ├── rotate-pages.go
│   └── bin/
│       ├── pdf-to-images
│       ├── merge-pdfs
│       ├── extract-text
│       └── rotate-pages
└── references/
    └── pdf-formats.md
```

### SKILL.md Excerpt
```markdown
---
name: pdf-tools
description: Comprehensive PDF manipulation toolkit. Use when users need to convert, merge, split, rotate, or extract content from PDF files. Triggers: mentions of PDF, .pdf files uploaded, requests for document manipulation.
---

# PDF Tools

Tools for efficient PDF manipulation with compiled binaries for performance.

## Quick Start

Common operations:

**Extract text:**
```bash
scripts/bin/extract-text document.pdf
```

**Convert to images:**
```bash
scripts/bin/pdf-to-images document.pdf output/
```

**Merge multiple PDFs:**
```bash
scripts/bin/merge-pdfs file1.pdf file2.pdf file3.pdf output.pdf
```

## Workflow Decision Tree

1. **Simple operations** (extract, convert, merge, rotate)
   → Use appropriate Go script from scripts/bin/

2. **Content analysis** (summarize, find information)
   → First extract text, then analyze content

3. **Form filling**
   → See references/pdf-forms.md for detailed workflow
```

### When to Use What

- **Go scripts:** All standard PDF operations (deterministic)
- **Agent workflow:** Content analysis, recommendations
- **References:** Complex topics like form handling

## Example 2: Data Processing Skill

### Structure
```
data-processor/
├── SKILL.md
├── scripts/
│   ├── csv-to-json.go
│   ├── json-to-csv.go
│   ├── validate-schema.go
│   ├── analyze_data.py (Python for pandas)
│   └── bin/
│       ├── csv-to-json
│       ├── json-to-csv
│       └── validate-schema
└── references/
    ├── schemas.md
    └── analysis-patterns.md
```

### SKILL.md Excerpt
```markdown
---
name: data-processor
description: Convert and analyze structured data formats. Use for CSV, JSON, XML conversions, data validation, and exploratory analysis. Triggers: data files uploaded, mentions of CSV/JSON/XML, requests for data analysis or conversion.
---

# Data Processor

## Operations

### Format Conversions (Go Scripts)

Fast, deterministic conversions:

```bash
# CSV to JSON
scripts/bin/csv-to-json input.csv output.json

# JSON to CSV
scripts/bin/json-to-csv input.json output.csv

# Validate against schema
scripts/bin/validate-schema data.json schema.json
```

### Data Analysis (Python + Agent)

1. Run initial analysis:
```bash
python3 scripts/analyze_data.py data.csv
```

2. Interpret results and provide insights:
   - Identify patterns
   - Suggest visualizations
   - Recommend next steps
```

### Pattern: Two-Phase Processing

This skill demonstrates the common pattern:

**Phase 1: Go Scripts**
- Fast data transformation
- Schema validation
- Format conversion
- Output: structured data

**Phase 2: Agent Workflow**
- Interpret results
- Find insights
- Make recommendations
- Output: human-readable analysis

## Example 3: Image Tools Skill

### Structure
```
image-tools/
├── SKILL.md
├── scripts/
│   ├── resize-image.go
│   ├── convert-format.go
│   ├── batch-process.go
│   └── bin/
│       ├── resize-image
│       ├── convert-format
│       └── batch-process
└── assets/
    └── watermark.png
```

### SKILL.md Excerpt
```markdown
---
name: image-tools
description: Image manipulation and batch processing. Use for resizing, format conversion, cropping, rotating images. Supports batch operations. Triggers: image files uploaded, mentions of image processing, resize, convert, crop, rotate.
---

# Image Tools

## Single Image Operations

```bash
# Resize
scripts/bin/resize-image input.jpg 800x600 output.jpg

# Convert format
scripts/bin/convert-format input.jpg output.png

# Rotate
scripts/bin/rotate-image input.jpg 90 output.jpg
```

## Batch Processing

Process entire directories efficiently:

```bash
scripts/bin/batch-process \
  --operation resize \
  --size 800x600 \
  --input images/ \
  --output resized/
```

The batch processor uses parallel goroutines for performance.

## When to Use Agent vs Scripts

**Use Go scripts for:**
- Standard operations (resize, crop, rotate, convert)
- Batch processing
- Operations with clear parameters

**Use agent workflow for:**
- "Make this image look better" (subjective)
- "Find the best crop for this portrait" (requires understanding)
- Choosing between multiple processing options
```

## Key Patterns Across Examples

### 1. Clear Separation of Concerns

**Deterministic → Go scripts**
- Format conversions
- Standard transformations
- Validation
- Batch operations

**Reasoning required → Agent workflows**
- Content analysis
- Recommendations
- Context-dependent decisions
- Creative tasks

### 2. Performance Where It Matters

Use Go for:
- Large file processing
- Batch operations (parallel)
- High-volume tasks
- Binary data manipulation

### 3. Progressive Disclosure

**SKILL.md:** High-level workflows and common operations  
**References/:** Detailed documentation for complex topics  
**Scripts/:** Implementation of deterministic operations

### 4. User-Friendly CLI

All Go scripts follow patterns:
- `--help` flag
- Clear error messages
- Progress indicators for long operations
- Verbose mode for debugging

### 5. Testing Strategy

Each skill includes:
- Example inputs in README or references
- Test commands for each script
- Expected outputs documented

## Anti-Example: What Not to Do

### ❌ Over-Scripting
```markdown
# DON'T: Script everything including one-liners
scripts/bin/list-files  # Just use 'ls'!
scripts/bin/copy-file   # Just use 'cp'!
```

### ❌ Under-Scripting
```markdown
# DON'T: Agent workflow for repeated deterministic tasks

For each file:
1. Read the file content
2. Convert JSON to YAML
3. Save to new location

# SHOULD BE: scripts/bin/json-to-yaml (called once for batch)
```

### ❌ Wrong Tool
```markdown
# DON'T: Go for data science
scripts/bin/train-ml-model  # Use Python!

# DON'T: Python for file conversion
scripts/convert_csv.py  # Use Go for performance!
```

## Template for New Skills

Based on these patterns:

```markdown
---
name: my-skill
description: What it does and when to use it. Include specific triggers.
---

# My Skill

## Quick Start

[Most common operation with example]

## Operations

### Category 1: [Deterministic Operations]
[Go script usage examples]

### Category 2: [Analysis/Reasoning]
[Agent workflow description]

## Workflow Patterns

[When to use what]

## Resources

[References to scripts, references, assets]
```

## Measuring Success

A well-designed skill has:

✅ Clear triggering in description  
✅ Go scripts for repeated deterministic tasks  
✅ Agent workflows for reasoning tasks  
✅ Lean SKILL.md (<500 lines)  
✅ Detailed references for complex topics  
✅ Tested, working scripts  
✅ Clear usage examples  
✅ No redundant tools (use bash when appropriate)