Add Agent Creator skill - American English version
Complete translation of agent-creator meta-skill to American English. This skill teaches Claude Code to autonomously create production-ready agents using a 5-phase protocol: - Phase 1: Discovery (API research and selection) - Phase 2: Design (analysis definition) - Phase 3: Architecture (modular structure) - Phase 4: Detection (keyword identification) - Phase 5: Implementation (complete code generation) Includes comprehensive documentation (~24,000 words), quality standards, and detailed phase guides. Translation: Portuguese → American English Structure: Identical to original Quality: High-fidelity translation maintaining technical accuracy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Francy Lisboa
commit
5311fda5fc
11 changed files with 7835 additions and 0 deletions
22
.claude-plugin/marketplace.json
Normal file
22
.claude-plugin/marketplace.json
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
{
|
||||
"name": "agent-creator-en",
|
||||
"owner": {
|
||||
"name": "Agent Creator",
|
||||
"email": "noreply@example.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Agent Creator - Meta-skill for autonomous agent generation in English",
|
||||
"version": "1.0.0",
|
||||
"created": "2025-10-18",
|
||||
"language": "en-US"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "agent-creator-en-plugin",
|
||||
"description": "This skill should be used when the user asks to create an agent, automate a repetitive workflow, or create a custom skill. Activates with phrases like every day, daily I have to, I need to repeat, create agent for, automate workflow, create skill for, need to automate, turn process into agent. Claude will use the 5-phase protocol to research APIs, define analyses, structure everything, implement functional code, and create a complete skill autonomously in a subdirectory.",
|
||||
"source": "./",
|
||||
"strict": false,
|
||||
"skills": ["./"]
|
||||
}
|
||||
]
|
||||
}
|
||||
29
.gitignore
vendored
Normal file
29
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
*.egg-info/
|
||||
dist/
|
||||
build/
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
|
||||
# Virtual environments
|
||||
venv/
|
||||
.venv/
|
||||
ENV/
|
||||
env/
|
||||
846
README.md
Normal file
846
README.md
Normal file
|
|
@ -0,0 +1,846 @@
|
|||
# Agent Creator - Meta-Skill for Claude Code
|
||||
|
||||
**Meta-skill that teaches Claude Code to create complete agents with Claude Skills in a fully autonomous way!**
|
||||
|
||||
You describe a repetitive workflow → Claude creates a complete production-ready agent in 60-90 minutes.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What It Is and What It Does
|
||||
|
||||
### Problem It Solves
|
||||
|
||||
Creating a Claude Code agent manually is:
|
||||
- ⏰ **Time-consuming**: 20-30 hours of work
|
||||
- 🧠 **Complex**: Requires knowledge of APIs, Python, architecture
|
||||
- 🔍 **Labor-intensive**: Research APIs, define analyses, structure, code, document
|
||||
|
||||
### Solution: Agent-Creator
|
||||
|
||||
**You do:**
|
||||
```
|
||||
"Automate this workflow: every day I download crop data,
|
||||
compare current year vs previous, takes 2 hours."
|
||||
```
|
||||
|
||||
**Claude Code does:**
|
||||
1. 🔍 Research available APIs → Decide the best one
|
||||
2. 🎨 Define useful analyses → Prioritize by value
|
||||
3. 🏗️ Structure project → Optimal architecture
|
||||
4. 💻 Implement Python code → Functional, no TODOs
|
||||
5. 📝 Write documentation → 12,000+ words
|
||||
6. ⚙️ Create configs → Real values
|
||||
7. 📦 Deliver agent → Production-ready in subdirectory
|
||||
|
||||
**Result:** Complete agent in ~90 minutes!
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Claude Code CLI installed
|
||||
- Python 3.8+ (for agents that will be created)
|
||||
|
||||
### Step 1: Install in Claude Code
|
||||
|
||||
**In the Claude Code terminal**, run:
|
||||
|
||||
```bash
|
||||
/plugin marketplace add FrancyJGLisboa/agent-creator-skill
|
||||
```
|
||||
|
||||
### Step 2: Verify Installation
|
||||
|
||||
```bash
|
||||
/plugin list
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
✓ agent-creator
|
||||
```
|
||||
|
||||
### Done! 🎉
|
||||
|
||||
The meta-skill is installed and ready to use.
|
||||
|
||||
---
|
||||
|
||||
## 💡 How to Use (Tutorial Guide)
|
||||
|
||||
### Basic Usage - Describe Your Workflow
|
||||
|
||||
**In Claude Code**, simply describe what you do repeatedly:
|
||||
|
||||
```
|
||||
👤 You type:
|
||||
"Automate this workflow: every day I download US crop data,
|
||||
compare current year vs previous, rank states. Takes 2 hours."
|
||||
```
|
||||
|
||||
**🤖 Claude Code:**
|
||||
```
|
||||
[Detects keyword: "automate"]
|
||||
[Activates skill: agent-creator]
|
||||
[Loads 5-phase protocol]
|
||||
|
||||
🔍 Phase 1: Researching US agriculture APIs...
|
||||
✓ 5 options found
|
||||
✓ Decided: USDA NASS QuickStats API
|
||||
Reason: Free, data since 1866, complete coverage
|
||||
|
||||
🎨 Phase 2: Defining analyses...
|
||||
✓ 15 typical questions identified
|
||||
✓ 5 main analyses: YoY, Ranking, Trends, Reports
|
||||
|
||||
🏗️ Phase 3: Structuring project...
|
||||
✓ 3 scripts + 3 utils planned
|
||||
|
||||
🎯 Phase 4: Defining automatic detection...
|
||||
✓ 50+ keywords identified
|
||||
|
||||
⚙️ Phase 5: Implementing code...
|
||||
✓ SKILL.md (6,200 words)
|
||||
✓ fetch_nass.py (280 lines)
|
||||
✓ parse_nass.py (180 lines)
|
||||
✓ analyze_nass.py (520 lines)
|
||||
✓ utils/ (350 lines)
|
||||
✓ references/ (5,000 words)
|
||||
✓ .claude-plugin/marketplace.json ✅
|
||||
✓ README.md (800 words)
|
||||
|
||||
✅ AGENT CREATED: ./usda-agriculture-agent/
|
||||
|
||||
🚀 To install:
|
||||
/plugin marketplace add ./usda-agriculture-agent
|
||||
```
|
||||
|
||||
### What You Get
|
||||
|
||||
A complete directory:
|
||||
|
||||
```
|
||||
./usda-agriculture-agent/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json ← For Claude Code installation
|
||||
├── SKILL.md ← Complete orchestration (6,000 words)
|
||||
├── scripts/
|
||||
│ ├── fetch_nass.py ← API client (280 lines)
|
||||
│ ├── parse_nass.py ← Parsing & validation (180 lines)
|
||||
│ ├── analyze_nass.py ← Analyses (520 lines)
|
||||
│ └── utils/
|
||||
│ ├── cache_manager.py ← Smart cache
|
||||
│ ├── rate_limiter.py ← Rate limiting
|
||||
│ └── validators.py ← Validations
|
||||
├── references/
|
||||
│ ├── api-guide.md ← How to use the API
|
||||
│ ├── analysis-methods.md ← Detailed methodologies
|
||||
│ └── troubleshooting.md ← Problem solving
|
||||
├── assets/
|
||||
│ ├── config.json ← Real configurations
|
||||
│ └── metadata.json ← Metadata
|
||||
├── DECISIONS.md ← Decision justifications
|
||||
└── README.md ← Usage instructions
|
||||
```
|
||||
|
||||
**Total:** ~2,000 lines of code + ~12,000 words of documentation
|
||||
|
||||
---
|
||||
|
||||
## 🔄 How It Works Internally (5 Phases)
|
||||
|
||||
### PHASE 1: Discovery (API Research)
|
||||
|
||||
**What it does:**
|
||||
- Research available public APIs for the domain
|
||||
- Uses `WebSearch` and `WebFetch` to find options
|
||||
- Compares APIs by: coverage, cost, rate limits, quality
|
||||
- **DECIDES** autonomously which to use
|
||||
|
||||
**Example (Agriculture):**
|
||||
```bash
|
||||
WebSearch: "US agriculture API free historical data"
|
||||
WebSearch: "USDA API documentation"
|
||||
WebFetch: https://quickstats.nass.usda.gov/api
|
||||
|
||||
→ DECISION: USDA NASS QuickStats API
|
||||
Justification: Free, data since 1866, all crops
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### PHASE 2: Design (Analysis Definition)
|
||||
|
||||
**What it does:**
|
||||
- Brainstorm 10-15 typical user questions
|
||||
- Group by analysis type
|
||||
- **DEFINES** 4-6 priority analyses
|
||||
- Specifies methodologies (formulas, interpretations)
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Typical questions:
|
||||
- "Corn production in 2023?"
|
||||
- "Compare soybeans 2024 vs 2023"
|
||||
- "Top 10 producing states"
|
||||
|
||||
→ ANALYSES DEFINED:
|
||||
1. YoY Comparison (year vs year)
|
||||
2. State Ranking (top producers)
|
||||
3. Trend Analysis (trends)
|
||||
4. Report Generation (reports)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### PHASE 3: Architecture (Structuring)
|
||||
|
||||
**What it does:**
|
||||
- Defines folder and file structure
|
||||
- Specifies responsibilities of each script
|
||||
- Plans cache strategy and performance
|
||||
|
||||
**Example:**
|
||||
```
|
||||
→ STRUCTURE:
|
||||
scripts/
|
||||
- fetch_nass.py (API requests)
|
||||
- parse_nass.py (parsing)
|
||||
- analyze_nass.py (analyses)
|
||||
utils/
|
||||
- cache_manager.py
|
||||
- rate_limiter.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### PHASE 4: Detection (Automatic Activation)
|
||||
|
||||
**What it does:**
|
||||
- Lists domain keywords
|
||||
- Determines when skill should activate
|
||||
- Creates optimized description
|
||||
|
||||
**Example:**
|
||||
```
|
||||
→ KEYWORDS:
|
||||
Entities: USDA, NASS, agriculture
|
||||
Commodities: corn, soybeans, wheat
|
||||
Metrics: production, area, yield
|
||||
Actions: compare, ranking, trend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### PHASE 5: Implementation (Complete Code)
|
||||
|
||||
**What it does:**
|
||||
- Creates **marketplace.json** (REQUIRED!)
|
||||
- Implements functional Python code
|
||||
- Writes SKILL.md (5000+ words)
|
||||
- Creates references with useful content
|
||||
- Generates real configs
|
||||
|
||||
**Commands executed internally:**
|
||||
```bash
|
||||
mkdir -p agent-name/{scripts/utils,references,assets,.claude-plugin}
|
||||
# Write: .claude-plugin/marketplace.json
|
||||
# Write: SKILL.md
|
||||
# Write: scripts/fetch_*.py
|
||||
# Write: scripts/parse_*.py
|
||||
# Write: scripts/analyze_*.py
|
||||
# Write: utils/cache_manager.py
|
||||
# Write: references/*.md
|
||||
# Write: assets/*.json
|
||||
# Write: README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Practical Usage Examples
|
||||
|
||||
### Example 1: Agriculture (USDA)
|
||||
|
||||
**👤 Input in Claude Code:**
|
||||
```
|
||||
"Automate: every day I download US crop data,
|
||||
compare current year vs previous, rank states.
|
||||
Takes 2 hours."
|
||||
```
|
||||
|
||||
**🤖 Claude executes (autonomously):**
|
||||
```
|
||||
Phase 1: Research → USDA NASS API
|
||||
Phase 2: Define → YoY, Ranking, Trends
|
||||
Phase 3: Structure → 3 scripts + 2 utils
|
||||
Phase 4: Keywords → USDA, corn, soybeans, production
|
||||
Phase 5: Implement → 1,410 lines of code
|
||||
|
||||
✅ Agent created: ./usda-agriculture-agent/
|
||||
```
|
||||
|
||||
**💻 How to install the created agent:**
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin marketplace add ./usda-agriculture-agent
|
||||
```
|
||||
|
||||
**🎯 How to use:**
|
||||
```
|
||||
"US corn production in 2023"
|
||||
"Compare soybeans this year vs last year"
|
||||
"Top 10 wheat producing states"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Finance (Stocks)
|
||||
|
||||
**👤 Input:**
|
||||
```
|
||||
"Need agent for stock analysis:
|
||||
fetch prices, calculate RSI and MACD,
|
||||
compare with benchmarks. Daily, 3h."
|
||||
```
|
||||
|
||||
**🤖 Claude creates:**
|
||||
```
|
||||
Phase 1: Alpha Vantage API (or Yahoo Finance)
|
||||
Phase 2: Price fetching, RSI, MACD, Benchmarking
|
||||
Phase 3-5: Implement everything
|
||||
|
||||
✅ Created: ./stock-technical-analysis-agent/
|
||||
```
|
||||
|
||||
**💻 Install:**
|
||||
```bash
|
||||
/plugin marketplace add ./stock-technical-analysis-agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Climate (Real Case from Today!)
|
||||
|
||||
**👤 Input:**
|
||||
```
|
||||
"Create agent for climate analysis of Sorriso, Mato Grosso.
|
||||
Need to analyze temperature and precipitation, historical trends."
|
||||
```
|
||||
|
||||
**🤖 Claude executed (5 autonomous phases):**
|
||||
|
||||
```
|
||||
🔍 PHASE 1: Climate API Research
|
||||
Researched: INMET, Open-Meteo, OpenWeather, Visual Crossing
|
||||
Compared: Coverage, cost, historical data
|
||||
✓ DECIDED: Open-Meteo Historical Weather API
|
||||
• Free (no API key!)
|
||||
• Data since 1940 (84+ years)
|
||||
• ERA5 reanalysis (high quality)
|
||||
• REST API (easy integration)
|
||||
|
||||
🎨 PHASE 2: Analysis Design
|
||||
Brainstorm: 15 typical questions
|
||||
✓ DEFINED: 6 main analyses
|
||||
1. Basic time series
|
||||
2. Temporal comparison (YoY)
|
||||
3. Trend analysis (CAGR, regression)
|
||||
4. Anomaly detection (Z-score)
|
||||
5. Seasonal analysis (monthly climatology)
|
||||
6. Descriptive statistics
|
||||
|
||||
🏗️ PHASE 3: Architecture
|
||||
✓ STRUCTURED:
|
||||
scripts/
|
||||
- fetch_climate.py (320 lines)
|
||||
- parse_climate.py (180 lines)
|
||||
- analyze_climate.py (420 lines)
|
||||
utils/
|
||||
- cache_manager.py (350 lines)
|
||||
- validators.py (450 lines)
|
||||
- statistics.py (350 lines)
|
||||
✓ Cache: Historical permanent, current year 24h
|
||||
✓ Validations: Ranges, physical consistency, continuity
|
||||
|
||||
🎯 PHASE 4: Automatic Detection
|
||||
✓ KEYWORDS: Sorriso, temperature, precipitation, rain, climate,
|
||||
trend, historical, anomaly, compare
|
||||
✓ DESCRIPTION: 200 words optimized
|
||||
|
||||
⚙️ PHASE 5: Complete Implementation
|
||||
✓ .claude-plugin/marketplace.json
|
||||
✓ SKILL.md (6,800 words)
|
||||
✓ Python scripts (2,070 lines)
|
||||
✓ References (1,500 words)
|
||||
✓ Configs (config.json, metadata.json)
|
||||
✓ README.md + DECISIONS.md
|
||||
|
||||
✅ AGENT CREATED: ./climate-analysis-sorriso-mt/
|
||||
```
|
||||
|
||||
**📊 Statistics:**
|
||||
- **Code:** 2,070 lines of Python
|
||||
- **Documentation:** 13,600 words
|
||||
- **Files:** 16 main files
|
||||
- **Time:** ~90 minutes of autonomous creation
|
||||
|
||||
**💻 Installation of created agent:**
|
||||
```bash
|
||||
# In terminal
|
||||
cd climate-analysis-sorriso-mt
|
||||
pip install -r requirements.txt
|
||||
|
||||
# In Claude Code
|
||||
/plugin marketplace add ./climate-analysis-sorriso-mt
|
||||
```
|
||||
|
||||
**🎯 Using the created agent:**
|
||||
```
|
||||
👤 "What's the average temperature in Sorriso over the last 10 years?"
|
||||
🤖 [Skill activates automatically]
|
||||
[Fetches data from API]
|
||||
[Analyzes and responds]
|
||||
|
||||
👤 "Rain trend in Sorriso since 1990"
|
||||
🤖 [34-year trend analysis]
|
||||
[Returns rate of change, significance, projection]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 How It Works: The 5 Autonomous Phases
|
||||
|
||||
### PHASE 1: DISCOVERY (API Research)
|
||||
|
||||
**Objective:** DECIDE which API to use
|
||||
|
||||
**Process:**
|
||||
1. Identifies domain (agriculture? finance? climate?)
|
||||
2. Research available public APIs
|
||||
3. Compares options (coverage, cost, quality)
|
||||
4. **DECIDES** with justification
|
||||
5. Documents decision
|
||||
|
||||
**Autonomy:** Claude decides without asking the user!
|
||||
|
||||
**Example of internal commands:**
|
||||
```bash
|
||||
# Claude executes internally:
|
||||
WebSearch: "US agriculture API free historical data"
|
||||
WebFetch: https://quickstats.nass.usda.gov/api
|
||||
# Compares: NASS vs ERS vs FAO
|
||||
# → DECISION: NASS (best option)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### PHASE 2: DESIGN (Analysis Definition)
|
||||
|
||||
**Objective:** DEFINE which analyses to implement
|
||||
|
||||
**Process:**
|
||||
1. Brainstorm typical questions (10-15)
|
||||
2. Group by type (comparisons, rankings, trends)
|
||||
3. **DEFINES** 4-6 priority analyses
|
||||
4. Specifies methodologies (mathematical formulas)
|
||||
|
||||
**Autonomy:** Claude prioritizes by value and frequency of use!
|
||||
|
||||
---
|
||||
|
||||
### PHASE 3: ARCHITECTURE (Structuring)
|
||||
|
||||
**Objective:** STRUCTURE the project optimally
|
||||
|
||||
**Process:**
|
||||
1. Defines folder structure
|
||||
2. Specifies scripts and responsibilities
|
||||
3. Plans cache strategy
|
||||
4. Defines validations
|
||||
|
||||
**Autonomy:** Claude chooses optimal architecture based on complexity!
|
||||
|
||||
---
|
||||
|
||||
### PHASE 4: DETECTION (Automatic Activation)
|
||||
|
||||
**Objective:** DETERMINE keywords for detection
|
||||
|
||||
**Process:**
|
||||
1. Lists domain entities
|
||||
2. Lists typical actions
|
||||
3. Determines keywords
|
||||
4. Creates optimized description (150-250 words)
|
||||
|
||||
**Result:** Skill activates automatically when user asks relevant question!
|
||||
|
||||
---
|
||||
|
||||
### PHASE 5: IMPLEMENTATION (Complete Code)
|
||||
|
||||
**Objective:** IMPLEMENT everything with REAL code
|
||||
|
||||
**Process:**
|
||||
```bash
|
||||
1. mkdir -p agent-name/{scripts/utils,references,assets,.claude-plugin}
|
||||
2. Write: .claude-plugin/marketplace.json ← REQUIRED!
|
||||
3. Write: SKILL.md (5000+ words)
|
||||
4. Write: scripts/*.py (functional code)
|
||||
5. Write: utils/*.py (cache, validators, etc)
|
||||
6. Write: references/*.md (useful content)
|
||||
7. Write: assets/*.json (real configs)
|
||||
8. Write: README.md + DECISIONS.md
|
||||
```
|
||||
|
||||
**Quality Standards:**
|
||||
- ✅ Complete code (no `TODO` or `pass`)
|
||||
- ✅ Detailed docstrings
|
||||
- ✅ Robust error handling
|
||||
- ✅ Type hints
|
||||
- ✅ Comprehensive validations
|
||||
|
||||
**Result:** Production-ready agent!
|
||||
|
||||
---
|
||||
|
||||
## 📝 Step-by-Step Commands
|
||||
|
||||
### 1. Create an Agent
|
||||
|
||||
**In Claude Code:**
|
||||
```
|
||||
👤 "Create an agent for [objective]"
|
||||
|
||||
OR
|
||||
|
||||
👤 "Automate this workflow: [description]"
|
||||
```
|
||||
|
||||
### 2. Wait for Creation
|
||||
|
||||
Claude executes the 5 phases autonomously (~60-90 min)
|
||||
|
||||
### 3. Install Created Agent
|
||||
|
||||
**In terminal:**
|
||||
```bash
|
||||
# Go to agent directory
|
||||
cd ./created-agent-name/
|
||||
|
||||
# Install Python dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# If API key needed (follow instructions in README)
|
||||
export API_KEY_VAR="your_key_here"
|
||||
```
|
||||
|
||||
**In Claude Code:**
|
||||
```bash
|
||||
# Install skill
|
||||
/plugin marketplace add ./created-agent-name
|
||||
|
||||
# Verify installation
|
||||
/plugin list
|
||||
```
|
||||
|
||||
### 4. Use the Agent
|
||||
|
||||
**In Claude Code:**
|
||||
```
|
||||
👤 Ask questions related to the domain
|
||||
🤖 Skill activates automatically and responds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 ROI (Return on Investment)
|
||||
|
||||
| Metric | Manual | With Agent-Creator | Savings |
|
||||
|---------|--------|-------------------|----------|
|
||||
| **Time** | 20-30 hours | 1.5 hours | **15-20x** |
|
||||
| **Required knowledge** | APIs, Python, Architecture | None | **100%** |
|
||||
| **Code written** | By you | By Claude | **100%** |
|
||||
| **Quality** | Variable | Production-ready | High |
|
||||
|
||||
**But the best part:** You do nothing, just describe the workflow! 🎉
|
||||
|
||||
---
|
||||
|
||||
## 📚 Complete Documentation
|
||||
|
||||
This repository includes detailed guides in Portuguese:
|
||||
|
||||
1. **[como-compartilhar-skills.md](./como-compartilhar-skills.md)**
|
||||
- How to publish your skills
|
||||
- GitHub, ZIP, Claude.ai
|
||||
- Best practices
|
||||
|
||||
2. **[guia-completo-claude-skills.md](./guia-completo-claude-skills.md)**
|
||||
- Complete guide about Claude Skills
|
||||
- Technical specifications
|
||||
- Examples
|
||||
|
||||
3. **[como_instalar_agente_creator.md](./como_instalar_agente_creator.md)**
|
||||
- Detailed installation instructions
|
||||
- Troubleshooting
|
||||
|
||||
4. **[meta-prompt-autonomo-criacao-agentes.md](./meta-prompt-autonomo-criacao-agentes.md)**
|
||||
- Meta-prompt for agent creation
|
||||
- Universal annotated template
|
||||
- Quality checklist
|
||||
|
||||
5. **[scripts-vs-skills-guia-didatico.md](./scripts-vs-skills-guia-didatico.md)**
|
||||
- Didactic comparison Scripts vs Skills
|
||||
- When to use each approach
|
||||
|
||||
6. **[agent-creator/README.md](./agent-creator/README.md)**
|
||||
- Meta-skill documentation
|
||||
- Technical details
|
||||
|
||||
---
|
||||
|
||||
## 💡 Use Cases
|
||||
|
||||
### Agriculture
|
||||
```
|
||||
"Create agent for Brazilian crop analysis via CONAB"
|
||||
→ Agent with TXT parsing, YoY analyses, regional rankings
|
||||
```
|
||||
|
||||
### Finance
|
||||
```
|
||||
"Automate daily stock analysis: prices, RSI, MACD"
|
||||
→ Agent with technical indicators, alerts, comparisons
|
||||
```
|
||||
|
||||
### Climate
|
||||
```
|
||||
"Climate analysis of Sorriso-MT: temperature, rain, trends"
|
||||
→ Agent with data since 1940, 6 types of analyses
|
||||
```
|
||||
|
||||
### Economy
|
||||
```
|
||||
"Agent for World Bank economic indicators"
|
||||
→ Agent with GDP, inflation, country comparisons
|
||||
```
|
||||
|
||||
**Any domain with API or structured data!**
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Useful Commands
|
||||
|
||||
### Check Installed Skills
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin list
|
||||
```
|
||||
|
||||
### Install Agent-Creator
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin marketplace add FrancyJGLisboa/agent-creator-skill
|
||||
```
|
||||
|
||||
### Create an Agent
|
||||
```bash
|
||||
# In Claude Code (natural language)
|
||||
"Create an agent for [objective]"
|
||||
"Automate workflow of [description]"
|
||||
```
|
||||
|
||||
### Install Created Agent
|
||||
```bash
|
||||
# Terminal
|
||||
cd ./created-agent/
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Claude Code
|
||||
/plugin marketplace add ./created-agent
|
||||
```
|
||||
|
||||
### Use Agent
|
||||
```bash
|
||||
# In Claude Code (natural language)
|
||||
Ask questions related to the agent's domain
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Technical Requirements
|
||||
|
||||
### To Use Agent-Creator
|
||||
- Claude Code CLI installed
|
||||
- Internet connection (for API research)
|
||||
|
||||
### For Created Agents
|
||||
- Python 3.8+
|
||||
- pip (to install dependencies)
|
||||
- Specific dependencies (listed in requirements.txt of each agent)
|
||||
- API key (if chosen API requires - instructions in agent's README)
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Understanding the Output
|
||||
|
||||
### Main Files Created
|
||||
|
||||
**`.claude-plugin/marketplace.json`**
|
||||
- Configuration for Claude Code installation
|
||||
- **CRITICAL:** Without it, skill cannot be installed
|
||||
|
||||
**`SKILL.md`**
|
||||
- Complete skill orchestration
|
||||
- Detailed workflows
|
||||
- Analysis documentation
|
||||
- ~5000-7000 words
|
||||
|
||||
**`scripts/`**
|
||||
- Functional Python code
|
||||
- Separated by responsibility (fetch, parse, analyze)
|
||||
- Reusable utils (cache, validators)
|
||||
- ~1500-2000 lines total
|
||||
|
||||
**`references/`**
|
||||
- Technical guides (API docs, methodologies)
|
||||
- Troubleshooting
|
||||
- Domain knowledge
|
||||
- ~5000 words
|
||||
|
||||
**`README.md`**
|
||||
- Installation instructions
|
||||
- Usage examples
|
||||
- Troubleshooting
|
||||
|
||||
**`DECISIONS.md`**
|
||||
- Justifications for all decisions
|
||||
- Which API chosen and why
|
||||
- Which analyses and why
|
||||
- Trade-offs considered
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Features
|
||||
|
||||
- ✅ **Total Autonomy:** Claude decides everything
|
||||
- ✅ **Production-Ready:** Functional code, no TODOs
|
||||
- ✅ **Complete Documentation:** 10,000+ words
|
||||
- ✅ **Smart Cache:** TTL based on data type
|
||||
- ✅ **Robust Validations:** Guaranteed data quality
|
||||
- ✅ **Error Handling:** Retry, fallbacks, clear messages
|
||||
- ✅ **Marketplace.json:** Guaranteed Claude Code installation
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Limitations
|
||||
|
||||
**DO NOT use for:**
|
||||
- ❌ Editing existing skills (edit directly)
|
||||
- ❌ Debugging skills (debug directly)
|
||||
- ❌ Asking questions about skills (ask directly)
|
||||
|
||||
**USE ONLY for:**
|
||||
- ✅ Creating new agents from scratch
|
||||
- ✅ Automating repetitive workflows
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome!
|
||||
|
||||
1. Fork this repository
|
||||
2. Create a branch (`git checkout -b feature/improvement`)
|
||||
3. Commit your changes
|
||||
4. Push to the branch
|
||||
5. Open a Pull Request
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
Apache 2.0 (same license as Anthropic's official skills)
|
||||
|
||||
Free to use, modify, and distribute.
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Credits
|
||||
|
||||
**Inspired by:**
|
||||
- [Anthropic Agent Skills Spec](https://github.com/anthropics/skills)
|
||||
- [skill-creator skill](https://github.com/anthropics/skills/tree/main/skill-creator)
|
||||
|
||||
**Differentiator:** Total autonomy - Claude decides everything, not just executes instructions.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Repository Statistics
|
||||
|
||||
**Agent-Creator Meta-Skill:**
|
||||
- 8 main files
|
||||
- ~5,000 words in SKILL.md
|
||||
- 6 detailed references
|
||||
- 5-phase autonomous protocol
|
||||
|
||||
**Documentation:**
|
||||
- 5 complete guides in Portuguese
|
||||
- ~150 KB of documentation
|
||||
- Complete coverage of Claude Skills ecosystem
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Examples of Agents Created with Agent-Creator
|
||||
|
||||
**1. USDA Agriculture Agent**
|
||||
- API: USDA NASS
|
||||
- Analyses: YoY, Ranking, Trends
|
||||
- Output: 1,410 lines of code
|
||||
|
||||
**2. Climate Analysis Sorriso-MT** (created today!)
|
||||
- API: Open-Meteo
|
||||
- Analyses: 6 types (series, trends, anomalies, etc.)
|
||||
- Output: 2,070 lines of code
|
||||
|
||||
**All created autonomously by the meta-skill!**
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
**Issues:** https://github.com/FrancyJGLisboa/agent-creator-skill/issues
|
||||
**Discussions:** https://github.com/FrancyJGLisboa/agent-creator-skill/discussions
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Install agent-creator
|
||||
/plugin marketplace add FrancyJGLisboa/agent-creator-skill
|
||||
|
||||
# 2. Create an agent (in Claude Code)
|
||||
"Automate workflow for analyzing [your domain]"
|
||||
|
||||
# 3. Wait for creation (~60-90 min)
|
||||
|
||||
# 4. Install created agent
|
||||
/plugin marketplace add ./created-agent
|
||||
|
||||
# 5. Use it!
|
||||
"[Ask domain questions]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Start automating today! Transform repetitive workflows into powerful agents! 🚀**
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Updated:** October 2025
|
||||
**Author:** Created with Claude Code
|
||||
**Repository:** https://github.com/FrancyJGLisboa/agent-creator-skill
|
||||
454
references/phase1-discovery.md
Normal file
454
references/phase1-discovery.md
Normal file
|
|
@ -0,0 +1,454 @@
|
|||
# Phase 1: Discovery and API Research
|
||||
|
||||
## Objective
|
||||
|
||||
Research and **DECIDE** autonomously which API or data source to use for the agent.
|
||||
|
||||
## Detailed Process
|
||||
|
||||
### Step 1: Identify Domain
|
||||
|
||||
From user input, extract the main domain:
|
||||
|
||||
| User Input | Identified Domain |
|
||||
|------------------|---------------------|
|
||||
| "US crop data" | Agriculture (US) |
|
||||
| "stock market analysis" | Finance / Stock Market |
|
||||
| "global climate data" | Climate / Meteorology |
|
||||
| "economic indicators" | Economy / Macro |
|
||||
| "commodity data" | Trading / Commodities |
|
||||
|
||||
### Step 2: Search Available APIs
|
||||
|
||||
For the identified domain, use WebSearch to find public APIs:
|
||||
|
||||
**Search queries**:
|
||||
```
|
||||
"[domain] API free public data"
|
||||
"[domain] government API documentation"
|
||||
"best API for [domain] historical data"
|
||||
"[domain] open data sources"
|
||||
```
|
||||
|
||||
**Example (US agriculture)**:
|
||||
```bash
|
||||
WebSearch: "US agriculture API free historical data"
|
||||
WebSearch: "USDA API documentation"
|
||||
WebSearch: "agricultural statistics API United States"
|
||||
```
|
||||
|
||||
**Typical result**: 5-10 candidate APIs
|
||||
|
||||
### Step 3: Research Documentation
|
||||
|
||||
For each candidate API, use WebFetch to load:
|
||||
- Homepage/overview
|
||||
- Getting started guide
|
||||
- API reference
|
||||
- Rate limits and pricing
|
||||
|
||||
**Extract information**:
|
||||
|
||||
```markdown
|
||||
## API 1: [Name]
|
||||
|
||||
**URL**: [base URL]
|
||||
**Docs**: [docs URL]
|
||||
|
||||
**Authentication**:
|
||||
- Type: API key / OAuth / None
|
||||
- Cost: Free / Paid
|
||||
- How to obtain: [steps]
|
||||
|
||||
**Available Data**:
|
||||
- Temporal coverage: [from when to when]
|
||||
- Geographic coverage: [countries, regions]
|
||||
- Metrics: [list]
|
||||
- Granularity: [daily, monthly, annual]
|
||||
|
||||
**Limitations**:
|
||||
- Rate limit: [requests per day/hour]
|
||||
- Max records: [per request]
|
||||
- Throttling: [yes/no]
|
||||
|
||||
**Quality**:
|
||||
- Source: [official government / private]
|
||||
- Reliability: [high/medium/low]
|
||||
- Update frequency: [frequency]
|
||||
|
||||
**Documentation**:
|
||||
- Quality: [excellent/good/poor]
|
||||
|
||||
### Step 4: API Capability Inventory (NEW v2.0 - CRITICAL!)
|
||||
|
||||
**OBJECTIVE:** Ensure the skill uses 100% of API capabilities, not just the basics!
|
||||
|
||||
**LEARNING:** us-crop-monitor v1.0 used only CONDITION (1 of 5 NASS metrics).
|
||||
v2.0 had to add PROGRESS, YIELD, PRODUCTION, AREA (+3,500 lines of rework).
|
||||
|
||||
**Process:**
|
||||
|
||||
**Step 4.1: Complete Inventory**
|
||||
|
||||
For the chosen API, catalog ALL data types:
|
||||
|
||||
```markdown
|
||||
## Complete Inventory - {API Name}
|
||||
|
||||
**Available Metrics/Endpoints:**
|
||||
|
||||
| Endpoint/Metric | Returns | Granularity | Coverage | Value |
|
||||
|-----------------|---------------|---------------|-----------|-------|
|
||||
| {metric1} | {description} | {daily/weekly}| {geo} | ⭐⭐⭐⭐⭐ |
|
||||
| {metric2} | {description} | {monthly} | {geo} | ⭐⭐⭐⭐⭐ |
|
||||
| {metric3} | {description} | {annual} | {geo} | ⭐⭐⭐⭐ |
|
||||
...
|
||||
|
||||
**Real Example (NASS):**
|
||||
|
||||
| Metric Type | Data | Frequency | Value | Implement? |
|
||||
|----------------|--------------------| ----------|----------|------------|
|
||||
| CONDITION | Quality ratings | Weekly | ⭐⭐⭐⭐⭐ | ✅ YES |
|
||||
| PROGRESS | % planted/harvested| Weekly | ⭐⭐⭐⭐⭐ | ✅ YES |
|
||||
| YIELD | Bu/acre | Monthly | ⭐⭐⭐⭐⭐ | ✅ YES |
|
||||
| PRODUCTION | Total bushels | Monthly | ⭐⭐⭐⭐⭐ | ✅ YES |
|
||||
| AREA | Acres planted | Annual | ⭐⭐⭐⭐ | ✅ YES |
|
||||
| PRICE | $/bushel | Monthly | ⭐⭐⭐ | ⚪ v2.0 |
|
||||
```
|
||||
|
||||
**Step 4.2: Coverage Decision**
|
||||
|
||||
**GOLDEN RULE:**
|
||||
- If metric has ⭐⭐⭐⭐ or ⭐⭐⭐⭐⭐ value → Implement in v1.0
|
||||
- If API has 5 high-value metrics → Implement all 5!
|
||||
- Never leave >50% of API unused without strong justification
|
||||
|
||||
**Step 4.3: Document Decision**
|
||||
|
||||
In DECISIONS.md:
|
||||
```markdown
|
||||
## API Coverage Decision
|
||||
|
||||
API {name} offers {N} types of metrics.
|
||||
|
||||
**Implemented in v1.0 ({X} of {N}):**
|
||||
- {metric1} - {justification}
|
||||
- {metric2} - {justification}
|
||||
...
|
||||
|
||||
**Not implemented ({Y} of {N}):**
|
||||
- {metricZ} - {why not} (planned for v2.0)
|
||||
|
||||
**Coverage:** {X/N * 100}% = {evaluation}
|
||||
- If < 70%: Clearly explain why low coverage
|
||||
- If > 70%: ✅ Good coverage
|
||||
```
|
||||
|
||||
**Output of this phase:** Exact list of all `get_*()` methods to implement
|
||||
- Examples: [many/few/none]
|
||||
- SDKs: [Python/R/None]
|
||||
|
||||
**Ease of Use**:
|
||||
- Format: JSON / CSV / XML
|
||||
- Structure: [simple/complex]
|
||||
- Quirks: [any strange behavior?]
|
||||
```
|
||||
|
||||
### Step 4: Compare Options
|
||||
|
||||
Create comparison table:
|
||||
|
||||
| API | Coverage | Cost | Rate Limit | Quality | Docs | Ease | Score |
|
||||
|-----|-----------|-------|------------|-----------|------|------------|-------|
|
||||
| API 1 | ⭐⭐⭐⭐⭐ | Free | 1000/day | Official | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 9.2/10 |
|
||||
| API 2 | ⭐⭐⭐⭐ | $49/mo | Unlimited | Private | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 7.8/10 |
|
||||
| API 3 | ⭐⭐⭐ | Free | 100/day | Private | ⭐⭐ | ⭐⭐⭐ | 5.5/10 |
|
||||
|
||||
**Scoring criteria**:
|
||||
- Coverage (fit with need): 30% weight
|
||||
- Cost (prefer free): 20% weight
|
||||
- Rate limit (sufficient?): 15% weight
|
||||
- Quality (official > private): 15% weight
|
||||
- Documentation (facilitates implementation): 10% weight
|
||||
- Ease of use (format, structure): 10% weight
|
||||
|
||||
### Step 5: DECIDE
|
||||
|
||||
**Consider user constraints**:
|
||||
- Mentioned "free"? → Eliminate paid options
|
||||
- Mentioned "10+ years historical data"? → Check coverage
|
||||
- Mentioned "real-time"? → Prioritize streaming APIs
|
||||
|
||||
**Apply logic**:
|
||||
1. Eliminate APIs that violate constraints
|
||||
2. Of remaining, choose highest score
|
||||
3. If tie, prefer:
|
||||
- Official > private
|
||||
- Better documentation
|
||||
- Easier to use
|
||||
|
||||
**FINAL DECISION**:
|
||||
|
||||
```markdown
|
||||
## Selected API: [API Name]
|
||||
|
||||
**Score**: X.X/10
|
||||
|
||||
**Justification**:
|
||||
- ✅ Coverage: [specific details]
|
||||
- ✅ Cost: [free/paid + details]
|
||||
- ✅ Rate limit: [number] requests/day (sufficient for [estimated usage])
|
||||
- ✅ Quality: [official/private + reliability]
|
||||
- ✅ Documentation: [quality + examples]
|
||||
- ✅ Ease of use: [format, structure]
|
||||
|
||||
**Fit with requirements**:
|
||||
- Constraint 1 (e.g., free): ✅ Met
|
||||
- Constraint 2 (e.g., 10+ years history): ✅ Met (since [year])
|
||||
- Primary need (e.g., crop production): ✅ Covered
|
||||
|
||||
**Alternatives Considered**:
|
||||
|
||||
**API X**: Score 7.5/10
|
||||
- Rejected because: [specific reason]
|
||||
- Trade-off: [what we lose vs gain]
|
||||
|
||||
**API Y**: Score 6.2/10
|
||||
- Rejected because: [reason]
|
||||
|
||||
**Conclusion**:
|
||||
[API Name] is the best option because [1-2 sentence synthesis].
|
||||
```
|
||||
|
||||
### Step 6: Research Technical Details
|
||||
|
||||
After deciding, dive deep into documentation:
|
||||
|
||||
**Load via WebFetch**:
|
||||
- Getting started guide
|
||||
- Complete API reference
|
||||
- Authentication guide
|
||||
- Rate limiting details
|
||||
- Best practices
|
||||
|
||||
**Extract for implementation**:
|
||||
|
||||
```markdown
|
||||
## Technical Details - [API]
|
||||
|
||||
### Authentication
|
||||
|
||||
**Method**: API key in header
|
||||
**Header**: `X-Api-Key: YOUR_KEY`
|
||||
**Obtaining key**:
|
||||
1. [step 1]
|
||||
2. [step 2]
|
||||
3. [step 3]
|
||||
|
||||
### Main Endpoints
|
||||
|
||||
**Endpoint 1**: [Name]
|
||||
- **URL**: `GET https://api.example.com/v1/endpoint`
|
||||
- **Parameters**:
|
||||
- `param1` (required): [description, type, example]
|
||||
- `param2` (optional): [description, type, default]
|
||||
- **Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"meta": {...}
|
||||
}
|
||||
```
|
||||
- **Errors**:
|
||||
- 400: [when occurs, how to handle]
|
||||
- 401: [when occurs, how to handle]
|
||||
- 429: [rate limit, how to handle]
|
||||
|
||||
**Example request**:
|
||||
```bash
|
||||
curl -H "X-Api-Key: YOUR_KEY" \
|
||||
"https://api.example.com/v1/endpoint?param1=value"
|
||||
```
|
||||
|
||||
[Repeat for all relevant endpoints]
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
- Limit: [number] requests per [period]
|
||||
- Response headers:
|
||||
- `X-RateLimit-Limit`: Total limit
|
||||
- `X-RateLimit-Remaining`: Remaining requests
|
||||
- `X-RateLimit-Reset`: Reset timestamp
|
||||
- Behavior when exceeded: [429 error, throttling, ban?]
|
||||
- Best practice: [how to implement rate limiting]
|
||||
|
||||
### Quirks and Gotchas
|
||||
|
||||
**Quirk 1**: Values come as strings with formatting
|
||||
- Example: `"2,525,000"` instead of `2525000`
|
||||
- Solution: Remove commas before converting
|
||||
|
||||
**Quirk 2**: Suppressed data marked as "(D)"
|
||||
- Meaning: Withheld to avoid disclosing data
|
||||
- Solution: Treat as NULL, signal to user
|
||||
|
||||
**Quirk 3**: [other non-obvious behavior]
|
||||
- Solution: [how to handle]
|
||||
|
||||
### Performance Tips
|
||||
|
||||
- Historical data doesn't change → cache permanently
|
||||
- Recent data may be revised → short cache (7 days)
|
||||
- Use pagination parameters if large response
|
||||
- Make parallel requests when possible (respecting rate limit)
|
||||
```
|
||||
|
||||
### Step 7: Document for Later Use
|
||||
|
||||
Save everything in `references/api-guide.md` of the agent to be created.
|
||||
|
||||
## Discovery Examples
|
||||
|
||||
### Example 1: US Agriculture
|
||||
|
||||
**Input**: "US crop data"
|
||||
|
||||
**Research**:
|
||||
```
|
||||
WebSearch: "USDA API agricultural data"
|
||||
→ Found: NASS QuickStats, ERS, FAS
|
||||
|
||||
WebFetch: https://quickstats.nass.usda.gov/api
|
||||
→ Free, data since 1866, 1000/day rate limit
|
||||
|
||||
WebFetch: https://www.ers.usda.gov/developer/
|
||||
→ Free, economic focus, less granular
|
||||
|
||||
WebFetch: https://apps.fas.usda.gov/api
|
||||
→ International focus, not domestic
|
||||
```
|
||||
|
||||
**Comparison**:
|
||||
| API | Coverage (US domestic) | Cost | Production Data | Score |
|
||||
|-----|---------------------------|-------|-------------------|-------|
|
||||
| NASS | ⭐⭐⭐⭐⭐ (excellent) | Free | ⭐⭐⭐⭐⭐ | 9.5/10 |
|
||||
| ERS | ⭐⭐⭐⭐ (good) | Free | ⭐⭐⭐ (economic) | 7.0/10 |
|
||||
| FAS | ⭐⭐ (international) | Free | ⭐⭐ (global) | 4.0/10 |
|
||||
|
||||
**DECISION**: NASS QuickStats API
|
||||
- Best coverage for US domestic agriculture
|
||||
- Free with reasonable rate limit
|
||||
- Complete production, area, yield data
|
||||
|
||||
### Example 2: Stock Market
|
||||
|
||||
**Input**: "technical stock analysis"
|
||||
|
||||
**Research**:
|
||||
```
|
||||
WebSearch: "stock market API free historical data"
|
||||
→ Alpha Vantage, Yahoo Finance, IEX Cloud, Polygon.io
|
||||
|
||||
WebFetch: Alpha Vantage docs
|
||||
→ Free, 5 requests/min, 500/day
|
||||
|
||||
WebFetch: Yahoo Finance (yfinance)
|
||||
→ Free, unlimited but unofficial
|
||||
|
||||
WebFetch: IEX Cloud
|
||||
→ Freemium, good docs, 50k free credits/month
|
||||
```
|
||||
|
||||
**Comparison**:
|
||||
| API | Data | Cost | Rate Limit | Official | Score |
|
||||
|-----|-------|-------|------------|---------|-------|
|
||||
| Alpha Vantage | Complete | Free | 500/day | ⭐⭐⭐ | 8.0/10 |
|
||||
| Yahoo Finance | Complete | Free | Unlimited | ❌ Unofficial | 7.5/10 |
|
||||
| IEX Cloud | Excellent | Freemium | 50k/month | ⭐⭐⭐⭐ | 8.5/10 |
|
||||
|
||||
**DECISION**: IEX Cloud (free tier)
|
||||
- Official and reliable
|
||||
- 50k requests/month sufficient
|
||||
- Excellent documentation
|
||||
- Complete data (OHLCV + volume)
|
||||
|
||||
### Example 3: Global Climate
|
||||
|
||||
**Input**: "global climate data"
|
||||
|
||||
**Research**:
|
||||
```
|
||||
WebSearch: "weather API historical data global"
|
||||
→ NOAA, OpenWeather, Weather.gov, Meteostat
|
||||
|
||||
[Research each one...]
|
||||
```
|
||||
|
||||
**DECISION**: NOAA Climate Data Online (CDO) API
|
||||
- Official (US government)
|
||||
- Free
|
||||
- Global and historical coverage (1900+)
|
||||
- Rate limit: 1000/day
|
||||
|
||||
## Decision Documentation
|
||||
|
||||
Create `DECISIONS.md` file in agent:
|
||||
|
||||
```markdown
|
||||
# Architecture Decisions
|
||||
|
||||
## Date: [creation date]
|
||||
|
||||
## Phase 1: API Selection
|
||||
|
||||
### Chosen API
|
||||
|
||||
**[API Name]**
|
||||
|
||||
### Selection Process
|
||||
|
||||
**APIs Researched**: [list]
|
||||
|
||||
**Evaluation Criteria**:
|
||||
1. Data coverage (fit with need)
|
||||
2. Cost (preference for free)
|
||||
3. Rate limits (viability)
|
||||
4. Quality (official > private)
|
||||
5. Documentation (facilitates development)
|
||||
|
||||
### Comparison
|
||||
|
||||
[Comparison table]
|
||||
|
||||
### Final Justification
|
||||
|
||||
[2-3 paragraphs explaining why this API was chosen]
|
||||
|
||||
### Trade-offs
|
||||
|
||||
**What we gain**:
|
||||
- [benefit 1]
|
||||
- [benefit 2]
|
||||
|
||||
**What we lose** (vs alternatives):
|
||||
- [accepted limitation 1]
|
||||
- [accepted limitation 2]
|
||||
|
||||
### Technical Details
|
||||
|
||||
[Summary of endpoints, authentication, rate limits, etc]
|
||||
|
||||
**Complete documentation**: See `references/api-guide.md`
|
||||
```
|
||||
|
||||
## Phase 1 Checklist
|
||||
|
||||
Before proceeding to Phase 2, verify:
|
||||
|
||||
- [ ] Research completed (WebSearch + WebFetch)
|
||||
- [ ] Minimum 3 APIs compared
|
||||
- [ ] Decision made with clear justification
|
||||
- [ ] User constraints respected
|
||||
- [ ] Technical details extracted
|
||||
- [ ] DECISIONS.md created
|
||||
- [ ] Ready for analysis design
|
||||
244
references/phase2-design.md
Normal file
244
references/phase2-design.md
Normal file
|
|
@ -0,0 +1,244 @@
|
|||
# Phase 2: Analysis Design
|
||||
|
||||
## Objective
|
||||
|
||||
**DEFINE** autonomously which analyses the agent will perform and how.
|
||||
|
||||
## Detailed Process
|
||||
|
||||
### Step 1: Brainstorm Use Cases
|
||||
|
||||
From the workflow described by the user, think of typical questions they will ask.
|
||||
|
||||
**Technique**: "If I were this user, what would I ask?"
|
||||
|
||||
**Example (US agriculture)**:
|
||||
|
||||
User said: "download crop data, compare year vs year, make rankings"
|
||||
|
||||
**Questions they likely ask**:
|
||||
1. "What's the corn production in 2023?"
|
||||
2. "How's soybean compared to last year?"
|
||||
3. "Did production grow or fall?"
|
||||
4. "How much did it grow?"
|
||||
5. "Does growth come from area or productivity?"
|
||||
6. "Which states produce most wheat?"
|
||||
7. "Top 5 soybean producers"
|
||||
8. "Did the ranking change vs last year?"
|
||||
9. "Production trend last 5 years?"
|
||||
10. "Forecast for next year?"
|
||||
11. "Average US yield"
|
||||
12. "Which state has best productivity?"
|
||||
13. "Did planted area increase?"
|
||||
14. "Compare Midwest vs South"
|
||||
15. "Production by region"
|
||||
|
||||
**Objective**: List 15-20 typical questions
|
||||
|
||||
### Step 2: Group by Analysis Type
|
||||
|
||||
Group similar questions:
|
||||
|
||||
**Group 1: Simple Queries** (fetching + formatting)
|
||||
- Questions: 1, 11, 13
|
||||
- Required analysis: **Data Retrieval**
|
||||
- Complexity: Low
|
||||
|
||||
**Group 2: Temporal Comparisons** (YoY)
|
||||
- Questions: 2, 3, 4, 5
|
||||
- Required analysis: **YoY Comparison + Decomposition**
|
||||
- Complexity: Medium
|
||||
|
||||
**Group 3: Rankings** (sorting + share)
|
||||
- Questions: 6, 7, 8
|
||||
- Required analysis: **State Ranking**
|
||||
- Complexity: Medium
|
||||
|
||||
**Group 4: Trends** (time series)
|
||||
- Questions: 9
|
||||
- Required analysis: **Trend Analysis**
|
||||
- Complexity: Medium-High
|
||||
|
||||
**Group 5: Projections** (forecasting)
|
||||
- Questions: 10
|
||||
- Required analysis: **Forecasting**
|
||||
- Complexity: High
|
||||
|
||||
**Group 6: Geographic Aggregations**
|
||||
- Questions: 12, 14, 15
|
||||
- Required analysis: **Regional Aggregation**
|
||||
- Complexity: Medium
|
||||
|
||||
### Step 3: Prioritize Analyses
|
||||
|
||||
**Prioritization criteria**:
|
||||
1. **Frequency of use** (based on described workflow)
|
||||
2. **Analytical value** (insight vs effort)
|
||||
3. **Implementation complexity** (easier first)
|
||||
4. **Dependencies** (does one analysis depend on another?)
|
||||
|
||||
**Scoring**:
|
||||
|
||||
| Analysis | Frequency | Value | Ease | Score |
|
||||
|---------|------------|-------|------------|-------|
|
||||
| YoY Comparison | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 9.3/10 |
|
||||
| State Ranking | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 9.3/10 |
|
||||
| Regional Agg | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 8.0/10 |
|
||||
| Trend Analysis | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 7.3/10 |
|
||||
| Data Retrieval | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 8.3/10 |
|
||||
| Forecasting | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | 5.3/10 |
|
||||
|
||||
**DECISION**: Implement top 5
|
||||
1. YoY Comparison (9.3)
|
||||
2. State Ranking (9.3)
|
||||
3. Data Retrieval (8.3)
|
||||
4. Regional Aggregation (8.0)
|
||||
5. Trend Analysis (7.3)
|
||||
|
||||
**Don't implement initially** (can add later):
|
||||
- Forecasting (5.3) - complex, occasional use
|
||||
|
||||
### Step 4: Specify Each Analysis
|
||||
|
||||
For each selected analysis:
|
||||
|
||||
```markdown
|
||||
## Analysis: [Name]
|
||||
|
||||
**Objective**: [What it does in 1 sentence]
|
||||
|
||||
**When to use**: [Types of questions that trigger it]
|
||||
|
||||
**Required inputs**:
|
||||
- Input 1: [type, description]
|
||||
- Input 2: [type, description]
|
||||
|
||||
**Expected outputs**:
|
||||
- Output 1: [type, description]
|
||||
- Output 2: [type, description]
|
||||
|
||||
**Methodology**:
|
||||
|
||||
[Explanation in natural language]
|
||||
|
||||
**Formulas**:
|
||||
```
|
||||
Formula 1 = ...
|
||||
Formula 2 = ...
|
||||
```
|
||||
|
||||
**Data transformations**:
|
||||
1. [Transformation 1]
|
||||
2. [Transformation 2]
|
||||
|
||||
**Validations**:
|
||||
- Validation 1: [criteria]
|
||||
- Validation 2: [criteria]
|
||||
|
||||
**Interpretation**:
|
||||
- If result > X: [interpretation]
|
||||
- If result < Y: [interpretation]
|
||||
|
||||
**Concrete example**:
|
||||
|
||||
Input:
|
||||
- Commodity: Corn
|
||||
- Year current: 2023
|
||||
- Year previous: 2022
|
||||
|
||||
Processing:
|
||||
- Fetch 2023 production: 15.3B bu
|
||||
- Fetch 2022 production: 13.7B bu
|
||||
- Calculate: (15.3 - 13.7) / 13.7 = +11.7%
|
||||
|
||||
Output:
|
||||
```json
|
||||
{
|
||||
"commodity": "CORN",
|
||||
"year_current": 2023,
|
||||
"year_previous": 2022,
|
||||
"production_current": 15.3,
|
||||
"production_previous": 13.7,
|
||||
"change_absolute": 1.6,
|
||||
"change_percent": 11.7,
|
||||
"interpretation": "significant_increase"
|
||||
}
|
||||
```
|
||||
|
||||
Response to user:
|
||||
"Corn production grew 11.7% in 2023 vs 2022 (15.3B bu vs 13.7B bu)."
|
||||
```
|
||||
|
||||
### Step 5: Specify Methodologies
|
||||
|
||||
For quantitative analyses, detail methodology:
|
||||
|
||||
**Example: YoY Decomposition**
|
||||
|
||||
```markdown
|
||||
### Growth Decomposition
|
||||
|
||||
**Objective**: Understand how much of production growth comes from:
|
||||
- Planted area increase (extensive)
|
||||
- Productivity/yield increase (intensive)
|
||||
|
||||
**Mathematics**:
|
||||
|
||||
Production = Area × Yield
|
||||
|
||||
Δ Production = Δ Area × Yield(t-1) + Area(t-1) × Δ Yield + Δ Area × Δ Yield
|
||||
|
||||
Interaction term usually small, so approximation:
|
||||
|
||||
Δ Production ≈ Δ Area × Yield(t-1) + Area(t-1) × Δ Yield
|
||||
|
||||
**Percentage contributions**:
|
||||
|
||||
Contrib_Area = (Δ Area% / Δ Production%) × 100
|
||||
Contrib_Yield = (Δ Yield% / Δ Production%) × 100
|
||||
|
||||
**Interpretation**:
|
||||
|
||||
- Contrib_Area > 60%: **Extensive growth**
|
||||
→ Area expansion is main driver
|
||||
→ Agricultural frontier expanding
|
||||
|
||||
- Contrib_Yield > 60%: **Intensive growth**
|
||||
→ Technology improvement is main driver
|
||||
→ Productivity/ha increasing
|
||||
|
||||
- Both ~50%: **Balanced growth**
|
||||
|
||||
**Validation**:
|
||||
|
||||
Check: Production(t) ≈ Area(t) × Yield(t) (margin 1%)
|
||||
Check: Contrib_Area + Contrib_Yield ≈ 100% (margin 5%)
|
||||
|
||||
**Example**:
|
||||
|
||||
Soybeans 2023 vs 2022:
|
||||
- Δ Production: +12.4%
|
||||
- Δ Area: +6.1%
|
||||
- Δ Yield: +7.6%
|
||||
|
||||
Contrib_Area = (6.1 / 12.4) × 100 = 49%
|
||||
Contrib_Yield = (7.6 / 12.4) × 100 = 61%
|
||||
|
||||
**Interpretation**: Intensive growth (61% from yield).
|
||||
Technology and management improving.
|
||||
```
|
||||
|
||||
### Step 6: Document Analyses
|
||||
|
||||
Save all specifications in `references/analysis-methods.md` of the agent.
|
||||
|
||||
## Phase 2 Checklist
|
||||
|
||||
- [ ] 15+ typical questions listed
|
||||
- [ ] Questions grouped by analysis type
|
||||
- [ ] 4-6 analyses prioritized (with scoring)
|
||||
- [ ] Each analysis specified (objective, inputs, outputs, methodology)
|
||||
- [ ] Methodologies detailed with formulas
|
||||
- [ ] Validations defined
|
||||
- [ ] Interpretations specified
|
||||
- [ ] Concrete examples included
|
||||
351
references/phase3-architecture.md
Normal file
351
references/phase3-architecture.md
Normal file
|
|
@ -0,0 +1,351 @@
|
|||
# Phase 3: Architecture and Structuring
|
||||
|
||||
## Objective
|
||||
|
||||
**STRUCTURE** the agent optimally: folders, files, responsibilities, cache, performance.
|
||||
|
||||
## Detailed Process
|
||||
|
||||
### Step 1: Define Agent Name
|
||||
|
||||
Based on domain and objective, create descriptive name:
|
||||
|
||||
**Format**: `domain-objective-type`
|
||||
|
||||
**Examples**:
|
||||
- US Agriculture → `nass-usda-agriculture`
|
||||
- Stock analysis → `stock-technical-analysis`
|
||||
- Global climate → `noaa-climate-analysis`
|
||||
- Brazil CONAB → `conab-crop-yield-analysis`
|
||||
|
||||
**Rules**:
|
||||
- lowercase
|
||||
- hyphens to separate words
|
||||
- maximum 50 characters
|
||||
- descriptive but concise
|
||||
|
||||
### Step 2: Directory Structure
|
||||
|
||||
**Decision**: How many levels of organization?
|
||||
|
||||
**Option A - Simple** (small agents):
|
||||
```
|
||||
agent-name/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json ← REQUIRED for installation!
|
||||
├── SKILL.md
|
||||
├── scripts/
|
||||
│ └── main.py
|
||||
├── references/
|
||||
│ └── guide.md
|
||||
└── assets/
|
||||
└── config.json
|
||||
```
|
||||
|
||||
**Option B - Organized** (medium agents):
|
||||
```
|
||||
agent-name/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json ← REQUIRED for installation!
|
||||
├── SKILL.md
|
||||
├── scripts/
|
||||
│ ├── fetch.py
|
||||
│ ├── parse.py
|
||||
│ ├── analyze.py
|
||||
│ └── utils/
|
||||
│ ├── cache.py
|
||||
│ └── validators.py
|
||||
├── references/
|
||||
│ ├── api-guide.md
|
||||
│ └── methodology.md
|
||||
└── assets/
|
||||
└── config.json
|
||||
```
|
||||
|
||||
**Option C - Complete** (complex agents):
|
||||
```
|
||||
agent-name/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json ← REQUIRED for installation!
|
||||
├── SKILL.md
|
||||
├── scripts/
|
||||
│ ├── core/
|
||||
│ │ ├── fetch_[source].py
|
||||
│ │ ├── parse_[source].py
|
||||
│ │ └── analyze_[source].py
|
||||
│ ├── models/
|
||||
│ │ ├── forecasting.py
|
||||
│ │ └── ml_models.py
|
||||
│ └── utils/
|
||||
│ ├── cache_manager.py
|
||||
│ ├── rate_limiter.py
|
||||
│ └── validators.py
|
||||
├── references/
|
||||
│ ├── api/
|
||||
│ │ └── [api-name]-guide.md
|
||||
│ ├── methods/
|
||||
│ │ └── analysis-methods.md
|
||||
│ └── troubleshooting.md
|
||||
├── assets/
|
||||
│ ├── config.json
|
||||
│ └── metadata.json
|
||||
└── data/
|
||||
├── raw/
|
||||
├── processed/
|
||||
├── cache/
|
||||
└── analysis/
|
||||
```
|
||||
|
||||
**Choose based on**:
|
||||
- Number of scripts (1-2 → A, 3-5 → B, 6+ → C)
|
||||
- Analysis complexity
|
||||
- Prefer starting with B, expand to C if needed
|
||||
|
||||
### Step 3: Define Script Responsibilities
|
||||
|
||||
**Principle**: Separation of Concerns
|
||||
|
||||
**Typical scripts**:
|
||||
|
||||
**1. fetch_[source].py**
|
||||
- **Responsibility**: API requests, authentication, rate limiting
|
||||
- **Input**: Query parameters (commodity, year, etc)
|
||||
- **Output**: Raw JSON from API
|
||||
- **Does NOT**: Parse, transform, analyze
|
||||
- **Size**: 200-300 lines
|
||||
|
||||
**2. parse_[source].py**
|
||||
- **Responsibility**: Parsing, cleaning, validation
|
||||
- **Input**: API JSON
|
||||
- **Output**: Structured DataFrame
|
||||
- **Does NOT**: Fetch, analyze
|
||||
- **Size**: 150-200 lines
|
||||
|
||||
**3. analyze_[source].py**
|
||||
- **Responsibility**: All analyses (YoY, ranking, etc)
|
||||
- **Input**: Clean DataFrame
|
||||
- **Output**: Dict with results
|
||||
- **Does NOT**: Fetch, parse
|
||||
- **Size**: 300-500 lines (all analyses)
|
||||
|
||||
**Typical utils**:
|
||||
|
||||
**cache_manager.py**:
|
||||
- Manage response cache
|
||||
- Differentiated TTL
|
||||
- ~100-150 lines
|
||||
|
||||
**rate_limiter.py**:
|
||||
- Control rate limit
|
||||
- Persistent counter
|
||||
- Alerts
|
||||
- ~100-150 lines
|
||||
|
||||
**validators.py**:
|
||||
- Data validations
|
||||
- Consistency checks
|
||||
- ~100-150 lines
|
||||
|
||||
**unit_converter.py** (if needed):
|
||||
- Unit conversions
|
||||
- ~50-100 lines
|
||||
|
||||
### Step 4: Plan References
|
||||
|
||||
**Typical files**:
|
||||
|
||||
**api-guide.md** (~1500 words):
|
||||
- How to get API key
|
||||
- Main endpoints with examples
|
||||
- Important parameters
|
||||
- Response format
|
||||
- Limitations and quirks
|
||||
- API troubleshooting
|
||||
|
||||
**analysis-methods.md** (~2000 words):
|
||||
- Each analysis explained
|
||||
- Mathematical formulas
|
||||
- Interpretations
|
||||
- Validations
|
||||
- Concrete examples
|
||||
|
||||
**troubleshooting.md** (~1000 words):
|
||||
- Common problems
|
||||
- Step-by-step solutions
|
||||
- FAQs
|
||||
|
||||
**domain-context.md** (optional, ~1000 words):
|
||||
- Domain context
|
||||
- Terminology
|
||||
- Important concepts
|
||||
- Benchmarks
|
||||
|
||||
### Step 5: Plan Assets
|
||||
|
||||
**config.json**:
|
||||
- API settings (URL, rate limits, timeouts)
|
||||
- Cache settings (TTLs, directories)
|
||||
- Analysis defaults
|
||||
- Validation thresholds
|
||||
|
||||
**Typical structure**:
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"base_url": "...",
|
||||
"api_key_env": "VAR_NAME",
|
||||
"rate_limit_per_day": 1000,
|
||||
"timeout_seconds": 30
|
||||
},
|
||||
"cache": {
|
||||
"enabled": true,
|
||||
"dir": "data/cache",
|
||||
"ttl_historical_days": 365,
|
||||
"ttl_current_days": 7
|
||||
},
|
||||
"defaults": {
|
||||
"param1": "value1"
|
||||
},
|
||||
"validation": {
|
||||
"threshold1": 0.01
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**metadata.json** (if needed):
|
||||
- Domain-specific metadata
|
||||
- Mappings (aliases)
|
||||
- Conversions (units)
|
||||
- Groupings (regions)
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"commodities": {
|
||||
"CORN": {
|
||||
"aliases": ["corn", "maize"],
|
||||
"unit": "BU",
|
||||
"conversion_to_mt": 0.0254
|
||||
}
|
||||
},
|
||||
"regions": {
|
||||
"MIDWEST": ["IA", "IL", "IN", "OH"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6: Cache Strategy
|
||||
|
||||
**Decision**: What to cache and for how long?
|
||||
|
||||
**General rule**:
|
||||
- **Historical data** (year < current): Permanent cache (365+ days)
|
||||
- **Current year data**: Short cache (7 days - may be revised)
|
||||
- **Metadata** (commodity lists, states): Permanent cache
|
||||
|
||||
**Implementation**:
|
||||
- Cache by key (parameter hash)
|
||||
- Check age before using
|
||||
- Fallback to expired cache if API fails
|
||||
|
||||
**Example**:
|
||||
```python
|
||||
def get_cache_ttl(year: int) -> timedelta:
|
||||
"""Determine cache TTL based on year"""
|
||||
current_year = datetime.now().year
|
||||
|
||||
if year < current_year:
|
||||
# Historical: cache for 1 year (effectively permanent)
|
||||
return timedelta(days=365)
|
||||
else:
|
||||
# Current year: cache for 7 days (may be revised)
|
||||
return timedelta(days=7)
|
||||
```
|
||||
|
||||
### Step 7: Rate Limiting Strategy
|
||||
|
||||
**Decision**: How to control rate limits?
|
||||
|
||||
**Components**:
|
||||
1. **Persistent counter** (file/DB)
|
||||
2. **Pre-request verification**
|
||||
3. **Alerts** (when near limit)
|
||||
4. **Blocking** (when limit reached)
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
class RateLimiter:
|
||||
def __init__(self, max_requests: int, period_seconds: int):
|
||||
self.max_requests = max_requests
|
||||
self.period = period_seconds
|
||||
self.counter_file = Path("data/cache/rate_limit_counter.json")
|
||||
|
||||
def allow_request(self) -> bool:
|
||||
"""Check if request is allowed"""
|
||||
count = self._get_current_count()
|
||||
|
||||
if count >= self.max_requests:
|
||||
return False
|
||||
|
||||
# Warn when near limit
|
||||
if count > self.max_requests * 0.9:
|
||||
print(f"⚠️ Rate limit: {count}/{self.max_requests} requests used")
|
||||
|
||||
return True
|
||||
|
||||
def record_request(self):
|
||||
"""Record that request was made"""
|
||||
count = self._get_current_count()
|
||||
self._save_count(count + 1)
|
||||
```
|
||||
|
||||
### Step 8: Document Architecture
|
||||
|
||||
Create section in DECISIONS.md:
|
||||
|
||||
```markdown
|
||||
## Phase 3: Architecture
|
||||
|
||||
### Chosen Structure
|
||||
|
||||
```
|
||||
[Directory tree]
|
||||
```
|
||||
|
||||
**Justification**:
|
||||
- Separate scripts for modularity
|
||||
- Utils for reusable code
|
||||
- References for progressive disclosure
|
||||
- Data/ to separate raw vs processed
|
||||
|
||||
### Defined Scripts
|
||||
|
||||
**fetch_[source].py** (280 lines estimated):
|
||||
- Responsibility: [...]
|
||||
- Input/Output: [...]
|
||||
|
||||
[For each script...]
|
||||
|
||||
### Cache Strategy
|
||||
|
||||
- Historical: Permanent cache
|
||||
- Current: 7 day cache
|
||||
- Justification: [historical data doesn't change]
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
- Method: [persistent counter]
|
||||
- Limits: [1000/day]
|
||||
- Alerts: [>90% usage]
|
||||
```
|
||||
|
||||
## Phase 3 Checklist
|
||||
|
||||
- [ ] Agent name defined
|
||||
- [ ] Directory structure chosen (A/B/C)
|
||||
- [ ] Responsibilities of each script defined
|
||||
- [ ] References planned (which files, content)
|
||||
- [ ] Assets planned (which configs, structure)
|
||||
- [ ] Cache strategy defined (what, TTL)
|
||||
- [ ] Rate limiting strategy defined
|
||||
- [ ] Architecture documented in DECISIONS.md
|
||||
465
references/phase4-detection.md
Normal file
465
references/phase4-detection.md
Normal file
|
|
@ -0,0 +1,465 @@
|
|||
# Phase 4: Automatic Detection
|
||||
|
||||
## Objective
|
||||
|
||||
**DETERMINE** keywords and create description so Claude Code activates the skill automatically.
|
||||
|
||||
## Detailed Process
|
||||
|
||||
### Step 1: List Domain Entities
|
||||
|
||||
Identify all relevant entities that users may mention:
|
||||
|
||||
**Entity categories**:
|
||||
|
||||
**1. Organizations/Sources**
|
||||
- Organization names (USDA, CONAB, NOAA, IMF)
|
||||
- Acronyms (NASS, ERS, FAS)
|
||||
- Full names (National Agricultural Statistics Service)
|
||||
|
||||
**2. Main Objects**
|
||||
- For agriculture: commodities (corn, soybeans, wheat)
|
||||
- For finance: instruments (stocks, bonds, options)
|
||||
- For climate: metrics (temperature, precipitation)
|
||||
|
||||
**3. Geography**
|
||||
- Countries (US, Brazil, China)
|
||||
- Regions (Midwest, Centro-Oeste, Southeast)
|
||||
- States/Provinces (Iowa, Mato Grosso, Texas)
|
||||
|
||||
**4. Metrics**
|
||||
- Production, area, yield, price
|
||||
- Revenue, profit, growth
|
||||
- Temperature, rainfall, humidity
|
||||
|
||||
**5. Temporality**
|
||||
- Years, seasons, quarters, months
|
||||
- Current, historical, forecast
|
||||
- YoY, QoQ, MoM
|
||||
|
||||
**Example (US agriculture)**:
|
||||
|
||||
```markdown
|
||||
**Organizations**:
|
||||
- USDA, NASS, National Agricultural Statistics Service
|
||||
- Department of Agriculture
|
||||
- QuickStats
|
||||
|
||||
**Commodities**:
|
||||
- Corn, soybeans, wheat
|
||||
- Cotton, rice, sorghum
|
||||
- Barley, oats, hay, peanuts
|
||||
- [list all major ones - 20+]
|
||||
|
||||
**Geography**:
|
||||
- US, United States, national
|
||||
- States: Iowa, Illinois, Nebraska, Kansas, Texas, etc [list top 15]
|
||||
- Regions: Midwest, Great Plains, Southeast, etc
|
||||
|
||||
**Metrics**:
|
||||
- Production, area planted, area harvested
|
||||
- Yield, productivity
|
||||
- Price received, value of production
|
||||
- Inventory, stocks
|
||||
|
||||
**Temporality**:
|
||||
- Year, season, crop year
|
||||
- Current, latest, this year, last year
|
||||
- Historical, trend, past 5 years
|
||||
- Forecast, projection, outlook
|
||||
```
|
||||
|
||||
### Step 2: List Actions/Verbs
|
||||
|
||||
Which verbs does the user use to request analyses?
|
||||
|
||||
**Categories**:
|
||||
|
||||
**Query (fetch information)**:
|
||||
- What is, how much, show me, get
|
||||
- Tell me, find, retrieve
|
||||
|
||||
**Compare**:
|
||||
- Compare, versus, vs, against
|
||||
- Difference, change, growth
|
||||
- Higher, lower, better, worse
|
||||
|
||||
**Rank (sort)**:
|
||||
- Top, best, leading, biggest
|
||||
- Rank, ranking, list
|
||||
- Which states, which countries
|
||||
|
||||
**Analyze**:
|
||||
- Analyze, analysis
|
||||
- Trend, pattern, evolution
|
||||
- Breakdown, decompose, explain
|
||||
|
||||
**Forecast (project)**:
|
||||
- Predict, project, forecast
|
||||
- Outlook, expectation, estimate
|
||||
- Future, next year, coming season
|
||||
|
||||
**Visualize**:
|
||||
- Plot, chart, graph, visualize
|
||||
- Show chart, generate graph
|
||||
|
||||
### Step 2.5: Generate Exhaustive Keywords (NEW v2.0 - CRITICAL!)
|
||||
|
||||
**OBJECTIVE:** Generate 60+ keywords to ensure correct activation in ALL relevant queries.
|
||||
|
||||
**LEARNING:** us-crop-monitor v1.0 had ~20 keywords. Missing "yield", "harvest", "production" → Claude Code didn't activate for those queries. v2.0 expanded to 60+ keywords.
|
||||
|
||||
**Mandatory Process:**
|
||||
|
||||
**Step A: Keywords per API Metric**
|
||||
|
||||
For EACH metric/endpoint the skill implements, generate keywords:
|
||||
|
||||
```markdown
|
||||
Metric 1: CONDITION (quality ratings)
|
||||
Primary keywords: condition, conditions, quality, ratings
|
||||
Secondary keywords: status, health, state
|
||||
Technical keywords: excellent, good, fair, poor
|
||||
Action keywords: rate, rated, rating, classify
|
||||
Portuguese: condição, condições, qualidade, estado, classificação
|
||||
→ Total: ~15 keywords
|
||||
|
||||
Metric 2: PROGRESS (% planted/harvested)
|
||||
Primary keywords: progress, harvest, planted, harvested
|
||||
Secondary keywords: planting, harvesting, completion
|
||||
Technical keywords: percentage, percent, %
|
||||
Action keywords: advancing, complete, completed
|
||||
Portuguese: progresso, plantio, colheita, plantado, colhido
|
||||
→ Total: ~15 keywords
|
||||
|
||||
Metric 3: YIELD (productivity)
|
||||
Primary keywords: yield, productivity, performance
|
||||
Technical keywords: bushels per acre, bu/acre, bu/ac
|
||||
Secondary keywords: output per unit
|
||||
Portuguese: rendimento, produtividade, bushels por acre
|
||||
→ Total: ~12 keywords
|
||||
|
||||
... Repeat for ALL implemented metrics
|
||||
```
|
||||
|
||||
**Rule:** Each metric = minimum 10 unique keywords
|
||||
|
||||
**Step B: Categorize Keywords by Type**
|
||||
|
||||
```markdown
|
||||
### Keyword Matrix - {Skill Name}
|
||||
|
||||
**1. Main Entities** (20+ keywords)
|
||||
- Official name: {entity}
|
||||
- Variations: {variations}
|
||||
- Singular + plural
|
||||
- Acronyms: {acronyms}
|
||||
- Full names: {full names}
|
||||
- Portuguese: {portuguese terms}
|
||||
|
||||
**2. Metrics - ONE SECTION PER API METRIC!** (30+ keywords)
|
||||
- Metric 1: {list 10-15 keywords}
|
||||
- Metric 2: {list 10-15 keywords}
|
||||
- Metric 3: {list 10-15 keywords}
|
||||
...
|
||||
|
||||
**3. Actions/Verbs** (20+ keywords)
|
||||
- Query: what, how, show, get, tell, find, retrieve
|
||||
- Compare: compare, vs, versus, against, difference
|
||||
- Rank: top, best, rank, leading, biggest
|
||||
- Analyze: analyze, trend, pattern, evolution
|
||||
- Report: report, dashboard, summary, overview
|
||||
- Portuguese: comparar, ranking, análise, relatório
|
||||
|
||||
**4. Temporal Qualifiers** (15+ keywords)
|
||||
- Current: current, now, today, latest, recent, atual, agora, hoje
|
||||
- Historical: historical, past, previous, last year, histórico
|
||||
- Comparative: this year vs last year, YoY, year-over-year
|
||||
- Forecast: forecast, projection, estimate, outlook, previsão
|
||||
|
||||
**5. Geographic Qualifiers** (15+ keywords)
|
||||
- National: national, US, United States, country-wide
|
||||
- Regional: region, Midwest, South, regional
|
||||
- State: state, by state, state-level, estado
|
||||
- Specific names: Iowa, Illinois, Nebraska, ...
|
||||
|
||||
**6. Data Context** (10+ keywords)
|
||||
- Source: {API name}, {organization}, {data source}
|
||||
- Type: data, statistics, metrics, indicators, dados
|
||||
```
|
||||
|
||||
**Goal:** Total 60-80 unique keywords!
|
||||
|
||||
**Step C: Test Coverage Matrix**
|
||||
|
||||
For each analysis function, generate 10 different queries:
|
||||
|
||||
```markdown
|
||||
Function: harvest_progress_report()
|
||||
|
||||
Query variations (test coverage):
|
||||
1. "What's the corn harvest progress?" ✅ harvest, progress
|
||||
2. "How much corn has been harvested?" ✅ harvested
|
||||
3. "Percent corn harvested?" ✅ percent, harvested
|
||||
4. "Harvest completion status?" ✅ harvest, completion, status
|
||||
5. "Progresso de colheita do milho?" ✅ progresso, colheita
|
||||
6. "Quanto foi colhido?" ✅ colhido
|
||||
7. "Harvest advancement?" ✅ harvest, advancement
|
||||
8. "How advanced is harvest?" ✅ harvest, advanced
|
||||
9. "Colheita completa?" ✅ colheita
|
||||
10. "Percentage complete harvest?" ✅ percentage, harvest
|
||||
|
||||
ALL keywords present in description? → Verify!
|
||||
```
|
||||
|
||||
**Do this for ALL 11 functions** = 110 query variations tested!
|
||||
|
||||
### Step 3: List Question Variations
|
||||
|
||||
For each analysis type, how can user ask?
|
||||
|
||||
**YoY Comparison**:
|
||||
- "Compare X this year vs last year"
|
||||
- "How does X compare to last year"
|
||||
- "Is X up or down from last year"
|
||||
- "X growth rate"
|
||||
- "X change YoY"
|
||||
- "X vs previous year"
|
||||
- "Did X increase or decrease"
|
||||
|
||||
**Ranking**:
|
||||
- "Top states for X"
|
||||
- "Which states produce most X"
|
||||
- "Leading X producers"
|
||||
- "Best X production"
|
||||
- "Biggest X producers"
|
||||
- "Ranking of X"
|
||||
- "List top 10 X"
|
||||
|
||||
**Trend**:
|
||||
- "X trend last N years"
|
||||
- "How has X changed over time"
|
||||
- "X evolution"
|
||||
- "Historical X data"
|
||||
- "X growth rate historical"
|
||||
- "Long term trend of X"
|
||||
|
||||
**Simple Query**:
|
||||
- "What is X production"
|
||||
- "X production in [year]"
|
||||
- "How much X"
|
||||
- "X data"
|
||||
- "Current X"
|
||||
|
||||
### Step 4: Define Negative Scope
|
||||
|
||||
**Important**: What should NOT activate?
|
||||
|
||||
Avoid false positives (skill activates when it shouldn't).
|
||||
|
||||
**Technique**: Think of similar questions but OUT of scope.
|
||||
|
||||
**Example (US agriculture)**:
|
||||
|
||||
❌ **DO NOT activate for**:
|
||||
- Futures market prices
|
||||
- "CBOT corn futures price"
|
||||
- "Soybean futures December contract"
|
||||
- Reason: Skill is USDA data (physical production), not trading
|
||||
|
||||
- Other countries' agriculture
|
||||
- "Brazil soybean production"
|
||||
- "Argentina corn exports"
|
||||
- Reason: Skill is US only
|
||||
|
||||
- Consumption/demand
|
||||
- "US corn consumption"
|
||||
- "Soybean demand forecast"
|
||||
- Reason: NASS has production, not consumption
|
||||
|
||||
- Private company data
|
||||
- "Monsanto corn seed sales"
|
||||
- "Cargill soybean crush"
|
||||
- Reason: Corporate data, not national statistics
|
||||
|
||||
**Document**:
|
||||
```markdown
|
||||
## Skill Scope
|
||||
|
||||
### ✅ WITHIN scope:
|
||||
- Physical crop production in US
|
||||
- Planted/harvested area
|
||||
- Yield/productivity
|
||||
- Prices RECEIVED by farmers (farm gate)
|
||||
- Inventories
|
||||
- Historical and current data
|
||||
- Comparisons, rankings, trends
|
||||
|
||||
### ❌ OUT of scope:
|
||||
- Futures market prices (CBOT, CME)
|
||||
- Agriculture outside US
|
||||
- Consumption/demand
|
||||
- Private company data
|
||||
- Market price forecasting
|
||||
```
|
||||
|
||||
### Step 5: Create Precise Description (Updated v2.0)
|
||||
|
||||
**NEW RULE:** Description must contain ALL 60+ identified keywords!
|
||||
|
||||
**Expanded Template:**
|
||||
|
||||
```yaml
|
||||
description: This skill should be used when the user asks about
|
||||
{domain} ({main entities with variations}). Automatically activates
|
||||
for queries about {metric1} ({metric1 keywords}), {metric2}
|
||||
({metric2 keywords}), {metric3} ({metric3 keywords}), {metric4}
|
||||
({metric4 keywords}), {metric5} ({metric5 keywords}), {actions_list},
|
||||
{temporal qualifiers}, {geographic qualifiers}, comparisons
|
||||
{comparison types}, rankings, trends, {data source} data,
|
||||
comprehensive reports, and dashboards. Uses {language} with {API name}
|
||||
to fetch real data on {complete list of all metrics}.
|
||||
```
|
||||
|
||||
**Mandatory components**:
|
||||
1. ✅ **Domain** with entities (corn, soybeans, wheat - not just "crops")
|
||||
2. ✅ **EACH API metric** explicitly mentioned
|
||||
3. ✅ **Synonyms** in parentheses (harvest = colheita, yield = rendimento)
|
||||
4. ✅ **Actions** covered (compare, rank, analyze, report)
|
||||
5. ✅ **Temporal context** (current, today, year-over-year)
|
||||
6. ✅ **Geographic** context (states, regions, national)
|
||||
7. ✅ **Data source** (USDA NASS, etc.)
|
||||
8. ✅ **Portuguese + English** keywords mixed
|
||||
|
||||
**Real size:** 300-500 characters (yes, larger than "recommended" - but necessary!)
|
||||
|
||||
**Real Example (us-crop-monitor v2.0):**
|
||||
```yaml
|
||||
description: This skill should be used when the user asks about
|
||||
agricultural crops in the United States (soybeans, corn, wheat).
|
||||
Automatically activates for queries about crop conditions (condições),
|
||||
crop progress (progresso de plantio/colheita), harvest progress
|
||||
(progresso de colheita), planting progress (plantio), yield
|
||||
(produtividade/rendimento em bushels per acre), production (produção
|
||||
total em bushels), area planted (área plantada), area harvested
|
||||
(área colhida), acres, forecasts (estimativas), crop monitoring,
|
||||
weekly comparisons (week-over-week) or annual (year-over-year),
|
||||
state producer rankings, trend analyses, USDA NASS data, comprehensive
|
||||
reports, and crop dashboards. Uses Python with NASS API to fetch
|
||||
real data on condition, progress, productivity, production and area.
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- Entities: soybeans, corn, wheat (3)
|
||||
- Metrics: conditions, progress, harvest, planting, yield, production, area (7)
|
||||
- Each metric with PT synonym: (condições), (colheita), (rendimento), etc.
|
||||
- Actions: queries, comparisons, rankings, analyses, reports
|
||||
- Temporal: weekly, annual, week-over-week, year-over-year
|
||||
- Source: USDA NASS
|
||||
- Total unique keywords: ~65+
|
||||
|
||||
**Step D: Validate Keyword Coverage**
|
||||
|
||||
Final checklist:
|
||||
```markdown
|
||||
- [ ] All API metrics mentioned? (if API has 5 → 5 in description)
|
||||
- [ ] Each metric has PT synonym? (yield = rendimento)
|
||||
- [ ] Action verbs included? (compare, rank, analyze)
|
||||
- [ ] Temporal context? (current, today, YoY)
|
||||
- [ ] Geographic context? (states, national)
|
||||
- [ ] Data source mentioned? (USDA NASS)
|
||||
- [ ] Total >= 60 unique keywords? (count!)
|
||||
```
|
||||
|
||||
**Example 2 (stock analysis)**:
|
||||
```yaml
|
||||
description: This skill should be used for technical stock analysis using indicators like RSI, MACD, Bollinger Bands, moving averages. Activates when user asks about technical analysis, indicators, buy/sell signals for stocks. Supports multiple tickers, benchmark comparisons, alert generation. DO NOT use for fundamental analysis, financial statements, or news.
|
||||
```
|
||||
|
||||
### Step 6: List Complete Keywords
|
||||
|
||||
In SKILL.md, include complete keywords section:
|
||||
|
||||
```markdown
|
||||
## Keywords for Automatic Detection
|
||||
|
||||
This skill is activated when user mentions:
|
||||
|
||||
**Entities**:
|
||||
- [complete list of organizations]
|
||||
- [complete list of main objects]
|
||||
|
||||
**Geography**:
|
||||
- [list of countries/regions/states]
|
||||
|
||||
**Metrics**:
|
||||
- [list of metrics]
|
||||
|
||||
**Actions**:
|
||||
- [list of verbs]
|
||||
|
||||
**Temporality**:
|
||||
- [list of temporal terms]
|
||||
|
||||
**Activation examples**:
|
||||
✅ "[example 1]"
|
||||
✅ "[example 2]"
|
||||
✅ "[example 3]"
|
||||
✅ "[example 4]"
|
||||
✅ "[example 5]"
|
||||
|
||||
**Does NOT activate for**:
|
||||
❌ "[out of scope example]"
|
||||
❌ "[out of scope example]"
|
||||
❌ "[out of scope example]"
|
||||
```
|
||||
|
||||
### Step 7: Mental Testing
|
||||
|
||||
**Simulate detection**:
|
||||
|
||||
For each example question from use cases (Phase 2), verify:
|
||||
- Description contains relevant keywords? ✅
|
||||
- Doesn't contain negative scope keywords? ✅
|
||||
- Claude would detect automatically? ✅
|
||||
|
||||
**If any use case would NOT be detected**:
|
||||
→ Add missing keywords to description
|
||||
|
||||
## Detection Design Examples
|
||||
|
||||
### Example 1: US Agriculture (NASS)
|
||||
|
||||
**Identified keywords**:
|
||||
- Entities: USDA (5x), NASS (8x), agriculture (3x)
|
||||
- Commodities: corn (12x), soybeans (10x), wheat (8x)
|
||||
- Metrics: production (15x), area (10x), yield (8x)
|
||||
- Geography: US (10x), states (5x), Iowa (2x)
|
||||
- Actions: compare (5x), ranking (3x), trend (2x)
|
||||
|
||||
**Description**:
|
||||
"This skill should be used for analyses about United States agriculture using official USDA NASS data. Activates when user asks about production, area, yield of commodities like corn, soybeans, wheat. Supports YoY comparisons, rankings, trends. DO NOT use for futures or other countries."
|
||||
|
||||
**Coverage**: 95% of typical use cases
|
||||
|
||||
### Example 2: Global Climate (NOAA)
|
||||
|
||||
**Keywords**:
|
||||
- Entities: NOAA, weather, climate
|
||||
- Metrics: temperature, precipitation, humidity
|
||||
- Geography: global, countries, stations
|
||||
- Temporality: historical, current, forecast
|
||||
|
||||
**Description**:
|
||||
"This skill should be used for climate analyses using NOAA data. Activates when user asks about temperature, precipitation, historical climate data or forecasts. Supports temporal and geographic aggregations, anomalies, long-term trends."
|
||||
|
||||
## Phase 4 Checklist
|
||||
|
||||
- [ ] Entities listed (organizations, objects, geography)
|
||||
- [ ] Actions/verbs listed
|
||||
- [ ] Question variations mapped
|
||||
- [ ] Negative scope defined
|
||||
- [ ] Description created (150-250 chars)
|
||||
- [ ] Complete keywords documented in SKILL.md
|
||||
- [ ] Activation examples (positive and negative)
|
||||
- [ ] Mental detection simulation (all use cases covered)
|
||||
1011
references/phase5-implementation.md
Normal file
1011
references/phase5-implementation.md
Normal file
File diff suppressed because it is too large
Load diff
783
references/phase6-testing.md
Normal file
783
references/phase6-testing.md
Normal file
|
|
@ -0,0 +1,783 @@
|
|||
# Phase 6: Test Suite Generation (NEW v2.0!)
|
||||
|
||||
## Objective
|
||||
|
||||
**GENERATE** comprehensive test suite that validates ALL functions of the created skill.
|
||||
|
||||
**LEARNING:** us-crop-monitor v1.0 had ZERO tests. When expanding to v2.0, it was difficult to ensure nothing broke. v2.0 has 25 tests (100% passing) that ensure reliability.
|
||||
|
||||
---
|
||||
|
||||
## Why Are Tests Critical?
|
||||
|
||||
### Benefits for Developer:
|
||||
- ✅ Ensures code works before distribution
|
||||
- ✅ Detects bugs early (not after client installs!)
|
||||
- ✅ Allows confident changes (regression testing)
|
||||
- ✅ Documents expected behavior
|
||||
|
||||
### Benefits for Client:
|
||||
- ✅ Confidence in skill ("100% tested")
|
||||
- ✅ Fewer bugs in production
|
||||
- ✅ More professional (commercially viable)
|
||||
|
||||
### Benefits for Agent-Creator:
|
||||
- ✅ Validates that generated skill actually works
|
||||
- ✅ Catch errors before considering "done"
|
||||
- ✅ Automatic quality gate
|
||||
|
||||
---
|
||||
|
||||
## Test Structure
|
||||
|
||||
### tests/ Directory
|
||||
|
||||
```
|
||||
{skill-name}/
|
||||
└── tests/
|
||||
├── test_fetch.py # Tests API client
|
||||
├── test_parse.py # Tests parsers
|
||||
├── test_analyze.py # Tests analyses
|
||||
├── test_integration.py # Tests end-to-end
|
||||
├── test_validation.py # Tests validators
|
||||
├── test_helpers.py # Tests helpers (year detection, etc.)
|
||||
└── README.md # How to run tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 1: test_fetch.py
|
||||
|
||||
**Objective:** Validate API client works
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Test suite for {API} client.
|
||||
|
||||
Tests all fetch methods with real API data.
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
|
||||
|
||||
from fetch_{api} import {ApiClient}, DataNotFoundError
|
||||
|
||||
|
||||
def test_get_{metric1}():
|
||||
"""Test fetching {metric1} data."""
|
||||
print("\nTesting get_{metric1}()...")
|
||||
|
||||
try:
|
||||
client = {ApiClient}()
|
||||
|
||||
# Test with valid parameters
|
||||
result = client.get_{metric1}(
|
||||
{entity}='{valid_entity}',
|
||||
year=2024
|
||||
)
|
||||
|
||||
# Validations
|
||||
assert 'data' in result, "Missing 'data' in result"
|
||||
assert 'metadata' in result, "Missing 'metadata'"
|
||||
assert len(result['data']) > 0, "No data returned"
|
||||
assert result['metadata']['from_cache'] in [True, False]
|
||||
|
||||
print(f" ✓ Fetched {len(result['data'])} records")
|
||||
print(f" ✓ Metadata present")
|
||||
print(f" ✓ From cache: {result['metadata']['from_cache']}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def test_get_{metric2}():
|
||||
"""Test fetching {metric2} data."""
|
||||
# Similar structure...
|
||||
pass
|
||||
|
||||
|
||||
def test_error_handling():
|
||||
"""Test that errors are handled correctly."""
|
||||
print("\nTesting error handling...")
|
||||
|
||||
try:
|
||||
client = {ApiClient}()
|
||||
|
||||
# Test invalid entity (should raise)
|
||||
try:
|
||||
result = client.get_{metric1}({entity}='INVALID_ENTITY', year=2024)
|
||||
print(" ✗ Should have raised DataNotFoundError")
|
||||
return False
|
||||
except DataNotFoundError:
|
||||
print(" ✓ Correctly raises DataNotFoundError for invalid entity")
|
||||
|
||||
# Test invalid year (should raise)
|
||||
try:
|
||||
result = client.get_{metric1}({entity}='{valid}', year=2099)
|
||||
print(" ✗ Should have raised ValidationError")
|
||||
return False
|
||||
except Exception as e:
|
||||
print(f" ✓ Correctly raises error for future year")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ Unexpected error: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def main():
|
||||
"""Run all fetch tests."""
|
||||
print("=" * 70)
|
||||
print("FETCH TESTS - {API} Client")
|
||||
print("=" * 70)
|
||||
|
||||
results = []
|
||||
|
||||
# Test each get_* method
|
||||
results.append(("get_{metric1}", test_get_{metric1}()))
|
||||
results.append(("get_{metric2}", test_get_{metric2}()))
|
||||
# ... add test for ALL get_* methods
|
||||
|
||||
results.append(("error_handling", test_error_handling()))
|
||||
|
||||
# Summary
|
||||
print("\n" + "=" * 70)
|
||||
print("SUMMARY")
|
||||
print("=" * 70)
|
||||
|
||||
passed = sum(1 for _, r in results if r)
|
||||
total = len(results)
|
||||
|
||||
for name, result in results:
|
||||
status = "✓ PASS" if result else "✗ FAIL"
|
||||
print(f"{status}: {name}()")
|
||||
|
||||
print(f"\nResults: {passed}/{total} tests passed")
|
||||
|
||||
return passed == total
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
success = main()
|
||||
sys.exit(0 if success else 1)
|
||||
```
|
||||
|
||||
**Rule:** ONE test function for EACH `get_*()` method implemented!
|
||||
|
||||
---
|
||||
|
||||
## Template 2: test_parse.py
|
||||
|
||||
**Objective:** Validate parsers
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Test suite for data parsers.
|
||||
|
||||
Tests all parse_* modules.
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
|
||||
|
||||
from parse_{type1} import parse_{type1}_response
|
||||
from parse_{type2} import parse_{type2}_response
|
||||
|
||||
|
||||
def test_parse_{type1}():
|
||||
"""Test {type1} parser."""
|
||||
print("\nTesting parse_{type1}_response()...")
|
||||
|
||||
# Sample data (real structure from API)
|
||||
sample_data = [
|
||||
{
|
||||
'field1': 'value1',
|
||||
'field2': 'value2',
|
||||
'Value': '123',
|
||||
# ... real API fields
|
||||
}
|
||||
]
|
||||
|
||||
try:
|
||||
df = parse_{type1}_response(sample_data)
|
||||
|
||||
# Validations
|
||||
assert not df.empty, "DataFrame is empty"
|
||||
assert 'Value' in df.columns or '{metric}_value' in df.columns
|
||||
assert len(df) == len(sample_data)
|
||||
|
||||
print(f" ✓ Parsed {len(df)} records")
|
||||
print(f" ✓ Columns: {list(df.columns)}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
return False
|
||||
|
||||
|
||||
def test_parse_empty_data():
|
||||
"""Test parser handles empty data gracefully."""
|
||||
print("\nTesting empty data handling...")
|
||||
|
||||
try:
|
||||
from parse_{type1} import ParseError
|
||||
|
||||
try:
|
||||
df = parse_{type1}_response([])
|
||||
print(" ✗ Should have raised ParseError")
|
||||
return False
|
||||
except ParseError as e:
|
||||
print(f" ✓ Correctly raises ParseError: {e}")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ Unexpected error: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def main():
|
||||
results = []
|
||||
|
||||
# Test each parser
|
||||
results.append(("parse_{type1}", test_parse_{type1}()))
|
||||
results.append(("parse_{type2}", test_parse_{type2}()))
|
||||
# ... for ALL parsers
|
||||
|
||||
results.append(("empty_data", test_parse_empty_data()))
|
||||
|
||||
# Summary
|
||||
passed = sum(1 for _, r in results if r)
|
||||
print(f"\nResults: {passed}/{len(results)} passed")
|
||||
return passed == len(results)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(0 if main() else 1)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 3: test_integration.py
|
||||
|
||||
**Objective:** End-to-end tests (MOST IMPORTANT!)
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Integration tests for {skill-name}.
|
||||
|
||||
Tests all analysis functions with REAL API data.
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
|
||||
|
||||
from analyze_{domain} import (
|
||||
{function1},
|
||||
{function2},
|
||||
{function3},
|
||||
# ... import ALL functions
|
||||
)
|
||||
|
||||
|
||||
def test_{function1}():
|
||||
"""Test {function1} with auto-year detection."""
|
||||
print("\n1. Testing {function1}()...")
|
||||
|
||||
try:
|
||||
# Test WITHOUT year (auto-detection)
|
||||
result = {function1}({entity}='{valid_entity}')
|
||||
|
||||
# Validations
|
||||
assert 'year' in result, "Missing year"
|
||||
assert 'year_requested' in result, "Missing year_requested"
|
||||
assert 'year_info' in result, "Missing year_info"
|
||||
assert result['year'] >= 2024, "Year too old"
|
||||
assert result['year_requested'] is None, "Should auto-detect"
|
||||
|
||||
print(f" ✓ Auto-year detection: {result['year']}")
|
||||
print(f" ✓ Year info: {result['year_info']}")
|
||||
print(f" ✓ Data present: {list(result.keys())}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
return False
|
||||
|
||||
|
||||
def test_{function1}_with_explicit_year():
|
||||
"""Test {function1} with explicit year."""
|
||||
print("\n2. Testing {function1}() with explicit year...")
|
||||
|
||||
try:
|
||||
# Test WITH year specified
|
||||
result = {function1}({entity}='{valid_entity}', year=2024)
|
||||
|
||||
assert result['year'] == 2024, f"Expected 2024, got {result['year']}"
|
||||
assert result['year_requested'] == 2024
|
||||
|
||||
print(f" ✓ Uses specified year: {result['year']}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def test_all_functions_exist():
|
||||
"""Verify all expected functions are implemented."""
|
||||
print("\nVerifying all functions exist...")
|
||||
|
||||
expected_functions = [
|
||||
'{function1}',
|
||||
'{function2}',
|
||||
'{function3}',
|
||||
# ... ALL functions
|
||||
]
|
||||
|
||||
missing = []
|
||||
for func_name in expected_functions:
|
||||
if func_name not in globals():
|
||||
missing.append(func_name)
|
||||
|
||||
if missing:
|
||||
print(f" ✗ Missing functions: {missing}")
|
||||
return False
|
||||
else:
|
||||
print(f" ✓ All {len(expected_functions)} functions present")
|
||||
return True
|
||||
|
||||
|
||||
def main():
|
||||
"""Run all integration tests."""
|
||||
print("\n" + "=" * 70)
|
||||
print("{SKILL NAME} - INTEGRATION TEST SUITE")
|
||||
print("=" * 70)
|
||||
|
||||
results = []
|
||||
|
||||
# Test each function
|
||||
results.append(("{function1} auto-year", test_{function1}()))
|
||||
results.append(("{function1} explicit-year", test_{function1}_with_explicit_year()))
|
||||
# ... repeat for ALL functions
|
||||
|
||||
results.append(("all_functions_exist", test_all_functions_exist()))
|
||||
|
||||
# Summary
|
||||
print("\n" + "=" * 70)
|
||||
print("FINAL SUMMARY")
|
||||
print("=" * 70)
|
||||
|
||||
passed = sum(1 for _, r in results if r)
|
||||
total = len(results)
|
||||
|
||||
print(f"\n✓ Passed: {passed}/{total}")
|
||||
print(f"✗ Failed: {total - passed}/{total}")
|
||||
|
||||
if passed == total:
|
||||
print("\n🎉 ALL TESTS PASSED! SKILL IS PRODUCTION READY!")
|
||||
else:
|
||||
print(f"\n⚠ {total - passed} test(s) failed - FIX BEFORE RELEASE")
|
||||
|
||||
print("=" * 70)
|
||||
|
||||
return passed == total
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
success = main()
|
||||
sys.exit(0 if success else 1)
|
||||
```
|
||||
|
||||
**Rule:** Minimum 2 tests per analysis function (auto-year + explicit-year)
|
||||
|
||||
---
|
||||
|
||||
## Template 4: test_helpers.py
|
||||
|
||||
**Objective:** Test year detection helpers
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Test suite for utility helpers.
|
||||
|
||||
Tests temporal context detection.
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from datetime import datetime
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
|
||||
|
||||
from utils.helpers import (
|
||||
get_current_{domain}_year,
|
||||
should_try_previous_year,
|
||||
format_year_message
|
||||
)
|
||||
|
||||
|
||||
def test_get_current_year():
|
||||
"""Test current year detection."""
|
||||
print("\nTesting get_current_{domain}_year()...")
|
||||
|
||||
try:
|
||||
year = get_current_{domain}_year()
|
||||
current_year = datetime.now().year
|
||||
|
||||
assert year == current_year, f"Expected {current_year}, got {year}"
|
||||
|
||||
print(f" ✓ Correctly returns: {year}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def test_should_try_previous_year():
|
||||
"""Test seasonal fallback logic."""
|
||||
print("\nTesting should_try_previous_year()...")
|
||||
|
||||
try:
|
||||
# Test with None (current year)
|
||||
result = should_try_previous_year()
|
||||
print(f" ✓ Current year fallback: {result}")
|
||||
|
||||
# Test with specific year
|
||||
result_past = should_try_previous_year(2023)
|
||||
print(f" ✓ Past year fallback: {result_past}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def test_format_year_message():
|
||||
"""Test year message formatting."""
|
||||
print("\nTesting format_year_message()...")
|
||||
|
||||
try:
|
||||
# Test auto-detected
|
||||
msg1 = format_year_message(2025, None)
|
||||
assert "auto-detected" in msg1.lower() or "2025" in msg1
|
||||
print(f" ✓ Auto-detected: {msg1}")
|
||||
|
||||
# Test requested
|
||||
msg2 = format_year_message(2024, 2024)
|
||||
assert "2024" in msg2
|
||||
print(f" ✓ Requested: {msg2}")
|
||||
|
||||
# Test fallback
|
||||
msg3 = format_year_message(2024, 2025)
|
||||
assert "not" in msg3.lower() or "fallback" in msg3.lower()
|
||||
print(f" ✓ Fallback: {msg3}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ FAILED: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def main():
|
||||
results = []
|
||||
|
||||
results.append(("get_current_year", test_get_current_year()))
|
||||
results.append(("should_try_previous_year", test_should_try_previous_year()))
|
||||
results.append(("format_year_message", test_format_year_message()))
|
||||
|
||||
passed = sum(1 for _, r in results if r)
|
||||
print(f"\nResults: {passed}/{len(results)} passed")
|
||||
|
||||
return passed == len(results)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(0 if main() else 1)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Rules for Tests
|
||||
|
||||
### 1. ALL tests must use REAL DATA
|
||||
|
||||
❌ **FORBIDDEN:**
|
||||
```python
|
||||
def test_function():
|
||||
# Mock data
|
||||
mock_data = {'fake': 'data'}
|
||||
result = function(mock_data)
|
||||
assert result == 'expected'
|
||||
```
|
||||
|
||||
✅ **MANDATORY:**
|
||||
```python
|
||||
def test_function():
|
||||
# Real API call
|
||||
client = ApiClient()
|
||||
result = client.get_real_data(entity='REAL', year=2024)
|
||||
|
||||
# Validate real response
|
||||
assert len(result['data']) > 0
|
||||
assert 'metadata' in result
|
||||
```
|
||||
|
||||
**Why?**
|
||||
- Tests with mocks don't guarantee API is working
|
||||
- Real tests detect API changes
|
||||
- Client needs to know it works with REAL data
|
||||
|
||||
---
|
||||
|
||||
### 2. Tests must be FAST
|
||||
|
||||
**Goal:** Complete suite in < 60 seconds
|
||||
|
||||
**Techniques:**
|
||||
- Use cache: First test populates cache, rest use cached
|
||||
- Limit requests: Don't test 100 entities, test 2-3
|
||||
- Parallel where possible
|
||||
|
||||
```python
|
||||
# Example: Populate cache once
|
||||
@classmethod
|
||||
def setUpClass(cls):
|
||||
"""Populate cache before all tests."""
|
||||
client = ApiClient()
|
||||
client.get_data('ENTITY1', 2024) # Cache for other tests
|
||||
|
||||
# Tests then use cached data (fast)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Tests must PASS 100%
|
||||
|
||||
**Quality Gate:** Skill is only "done" when ALL tests pass.
|
||||
|
||||
```python
|
||||
if __name__ == "__main__":
|
||||
success = main()
|
||||
if not success:
|
||||
print("\n❌ SKILL NOT READY - FIX FAILING TESTS")
|
||||
sys.exit(1)
|
||||
else:
|
||||
print("\n✅ SKILL READY FOR DISTRIBUTION")
|
||||
sys.exit(0)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage Requirements
|
||||
|
||||
### Minimum Mandatory:
|
||||
|
||||
**Per module:**
|
||||
- `fetch_{api}.py`: 1 test per `get_*()` method + 1 error handling test
|
||||
- Each `parse_{type}.py`: 1 test per main function
|
||||
- `analyze_{domain}.py`: 2 tests per analysis (auto-year + explicit-year)
|
||||
- `utils/helpers.py`: 3 tests (get_year, should_fallback, format_message)
|
||||
|
||||
**Expected total:** 15-30 tests depending on skill size
|
||||
|
||||
**Example (us-crop-monitor v2.0):**
|
||||
- test_fetch.py: 6 tests (5 get_* + 1 error)
|
||||
- test_parse.py: 4 tests (4 parsers)
|
||||
- test_analyze.py: 11 tests (11 functions)
|
||||
- test_helpers.py: 3 tests
|
||||
- test_integration.py: 1 end-to-end test
|
||||
- **Total:** 25 tests
|
||||
|
||||
---
|
||||
|
||||
## How to Run Tests
|
||||
|
||||
### Individual:
|
||||
```bash
|
||||
python3 tests/test_fetch.py
|
||||
python3 tests/test_integration.py
|
||||
```
|
||||
|
||||
### Complete suite:
|
||||
```bash
|
||||
# Run all
|
||||
for test in tests/test_*.py; do
|
||||
python3 $test || exit 1
|
||||
done
|
||||
|
||||
# Or with pytest (if available)
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
### In CI/CD:
|
||||
```yaml
|
||||
# .github/workflows/test.yml
|
||||
name: Test Suite
|
||||
on: [push]
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- run: pip install -r requirements.txt
|
||||
- run: python3 tests/test_integration.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Example
|
||||
|
||||
**When tests pass:**
|
||||
```
|
||||
======================================================================
|
||||
US CROP MONITOR - INTEGRATION TEST SUITE
|
||||
======================================================================
|
||||
|
||||
1. current_condition_report()...
|
||||
✓ Year: 2025 | Week: 39
|
||||
✓ Good+Excellent: 66.0%
|
||||
|
||||
2. week_over_week_comparison()...
|
||||
✓ Year: 2025 | Weeks: 39 vs 38
|
||||
✓ Delta: -2.2 pts
|
||||
|
||||
...
|
||||
|
||||
======================================================================
|
||||
FINAL SUMMARY
|
||||
======================================================================
|
||||
|
||||
✓ Passed: 25/25 tests
|
||||
✗ Failed: 0/25 tests
|
||||
|
||||
🎉 ALL TESTS PASSED! SKILL IS PRODUCTION READY!
|
||||
======================================================================
|
||||
```
|
||||
|
||||
**When tests fail:**
|
||||
```
|
||||
8. yield_analysis()...
|
||||
✗ FAILED: 'yield_bu_per_acre' not in result
|
||||
|
||||
...
|
||||
|
||||
FINAL SUMMARY:
|
||||
✓ Passed: 24/25
|
||||
✗ Failed: 1/25
|
||||
|
||||
❌ SKILL NOT READY - FIX FAILING TESTS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Agent-Creator
|
||||
|
||||
### When to generate tests:
|
||||
|
||||
**In Phase 5 (Implementation):**
|
||||
|
||||
Updated order:
|
||||
```
|
||||
...
|
||||
8. Implement analyze (analyses)
|
||||
9. CREATE TESTS (← here!)
|
||||
- Generate test_fetch.py
|
||||
- Generate test_parse.py
|
||||
- Generate test_analyze.py
|
||||
- Generate test_helpers.py
|
||||
- Generate test_integration.py
|
||||
10. RUN TESTS
|
||||
- Run test suite
|
||||
- If fails → FIX and re-run
|
||||
- Only continue when 100% passing
|
||||
11. Create examples/
|
||||
...
|
||||
```
|
||||
|
||||
### Quality Gate:
|
||||
|
||||
```python
|
||||
# Agent-creator should do:
|
||||
print("Running test suite...")
|
||||
exit_code = subprocess.run(['python3', 'tests/test_integration.py']).returncode
|
||||
|
||||
if exit_code != 0:
|
||||
print("❌ Tests failed - aborting skill generation")
|
||||
print("Fix errors above and try again")
|
||||
sys.exit(1)
|
||||
|
||||
print("✅ All tests passed - continuing...")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before considering skill "done":
|
||||
|
||||
- [ ] tests/ directory created
|
||||
- [ ] test_fetch.py with 1 test per get_*() method
|
||||
- [ ] test_parse.py with 1 test per parser
|
||||
- [ ] test_analyze.py with 2 tests per function (auto-year + explicit)
|
||||
- [ ] test_helpers.py with year detection tests
|
||||
- [ ] test_integration.py with end-to-end test
|
||||
- [ ] ALL tests passing (100%)
|
||||
- [ ] Test suite executes in < 60 seconds
|
||||
- [ ] README in tests/ explaining how to run
|
||||
|
||||
---
|
||||
|
||||
## Real Example: us-crop-monitor v2.0
|
||||
|
||||
**Tests created:**
|
||||
- `test_new_metrics.py` - 5 tests (fetch methods)
|
||||
- `test_year_detection.py` - 2 tests (auto-detection)
|
||||
- `test_all_year_detection.py` - 4 tests (all functions)
|
||||
- `test_new_analyses.py` - 3 tests (new analyses)
|
||||
- `tests/test_integrated_validation.py` - 11 tests (comprehensive)
|
||||
|
||||
**Total:** 25 tests, 100% passing
|
||||
|
||||
**Result:**
|
||||
```
|
||||
✓ Passed: 25/25 tests
|
||||
🎉 ALL TESTS PASSED! SKILL IS PRODUCTION READY!
|
||||
```
|
||||
|
||||
**Benefit:** Full confidence v2.0 works before distribution!
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**ALWAYS generate test suite!**
|
||||
|
||||
Skills without tests = prototypes
|
||||
Skills with tests = professional products ✅
|
||||
|
||||
**ROI:** Tests cost +2h to create, but save 10-20h of debugging later!
|
||||
937
references/quality-standards.md
Normal file
937
references/quality-standards.md
Normal file
|
|
@ -0,0 +1,937 @@
|
|||
# Mandatory Quality Standards
|
||||
|
||||
## Fundamental Principles
|
||||
|
||||
**Production-Ready, Not Prototype**
|
||||
- Code must work without modifications
|
||||
- Doesn't need "now implement X"
|
||||
- Can be used immediately
|
||||
|
||||
**Functional, Not Placeholder**
|
||||
- Complete code in all functions
|
||||
- No TODO, pass, NotImplementedError
|
||||
- Robust error handling
|
||||
|
||||
**Useful, Not Generic**
|
||||
- Specific and detailed content
|
||||
- Concrete examples, not abstract
|
||||
- Not just external links
|
||||
|
||||
---
|
||||
|
||||
## Standards by File Type
|
||||
|
||||
### Python Scripts
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Complete structure**:
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Module docstring"""
|
||||
|
||||
# Imports
|
||||
import ...
|
||||
|
||||
# Constants
|
||||
CONST = value
|
||||
|
||||
# Classes/Functions
|
||||
class/def ...
|
||||
|
||||
# Main
|
||||
def main():
|
||||
...
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
**2. Docstrings**:
|
||||
- Module docstring: 3-5 lines
|
||||
- Class docstring: Description + Example
|
||||
- Method docstring: Args, Returns, Raises, Example
|
||||
|
||||
**3. Type hints**:
|
||||
```python
|
||||
def function(param1: str, param2: int = 10) -> Dict[str, Any]:
|
||||
...
|
||||
```
|
||||
|
||||
**4. Error handling**:
|
||||
```python
|
||||
try:
|
||||
result = risky_operation()
|
||||
except SpecificError as e:
|
||||
# Handle specifically
|
||||
log_error(e)
|
||||
raise CustomError(f"Context: {e}")
|
||||
```
|
||||
|
||||
**5. Validations**:
|
||||
```python
|
||||
def process(data: Dict) -> pd.DataFrame:
|
||||
# Validate input
|
||||
if not data:
|
||||
raise ValueError("Data cannot be empty")
|
||||
|
||||
if 'required_field' not in data:
|
||||
raise ValueError("Missing required field")
|
||||
|
||||
# Process
|
||||
...
|
||||
|
||||
# Validate output
|
||||
assert len(result) > 0, "Result cannot be empty"
|
||||
assert result['value'].notna().all(), "No null values allowed"
|
||||
|
||||
return result
|
||||
```
|
||||
|
||||
**6. Appropriate logging**:
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def fetch_data():
|
||||
logger.info("Fetching data from API...")
|
||||
# ...
|
||||
logger.debug(f"Received {len(data)} records")
|
||||
# ...
|
||||
logger.error(f"API error: {e}")
|
||||
```
|
||||
|
||||
#### ❌ FORBIDDEN
|
||||
|
||||
```python
|
||||
# ❌ DON'T DO THIS:
|
||||
|
||||
def analyze():
|
||||
# TODO: implement analysis
|
||||
pass
|
||||
|
||||
def process(data): # ❌ No type hints
|
||||
# ❌ No docstring
|
||||
result = data # ❌ No real logic
|
||||
return result # ❌ No validation
|
||||
|
||||
def fetch_api(url):
|
||||
response = requests.get(url) # ❌ No timeout
|
||||
return response.json() # ❌ No error handling
|
||||
```
|
||||
|
||||
#### ✅ DO THIS:
|
||||
|
||||
```python
|
||||
def analyze_yoy(df: pd.DataFrame, commodity: str, year1: int, year2: int) -> Dict:
|
||||
"""
|
||||
Perform year-over-year analysis
|
||||
|
||||
Args:
|
||||
df: DataFrame with parsed data
|
||||
commodity: Commodity name (e.g., "CORN")
|
||||
year1: Current year
|
||||
year2: Previous year
|
||||
|
||||
Returns:
|
||||
Dict with keys:
|
||||
- production_current: float
|
||||
- production_previous: float
|
||||
- change_percent: float
|
||||
- interpretation: str
|
||||
|
||||
Raises:
|
||||
ValueError: If data not found for specified years
|
||||
DataQualityError: If data fails validation
|
||||
|
||||
Example:
|
||||
>>> analyze_yoy(df, "CORN", 2023, 2022)
|
||||
{'production_current': 15.3, 'change_percent': 11.7, ...}
|
||||
"""
|
||||
# Validate inputs
|
||||
if commodity not in df['commodity'].unique():
|
||||
raise ValueError(f"Commodity {commodity} not found in data")
|
||||
|
||||
# Filter data
|
||||
df1 = df[(df['commodity'] == commodity) & (df['year'] == year1)]
|
||||
df2 = df[(df['commodity'] == commodity) & (df['year'] == year2)]
|
||||
|
||||
if len(df1) == 0 or len(df2) == 0:
|
||||
raise ValueError(f"Data not found for {commodity} in {year1} or {year2}")
|
||||
|
||||
# Extract values
|
||||
prod1 = df1['production'].iloc[0]
|
||||
prod2 = df2['production'].iloc[0]
|
||||
|
||||
# Calculate
|
||||
change = prod1 - prod2
|
||||
change_pct = (change / prod2) * 100
|
||||
|
||||
# Interpret
|
||||
if abs(change_pct) < 2:
|
||||
interpretation = "stable"
|
||||
elif change_pct > 10:
|
||||
interpretation = "significant_increase"
|
||||
elif change_pct > 2:
|
||||
interpretation = "moderate_increase"
|
||||
elif change_pct < -10:
|
||||
interpretation = "significant_decrease"
|
||||
else:
|
||||
interpretation = "moderate_decrease"
|
||||
|
||||
# Return
|
||||
return {
|
||||
"commodity": commodity,
|
||||
"production_current": round(prod1, 1),
|
||||
"production_previous": round(prod2, 1),
|
||||
"change_absolute": round(change, 1),
|
||||
"change_percent": round(change_pct, 1),
|
||||
"interpretation": interpretation
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### SKILL.md
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Valid frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
name: agent-name
|
||||
description: [150-250 words with keywords]
|
||||
---
|
||||
```
|
||||
|
||||
**2. Size**: 5000-7000 words
|
||||
|
||||
**3. Mandatory sections**:
|
||||
- When to use (specific triggers)
|
||||
- Data source (detailed API)
|
||||
- Workflows (complete step-by-step)
|
||||
- Scripts (each one explained)
|
||||
- Analyses (methodologies)
|
||||
- Errors (complete handling)
|
||||
- Validations (mandatory)
|
||||
- Keywords (complete list)
|
||||
- Examples (5+ complete)
|
||||
|
||||
**4. Detailed workflows**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
### Workflow: YoY Comparison
|
||||
|
||||
1. **Identify question parameters**
|
||||
- Commodity: [extract from question]
|
||||
- Years: Current vs previous (or specified)
|
||||
|
||||
2. **Fetch data**
|
||||
```bash
|
||||
python scripts/fetch_nass.py \
|
||||
--commodity CORN \
|
||||
--years 2023,2022 \
|
||||
--output data/raw/corn_2023_2022.json
|
||||
```
|
||||
|
||||
3. **Parse**
|
||||
```bash
|
||||
python scripts/parse_nass.py \
|
||||
--input data/raw/corn_2023_2022.json \
|
||||
--output data/processed/corn.csv
|
||||
```
|
||||
|
||||
4. **Analyze**
|
||||
```bash
|
||||
python scripts/analyze_nass.py \
|
||||
--input data/processed/corn.csv \
|
||||
--analysis yoy \
|
||||
--commodity CORN \
|
||||
--year1 2023 \
|
||||
--year2 2022 \
|
||||
--output data/analysis/corn_yoy.json
|
||||
```
|
||||
|
||||
5. **Interpret results**
|
||||
|
||||
File `data/analysis/corn_yoy.json` contains:
|
||||
```json
|
||||
{
|
||||
"production_current": 15.3,
|
||||
"change_percent": 11.7,
|
||||
"interpretation": "significant_increase"
|
||||
}
|
||||
```
|
||||
|
||||
Respond to user:
|
||||
"Corn production grew 11.7% in 2023..."
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
### Workflow: Comparison
|
||||
|
||||
1. Get data
|
||||
2. Compare
|
||||
3. Return result
|
||||
```
|
||||
|
||||
**5. Complete examples**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
### Example 1: YoY Comparison
|
||||
|
||||
**Question**: "How's corn production compared to last year?"
|
||||
|
||||
**Executed flow**:
|
||||
[Specific commands with outputs]
|
||||
|
||||
**Generated answer**:
|
||||
"Corn production in 2023 is 15.3 billion bushels,
|
||||
growth of 11.7% vs 2022 (13.7 billion). Growth
|
||||
comes mainly from area increase (+8%) with stable yield."
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
### Example: Comparison
|
||||
|
||||
User asks about comparison. Agent compares and responds.
|
||||
```
|
||||
|
||||
#### ❌ FORBIDDEN
|
||||
|
||||
- Empty sections
|
||||
- "See documentation"
|
||||
- Workflows without specific commands
|
||||
- Generic examples
|
||||
|
||||
---
|
||||
|
||||
### References
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Useful and self-contained content**:
|
||||
|
||||
✅ **GOOD** (references/api-guide.md):
|
||||
```markdown
|
||||
## Endpoint: Get Production Data
|
||||
|
||||
**URL**: `GET https://quickstats.nass.usda.gov/api/api_GET/`
|
||||
|
||||
**Parameters**:
|
||||
- `commodity_desc`: Commodity name
|
||||
- Example: "CORN", "SOYBEANS"
|
||||
- Case-sensitive
|
||||
- `year`: Desired year
|
||||
- Example: 2023
|
||||
- Range: 1866-present
|
||||
|
||||
**Complete request example**:
|
||||
```bash
|
||||
curl -H "X-Api-Key: YOUR_KEY" \
|
||||
"https://quickstats.nass.usda.gov/api/api_GET/?commodity_desc=CORN&year=2023&format=JSON"
|
||||
```
|
||||
|
||||
**Expected response**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"year": 2023,
|
||||
"commodity_desc": "CORN",
|
||||
"value": "15,300,000,000",
|
||||
"unit_desc": "BU"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Important fields**:
|
||||
- `value`: Comes as STRING with commas
|
||||
- Solution: `value.replace(',', '')`
|
||||
- Convert to float after
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
## API Endpoint
|
||||
|
||||
For details on how to use the API, consult the official documentation at:
|
||||
https://quickstats.nass.usda.gov/api
|
||||
|
||||
[End of file]
|
||||
```
|
||||
|
||||
**2. Adequate size**:
|
||||
- API guide: 1500-2000 words
|
||||
- Analysis methods: 2000-3000 words
|
||||
- Troubleshooting: 1000-1500 words
|
||||
|
||||
**3. Concrete examples**:
|
||||
- Always include examples with real values
|
||||
- Executable code blocks
|
||||
- Expected outputs
|
||||
|
||||
#### ❌ FORBIDDEN
|
||||
|
||||
- "For more information, see [link]"
|
||||
- Sections with only 2-3 lines
|
||||
- Lists without details
|
||||
- Circular references ("see other doc that sees other doc")
|
||||
|
||||
---
|
||||
|
||||
### Assets (Configs)
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Syntactically valid JSON**:
|
||||
```bash
|
||||
# ALWAYS validate:
|
||||
python -c "import json; json.load(open('config.json'))"
|
||||
```
|
||||
|
||||
**2. Real values**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"base_url": "https://quickstats.nass.usda.gov/api",
|
||||
"api_key_env": "NASS_API_KEY",
|
||||
"_instructions": "Get free API key from: https://quickstats.nass.usda.gov/api#registration",
|
||||
"rate_limit_per_day": 1000,
|
||||
"timeout_seconds": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"base_url": "YOUR_API_URL_HERE",
|
||||
"api_key": "YOUR_KEY_HERE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Inline comments** (using `_comment` or `_note`):
|
||||
```json
|
||||
{
|
||||
"_comment": "Differentiated TTL by data type",
|
||||
"cache": {
|
||||
"ttl_historical_days": 365,
|
||||
"_note_historical": "Historical data doesn't change",
|
||||
"ttl_current_days": 7,
|
||||
"_note_current": "Current year data may be revised"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### README.md
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Complete installation instructions**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
## Installation
|
||||
|
||||
### 1. Get API Key (Free)
|
||||
|
||||
1. Access https://quickstats.nass.usda.gov/api#registration
|
||||
2. Fill form:
|
||||
- Name: [your name]
|
||||
- Email: [your email]
|
||||
- Purpose: "Personal research"
|
||||
3. Click "Submit"
|
||||
4. You'll receive email with API key in ~1 minute
|
||||
5. Key format: `A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6`
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
**Option A - Export** (temporary):
|
||||
```bash
|
||||
export NASS_API_KEY="your_key_here"
|
||||
```
|
||||
|
||||
**Option B - .bashrc/.zshrc** (permanent):
|
||||
```bash
|
||||
echo 'export NASS_API_KEY="your_key_here"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
**Option C - .env file** (per project):
|
||||
```bash
|
||||
echo "NASS_API_KEY=your_key_here" > .env
|
||||
```
|
||||
|
||||
### 3. Install Dependencies
|
||||
|
||||
```bash
|
||||
cd nass-usda-agriculture
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Requirements:
|
||||
- requests
|
||||
- pandas
|
||||
- numpy
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
## Installation
|
||||
|
||||
1. Get API key from the official website
|
||||
2. Configure environment
|
||||
3. Install dependencies
|
||||
4. Done!
|
||||
```
|
||||
|
||||
**2. Concrete usage examples**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
## Examples
|
||||
|
||||
### Example 1: Current Production
|
||||
|
||||
```
|
||||
You: "What's US corn production in 2023?"
|
||||
|
||||
Claude: "Corn production in 2023 was 15.3 billion
|
||||
bushels (389 million metric tons)..."
|
||||
```
|
||||
|
||||
### Example 2: YoY Comparison
|
||||
|
||||
```
|
||||
You: "Compare soybeans this year vs last year"
|
||||
|
||||
Claude: "Soybean production in 2023 is 2.6% below 2022:
|
||||
- 2023: 4.165 billion bushels
|
||||
- 2022: 4.276 billion bushels
|
||||
- Drop from area (-4.5%), yield improved (+0.8%)"
|
||||
```
|
||||
|
||||
[3-5 more examples]
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
## Usage
|
||||
|
||||
Ask questions about agriculture and the agent will respond.
|
||||
```
|
||||
|
||||
**3. Specific troubleshooting**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
### Error: "NASS_API_KEY environment variable not found"
|
||||
|
||||
**Cause**: API key not configured
|
||||
|
||||
**Step-by-step solution**:
|
||||
1. Verify key was obtained: https://...
|
||||
2. Configure environment:
|
||||
```bash
|
||||
export NASS_API_KEY="your_key_here"
|
||||
```
|
||||
3. Verify:
|
||||
```bash
|
||||
echo $NASS_API_KEY
|
||||
```
|
||||
4. Should show your key
|
||||
5. If doesn't work, restart terminal
|
||||
|
||||
**Still not working?**
|
||||
- Check for extra spaces in key
|
||||
- Verify key hasn't expired (validity: 1 year)
|
||||
- Re-generate key if needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
### Per Python Script
|
||||
|
||||
- [ ] Shebang: `#!/usr/bin/env python3`
|
||||
- [ ] Module docstring (3-5 lines)
|
||||
- [ ] Organized imports (stdlib, 3rd party, local)
|
||||
- [ ] Constants at top (if applicable)
|
||||
- [ ] Type hints in all public functions
|
||||
- [ ] Docstrings in classes (description + attributes + example)
|
||||
- [ ] Docstrings in methods (Args, Returns, Raises, Example)
|
||||
- [ ] Error handling for risky operations
|
||||
- [ ] Input validations
|
||||
- [ ] Output validations
|
||||
- [ ] Appropriate logging
|
||||
- [ ] Main function with argparse
|
||||
- [ ] if __name__ == "__main__"
|
||||
- [ ] Functional code (no TODO/pass)
|
||||
- [ ] Valid syntax (test: `python -m py_compile script.py`)
|
||||
|
||||
### Per SKILL.md
|
||||
|
||||
- [ ] Frontmatter with name and description
|
||||
- [ ] Description 150-250 characters with keywords
|
||||
- [ ] Size 5000+ words
|
||||
- [ ] "When to Use" section with specific triggers
|
||||
- [ ] "Data Source" section detailed
|
||||
- [ ] Step-by-step workflows with commands
|
||||
- [ ] Scripts explained individually
|
||||
- [ ] Analyses documented (objective, methodology)
|
||||
- [ ] Errors handled (all expected)
|
||||
- [ ] Validations listed
|
||||
- [ ] Performance/cache explained
|
||||
- [ ] Complete keywords
|
||||
- [ ] Complete examples (5+)
|
||||
|
||||
### Per Reference File
|
||||
|
||||
- [ ] 1000+ words
|
||||
- [ ] Useful content (not just links)
|
||||
- [ ] Concrete examples with real values
|
||||
- [ ] Executable code blocks
|
||||
- [ ] Well structured (headings, lists)
|
||||
- [ ] No empty sections
|
||||
- [ ] No "TODO: write"
|
||||
|
||||
### Per Asset (Config)
|
||||
|
||||
- [ ] Syntactically valid JSON (validate!)
|
||||
- [ ] Real values (not "YOUR_X_HERE" without context)
|
||||
- [ ] Inline comments (_comment, _note)
|
||||
- [ ] Instructions for values user must fill
|
||||
- [ ] Logical and organized structure
|
||||
|
||||
### Per README.md
|
||||
|
||||
- [ ] Step-by-step installation
|
||||
- [ ] How to get API key (detailed)
|
||||
- [ ] How to configure (3 options)
|
||||
- [ ] How to install dependencies
|
||||
- [ ] How to install in Claude Code
|
||||
- [ ] Usage examples (5+)
|
||||
- [ ] Troubleshooting (10+ problems)
|
||||
- [ ] License
|
||||
- [ ] Contact/contribution (if applicable)
|
||||
|
||||
### Complete Agent
|
||||
|
||||
- [ ] DECISIONS.md documents all choices
|
||||
- [ ] **VERSION** file created (e.g. 1.0.0)
|
||||
- [ ] **CHANGELOG.md** created with complete v1.0.0 entry
|
||||
- [ ] **INSTALACAO.md** with complete didactic tutorial
|
||||
- [ ] **comprehensive_{domain}_report()** implemented
|
||||
- [ ] marketplace.json with version field
|
||||
- [ ] 18+ files created
|
||||
- [ ] ~1500+ lines of Python code
|
||||
- [ ] ~10,000+ words of documentation
|
||||
- [ ] 2+ configs
|
||||
- [ ] requirements.txt
|
||||
- [ ] .gitignore (if needed)
|
||||
- [ ] No placeholder/TODO
|
||||
- [ ] Valid syntax (Python, JSON, YAML)
|
||||
- [ ] Ready to use (production-ready)
|
||||
|
||||
---
|
||||
|
||||
## Quality Examples
|
||||
|
||||
### Example: Error Handling
|
||||
|
||||
❌ **BAD**:
|
||||
```python
|
||||
def fetch(url):
|
||||
return requests.get(url).json()
|
||||
```
|
||||
|
||||
✅ **GOOD**:
|
||||
```python
|
||||
def fetch(url: str, timeout: int = 30) -> Dict:
|
||||
"""
|
||||
Fetch data from URL with error handling
|
||||
|
||||
Args:
|
||||
url: URL to fetch
|
||||
timeout: Timeout in seconds
|
||||
|
||||
Returns:
|
||||
JSON response as dict
|
||||
|
||||
Raises:
|
||||
NetworkError: If connection fails
|
||||
TimeoutError: If request times out
|
||||
APIError: If API returns error
|
||||
"""
|
||||
try:
|
||||
response = requests.get(url, timeout=timeout)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
|
||||
if 'error' in data:
|
||||
raise APIError(f"API error: {data['error']}")
|
||||
|
||||
return data
|
||||
|
||||
except requests.Timeout:
|
||||
raise TimeoutError(f"Request timed out after {timeout}s")
|
||||
|
||||
except requests.ConnectionError as e:
|
||||
raise NetworkError(f"Connection failed: {e}")
|
||||
|
||||
except requests.HTTPError as e:
|
||||
if e.response.status_code == 429:
|
||||
raise RateLimitError("Rate limit exceeded")
|
||||
else:
|
||||
raise APIError(f"HTTP {e.response.status_code}: {e}")
|
||||
```
|
||||
|
||||
### Example: Validations
|
||||
|
||||
❌ **BAD**:
|
||||
```python
|
||||
def parse(data):
|
||||
df = pd.DataFrame(data)
|
||||
return df
|
||||
```
|
||||
|
||||
✅ **GOOD**:
|
||||
```python
|
||||
def parse(data: List[Dict]) -> pd.DataFrame:
|
||||
"""Parse and validate data"""
|
||||
|
||||
# Validate input
|
||||
if not data:
|
||||
raise ValueError("Data cannot be empty")
|
||||
|
||||
if not isinstance(data, list):
|
||||
raise TypeError(f"Expected list, got {type(data)}")
|
||||
|
||||
# Parse
|
||||
df = pd.DataFrame(data)
|
||||
|
||||
# Validate schema
|
||||
required_cols = ['year', 'commodity', 'value']
|
||||
missing = set(required_cols) - set(df.columns)
|
||||
if missing:
|
||||
raise ValueError(f"Missing required columns: {missing}")
|
||||
|
||||
# Validate types
|
||||
df['year'] = pd.to_numeric(df['year'], errors='raise')
|
||||
df['value'] = pd.to_numeric(df['value'], errors='raise')
|
||||
|
||||
# Validate ranges
|
||||
current_year = datetime.now().year
|
||||
if (df['year'] > current_year).any():
|
||||
raise ValueError(f"Future years found (max allowed: {current_year})")
|
||||
|
||||
if (df['value'] < 0).any():
|
||||
raise ValueError("Negative values found")
|
||||
|
||||
# Validate no duplicates
|
||||
if df.duplicated(subset=['year', 'commodity']).any():
|
||||
raise ValueError("Duplicate records found")
|
||||
|
||||
return df
|
||||
```
|
||||
|
||||
### Example: Docstrings
|
||||
|
||||
❌ **BAD**:
|
||||
```python
|
||||
def analyze(df, commodity):
|
||||
"""Analyze data"""
|
||||
# ...
|
||||
```
|
||||
|
||||
✅ **GOOD**:
|
||||
```python
|
||||
def analyze_yoy(
|
||||
df: pd.DataFrame,
|
||||
commodity: str,
|
||||
year1: int,
|
||||
year2: int
|
||||
) -> Dict[str, Any]:
|
||||
"""
|
||||
Perform year-over-year comparison analysis
|
||||
|
||||
Compares production, area, and yield between two years
|
||||
and decomposes growth into area vs yield contributions.
|
||||
|
||||
Args:
|
||||
df: DataFrame with columns ['year', 'commodity', 'production', 'area', 'yield']
|
||||
commodity: Commodity name (e.g., "CORN", "SOYBEANS")
|
||||
year1: Current year to compare
|
||||
year2: Previous year to compare against
|
||||
|
||||
Returns:
|
||||
Dict containing:
|
||||
- production_current (float): Production in year1 (million units)
|
||||
- production_previous (float): Production in year2
|
||||
- change_absolute (float): Absolute change
|
||||
- change_percent (float): Percent change
|
||||
- decomposition (dict): Area vs yield contribution
|
||||
- interpretation (str): "increase", "decrease", or "stable"
|
||||
|
||||
Raises:
|
||||
ValueError: If commodity not found in data
|
||||
ValueError: If either year not found in data
|
||||
DataQualityError: If production != area * yield (tolerance > 1%)
|
||||
|
||||
Example:
|
||||
>>> df = pd.DataFrame([
|
||||
... {'year': 2023, 'commodity': 'CORN', 'production': 15.3, 'area': 94.6, 'yield': 177},
|
||||
... {'year': 2022, 'commodity': 'CORN', 'production': 13.7, 'area': 89.2, 'yield': 173}
|
||||
... ])
|
||||
>>> result = analyze_yoy(df, "CORN", 2023, 2022)
|
||||
>>> result['change_percent']
|
||||
11.7
|
||||
"""
|
||||
# [Complete implementation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Anti-Pattern 1: Partial Implementation
|
||||
|
||||
❌ **NO**:
|
||||
```python
|
||||
def yoy_comparison(df, commodity, year1, year2):
|
||||
# Implement YoY comparison
|
||||
pass
|
||||
|
||||
def state_ranking(df, commodity):
|
||||
# TODO: implement ranking
|
||||
raise NotImplementedError()
|
||||
```
|
||||
|
||||
✅ **YES**:
|
||||
```python
|
||||
# [Complete and functional code for BOTH functions]
|
||||
```
|
||||
|
||||
### Anti-Pattern 2: Empty References
|
||||
|
||||
❌ **NO**:
|
||||
```markdown
|
||||
# Analysis Methods
|
||||
|
||||
## YoY Comparison
|
||||
|
||||
This method compares two years.
|
||||
|
||||
## Ranking
|
||||
|
||||
This method ranks states.
|
||||
```
|
||||
|
||||
✅ **YES**:
|
||||
```markdown
|
||||
# Analysis Methods
|
||||
|
||||
## YoY Comparison
|
||||
|
||||
### Objective
|
||||
Compare metrics between current and previous year...
|
||||
|
||||
### Detailed Methodology
|
||||
|
||||
**Formulas**:
|
||||
```
|
||||
Δ X = X(t) - X(t-1)
|
||||
Δ X% = (Δ X / X(t-1)) × 100
|
||||
```
|
||||
|
||||
**Decomposition** (for production):
|
||||
[Complete mathematics]
|
||||
|
||||
**Interpretation**:
|
||||
- |Δ| < 2%: Stable
|
||||
- Δ > 10%: Significant increase
|
||||
[...]
|
||||
|
||||
### Validations
|
||||
[List]
|
||||
|
||||
### Complete Numerical Example
|
||||
[With real values]
|
||||
```
|
||||
|
||||
### Anti-Pattern 3: Useless Configs
|
||||
|
||||
❌ **NO**:
|
||||
```json
|
||||
{
|
||||
"api_url": "INSERT_URL",
|
||||
"api_key": "INSERT_KEY"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **YES**:
|
||||
```json
|
||||
{
|
||||
"_comment": "Configuration for NASS USDA Agent",
|
||||
"api": {
|
||||
"base_url": "https://quickstats.nass.usda.gov/api",
|
||||
"_note": "This is the official USDA NASS API base URL",
|
||||
"api_key_env": "NASS_API_KEY",
|
||||
"_key_instructions": "Get free API key from: https://quickstats.nass.usda.gov/api#registration"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Validation
|
||||
|
||||
Before delivering to user, verify:
|
||||
|
||||
### Sanity Test
|
||||
|
||||
```bash
|
||||
# 1. Python syntax
|
||||
find scripts -name "*.py" -exec python -m py_compile {} \;
|
||||
|
||||
# 2. JSON syntax
|
||||
python -c "import json; json.load(open('assets/config.json'))"
|
||||
|
||||
# 3. Imports make sense
|
||||
grep -r "^import\|^from" scripts/*.py | sort | uniq
|
||||
# Verify all libs are: stdlib, requests, pandas, numpy
|
||||
# No imports of uninstalled libs
|
||||
|
||||
# 4. SKILL.md has frontmatter
|
||||
head -5 SKILL.md | grep "^---$"
|
||||
|
||||
# 5. SKILL.md size
|
||||
wc -w SKILL.md
|
||||
# Should be > 5000 words
|
||||
```
|
||||
|
||||
### Final Checklist
|
||||
|
||||
- [ ] Syntax check passed (Python, JSON)
|
||||
- [ ] No import of non-existent lib
|
||||
- [ ] No TODO or pass
|
||||
- [ ] SKILL.md > 5000 words
|
||||
- [ ] References with content
|
||||
- [ ] README with complete instructions
|
||||
- [ ] DECISIONS.md created
|
||||
- [ ] requirements.txt created
|
||||
Loading…
Reference in a new issue