claude-code-meta-skill/source/meta-skill-generator/references/workflow-analysis.md

Workflow Analysis Guide

This guide helps identify which operations should be Go scripts vs agent workflows.

Decision Framework

Ask These Questions

For each operation in your skill, evaluate:

1. Does it require understanding/interpretation?

   • YES → Agent workflow
   • NO → Continue

2. Is the logic completely deterministic?

   • NO → Agent workflow
   • YES → Continue

3. Could it benefit from compilation/performance?

   • YES → Go script
   • NO → Continue

4. Does it need Python libraries?

   • YES → Python script
   • NO → Go script

Detailed Analysis

Strongly Favor Go Scripts For:

File operations:

• Format conversions (PDF→PNG, CSV→JSON)
• Splitting/merging files
• Batch renaming/organizing
• File validation (format checks)
• Compression/decompression

Data transformations:

• Parsing structured data (CSV, JSON, XML)
• Format conversions with fixed rules
• Data validation against schemas
• Mathematical computations
• Text processing with regex

Batch operations:

• Processing thousands of files
• Parallel operations on independent items
• High-volume data processing
• Performance-critical tasks

Binary/low-level:

• Image manipulation (resize, crop, rotate)
• Audio/video processing
• Network protocols
• Cryptographic operations

Strongly Favor Agent Workflows For:

Content understanding:

• Sentiment analysis
• Topic extraction
• Summarization
• Question answering
• Semantic search

Decision-making:

• Choosing strategies based on context
• Adapting to unexpected inputs
• Multi-step reasoning
• Evaluating trade-offs

Creative tasks:

• Writing (articles, emails, code comments)
• Design suggestions
• Naming (variables, files, projects)
• Brainstorming

Interactive processes:

• Troubleshooting
• Guided workflows with user input
• Adaptive error handling
• Context-dependent branching

Consider Python Scripts For:

Data science:

• Pandas/NumPy operations
• Statistical analysis
• Data visualization
• Machine learning inference

Specialized libraries:

• Computer vision (OpenCV)
• NLP (spaCy, NLTK)
• Web scraping (BeautifulSoup)
• API clients with complex auth

Prototyping:

• Quick experiments
• One-off utilities
• Testing ideas before Go implementation

Real-World Examples

Example 1: PDF Processing Skill

User requests:

1. "Extract text from this PDF"
2. "Rotate all pages 90 degrees"
3. "Summarize the key points in this PDF"
4. "Split this PDF into separate pages"

Analysis:

Request	Operation	Type	Reason
Extract text	pdf-extract-text	Go script	Deterministic, parsing
Rotate pages	pdf-rotate-pages	Go script	Deterministic, binary
Summarize	summarize-document	Agent workflow	Understanding required
Split pages	pdf-split-pages	Go script	Deterministic, file ops

Go scripts: 3
Agent workflows: 1

Example 2: Data Analysis Skill

User requests:

1. "Convert this CSV to JSON"
2. "Find outliers in this dataset"
3. "Plot the trends in this data"
4. "What insights can you find?"

Analysis:

Request	Operation	Type	Reason
CSV to JSON	csv-to-json	Go script	Simple conversion
Find outliers	find-outliers	Python script	Statistical libraries
Plot trends	plot-data	Python script	Matplotlib/Seaborn
Find insights	analyze-insights	Agent workflow	Interpretation needed

Go scripts: 1
Python scripts: 2
Agent workflows: 1

Example 3: Code Generation Skill

User requests:

1. "Format this code"
2. "Generate boilerplate for a REST API"
3. "Review this code for bugs"
4. "Add error handling"

Analysis:

Request	Operation	Type	Reason
Format code	format-code	Go script	Deterministic rules
Generate boilerplate	generate-boilerplate	Go script	Template-based
Review for bugs	review-code	Agent workflow	Reasoning required
Add error handling	add-error-handling	Agent workflow	Context-dependent

Go scripts: 2
Agent workflows: 2

Common Patterns

Pattern: "Process and Analyze"

Many skills have this two-phase pattern:

1. Process phase (Go script)

   • Extract/transform/validate data
   • Fixed, deterministic operations
   • Output: structured data

2. Analyze phase (Agent workflow)

   • Interpret results
   • Make recommendations
   • Context-dependent decisions

Example:

1. Run: scripts/bin/extract-metrics data.log
   Extracts structured metrics to metrics.json

2. Analyze the metrics and identify:
   - Performance bottlenecks
   - Unusual patterns
   - Recommended optimizations

Pattern: "Validate and Act"

1. Validate (Go script)

   • Check format/schema
   • Fast, deterministic
   • Output: valid/invalid + errors

2. Act (Agent workflow or Go script)

   • If valid → Go script for fixed action
   • If invalid → Agent helps troubleshoot

Example:

1. Run: scripts/bin/validate-config config.yaml
   - Validates against schema
   - Returns validation errors

2. If valid:
   - Run: scripts/bin/apply-config config.yaml
   
   If invalid:
   - Review errors and suggest fixes

Pattern: "Batch with Exceptions"

1. Batch process (Go script)

   • Process 95% of standard cases
   • Fast, parallel
   • Flag exceptions

2. Handle exceptions (Agent workflow)

   • Review flagged items
   • Make case-by-case decisions
   • Learn patterns for future

Anti-Patterns

❌ Over-Engineering

Don't create Go scripts for:

• Operations done once
• Simple 5-line operations
• Operations that may need frequent changes

Better: Keep as agent workflow or simple bash command

❌ Under-Engineering

Don't use agent workflows for:

• Operations rewritten 10+ times
• Performance-critical bottlenecks
• Operations with clear pass/fail criteria

Better: Extract to Go script

❌ Wrong Tool

Don't use Go for:

• Complex data science (use Python)
• Operations requiring heavyweight libraries
• Rapid prototyping

Don't use Python for:

• High-performance requirements
• Binary/low-level operations
• Simple file processing

Optimization Checklist

When reviewing a skill design:

• Every Go script is truly deterministic
• Every agent workflow truly needs reasoning
• No operations rewritten 3+ times
• Performance-critical paths identified
• Python used only where libraries needed
• Clear boundaries between phases
• Error handling strategy defined
• Testing approach planned

Next Steps

After analysis:

1. List all Go scripts to create
2. List all Python scripts to create
3. Document agent workflows in SKILL.md
4. Create integration points between scripts and workflows
5. Plan testing strategy
6. Implement in priority order