diegosouzapw/awesome-omni-skill / skills/ai-agents/annotating-csv
annotating-csv
UnverifiedAnnotates CSV rows using OpenAI by applying a prompt to each row and adding a new column with AI-generated results. Use when the user wants to classify, extract, summarize, or add AI-generated annotations to CSV data. Triggers on mentions of CSV annotation, row-by-row AI processing, bulk classification, or adding AI columns to spreadsheet data.
CSV Annotation with OpenAI
Adds AI-generated annotations to CSV files by processing each row with a prompt.
Quick Start
uv run annotate-csv.py "Classify sentiment as positive/negative/neutral" reviews.csv
Output: reviews_annotated.csv with new annotation column.
Dependencies install automatically on first run.
Core Usage
uv run annotate-csv.py <prompt> <csv_file> [options]
| Option | Description | Default |
|---|---|---|
-o, --output | Output file path | <input>_annotated.csv |
-c, --column | Annotation column name | annotation |
--context | Columns to use (all or comma-separated) | all |
--model | OpenAI model | gpt-5-mini |
--parallelism | Parallel workers | 10 |
--id-column | Column for progress display | - |
Prompt Sources
Prompts can be inline or from a file:
# Inline prompt
python annotate-csv.py "Extract the main topic" data.csv
# From file (for complex prompts)
python annotate-csv.py prompt.txt data.csv
Common Patterns
Classification:
python annotate-csv.py "Classify sentiment: positive, negative, or neutral" feedback.csv -c sentiment
Extraction:
python annotate-csv.py "Extract the product name mentioned" reviews.csv -c product --context "review_text"
Summarization:
python annotate-csv.py "Summarize in one sentence" articles.csv -c summary
See EXAMPLES.md for more patterns and prompt templates.
Environment Setup
Requires OPENAI_API_KEY in .env file:
OPENAI_API_KEY=sk-...
Run with uv (recommended):
uv run annotate-csv.py "Your prompt" data.csv
Or install dependencies first:
uv pip install -r requirements.txt
python annotate-csv.py "Your prompt" data.csv
Workflow
- Preview data: Check CSV structure and columns
- Choose context: Decide which columns the AI needs to see
- Write prompt: Be specific about expected output format
- Test on subset: Try on a few rows first if large dataset
- Run full annotation: Process the complete file
- Validate results: Spot-check annotation quality
Writing Effective Prompts
- Be explicit about output format (single word, phrase, sentence)
- List valid categories for classification tasks
- Specify what to do with ambiguous cases
- Keep prompts focused on one task
See PROMPTS.md for prompt-writing guidance.
Troubleshooting
| Issue | Solution |
|---|---|
| API key error | Check .env file has OPENAI_API_KEY |
| Column not found | Verify column names match CSV exactly |
| Rate limits | Reduce --parallelism to 5 or lower |
| Empty annotations | Check context columns have data |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |