7.2 KiB
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
---
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:
scripts/bin/pdf-to-images document.pdf output/
Merge multiple PDFs:
scripts/bin/merge-pdfs file1.pdf file2.pdf file3.pdf output.pdf
Workflow Decision Tree
-
Simple operations (extract, convert, merge, rotate) → Use appropriate Go script from scripts/bin/
-
Content analysis (summarize, find information) → First extract text, then analyze content
-
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)
- Run initial analysis:
python3 scripts/analyze_data.py data.csv
- 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:
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
# 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
# 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:
---
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)