admin-valentin/agent-skill-creator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agent-skill-creator/Dynamous/Content-Ideation/vscode-copilot-simulation.txt
Francy Lisboa Charuto 0663e3ef8a docs: Add "Don't Make Humans Be Clear" design principle + messy input simulations 
5 realistic interactions showing how agent-skill-creator must work
with inarticulate, messy human input — not clean specifications:

1. The File Dump — analyst drags 5 files and types "here"
2. The URL Dump — half-sentence with 2 URLs and "same thing as wasde"
3. The Screenshot + Complaint — Paint-annotated Bloomberg screenshot
   and "this is ridiculous" (reveals the workflow was unnecessary —
   data already existed in Databricks)
4. The Forwarded Email — 6-message chain with legal disclaimers,
   agent extracts the one useful paragraph from Oliver in London
5. The One Word — analyst types "freight", agent infers from desk
   context, Databricks catalog, and colleague skills

Closes with 6 design principles: file interpretation over requirements
gathering, context inference, progressive refinement, discovery over
assumption, confirm don't interrogate, fail forward not fail safe.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 18:25:56 -03:00

6473 lines
332 KiB
Text
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Simulated Interaction: VS Code Copilot + agent-skill-creator
=============================================================
---
Setup (one time, already done)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.agents/skills/agent-skill-creator
VS Code Copilot, Claude Code, Gemini CLI, and other tools find it at
~/.agents/skills/ automatically (symlinked to tool-specific paths by
the installer).
---
The Interaction
The user opens VS Code, opens Copilot Chat (Agent mode), and types:
User: /agent-skill-creator Every month I pull customer churn data from our Stripe API and Mixpanel, segment customers by plan tier and usage drop-off, calculate churn risk scores, and generate a PDF report for the leadership team. Here's our current script: scripts/churn_analysis.py
Copilot (loading agent-skill-creator skill):
I'll build a complete agent skill from your churn analysis workflow. Let me start by reading your existing script and understanding the full picture.
Reading scripts/churn_analysis.py...
I can see this pulls from Stripe's subscription API and Mixpanel's engagement endpoint, segments by 3 plan tiers, and uses a weighted scoring model. Let me uncover the implicit requirements before building.
Implicit requirements I've identified:
- Error handling when Stripe/Mixpanel APIs are unreachable
- Date range defaults (last 30 days) vs custom ranges
- The PDF needs the Acme Corp header and formatting your leadership team expects
- Churn risk thresholds (>0.7 = high, >0.4 = medium) are hardcoded — should be configurable
- No handling for new customers with insufficient data
Building the skill now...
(Copilot creates the full skill directory)
customer-churn-skill/
├── SKILL.md # Activation: /customer-churn-skill
├── scripts/
│ ├── churn_analysis.py # Core analysis (refactored from your script)
│ ├── stripe_connector.py # Stripe API integration
│ ├── mixpanel_connector.py # Mixpanel API integration
│ └── pdf_report.py # PDF generation with formatting
├── references/
│ ├── scoring-model.md # Churn risk scoring methodology
│ ├── api-endpoints.md # Stripe + Mixpanel endpoint docs
│ └── report-format.md # PDF layout specification
├── assets/
│ └── report_template.html # PDF template
├── install.sh # Cross-platform installer (14 tools)
└── README.md # Installation instructions
Validation results:
- Spec compliance: PASSED (frontmatter, naming, structure, references)
- Security scan: PASSED (no hardcoded API keys, credentials use environment variables)
Installed at: ~/.agents/skills/customer-churn-skill
To use it, start a new chat and type:
/customer-churn-skill Generate the monthly churn report for March
Or with custom parameters:
/customer-churn-skill Analyze churn for Enterprise tier only, last 90 days
Want to share this skill with your team so they can install it too?
---
User: Yes, we use GitHub
Copilot:
Setting up sharing...
cd customer-churn-skill
git init
git add -A
git commit -m "feat: Initial skill — customer-churn-skill"
gh repo create customer-churn-skill --private --source=. --push
Done! Share this with your team:
# For VS Code Copilot / Claude Code:
git clone https://github.com/your-org/customer-churn-skill.git ~/.agents/skills/customer-churn-skill
# For Codex CLI / Gemini CLI / Kiro:
git clone https://github.com/your-org/customer-churn-skill.git ~/.agents/skills/customer-churn-skill
# For Cursor (per-project):
git clone https://github.com/your-org/customer-churn-skill.git .cursor/rules/customer-churn-skill
# Or install everywhere at once:
npx skills add your-org/customer-churn-skill
Your colleagues paste one line, and they can type /customer-churn-skill in their agent.
---
Later that week — a colleague uses it
The colleague cloned it. They open VS Code Copilot and type:
Colleague: /customer-churn-skill Which Enterprise customers are highest churn risk this month? Include a breakdown by usage drop-off category.
Copilot (loading customer-churn-skill):
Running churn analysis for Enterprise tier, March 2026...
Connecting to Stripe API... (uses STRIPE_API_KEY from env)
Connecting to Mixpanel... (uses MIXPANEL_TOKEN from env)
Enterprise Churn Risk Report — March 2026
| Customer | Plan | Risk Score | Drop-off Category | MRR |
|---------------|-----------------|------------|---------------------|---------|
| Acme Corp | Enterprise Plus | 0.89 | Feature abandonment | $12,400 |
| DataFlow Inc | Enterprise | 0.76 | Login frequency | $8,200 |
| NorthStar Ltd | Enterprise | 0.72 | Support escalation | $6,800 |
| ... | | | | |
7 Enterprise accounts flagged as high-risk ($94,200 combined MRR at risk).
PDF report generated at ./reports/churn-enterprise-2026-03.pdf.
Want me to email this to the leadership distribution list?
---
Key difference from raw Copilot
Without the skill, the colleague would have had to explain: which APIs, which endpoints, what scoring model, what PDF format, what "churn risk" means in their org. With the skill installed, they just say what they want and it already knows all of that.
=============================================================
AGRICULTURE COMMODITY RESEARCH TEAM — FULL SCENARIO
=============================================================
Context: A 6-person ag commodity research team at a trading firm. They cover soybeans, corn, wheat, and coffee. Every analyst repeats the same data-pulling, report-building, and market-monitoring workflows daily. The team lead decides to turn these into shared skills.
=============================================================
SKILL 1: WASDE Report Analyzer
=============================================================
The senior grain analyst opens VS Code Copilot:
User: /agent-skill-creator Every month when USDA releases the WASDE report, I download the PDF from usda.gov, extract the supply and demand tables for corn, soybeans, and wheat, compare the new estimates against last month and against the market consensus (which I pull from a Bloomberg terminal CSV export), flag any revisions greater than 2%, and write a 2-page brief for the trading desk with a "surprise score" for each commodity. Here's last month's brief as an example: references/wasde-brief-feb-2026.pdf
Copilot (loading agent-skill-creator skill):
I'll build a skill from your WASDE analysis workflow. Let me read your example brief first.
Reading references/wasde-brief-feb-2026.pdf...
I can see the structure: header with release date and report number, a table per commodity showing Old USDA / New USDA / Consensus / Surprise, then a narrative section interpreting the numbers for the trading desk. Let me identify implicit requirements.
Implicit requirements I've identified:
- WASDE PDF table extraction needs to handle USDA's inconsistent formatting across years
- "Consensus" comes from a Bloomberg CSV export — need to define the expected column format
- Surprise score formula: |(New USDA - Consensus)| / Consensus * 100, flagged if > 2%
- The brief must separate US domestic vs world balance sheets
- Ending stocks and stocks-to-use ratio are the key numbers the desk cares about
- Historical comparison should include the 5-year average, not just last month
- Wheat needs to be split: all wheat, HRW, SRW, HRS separately
- The desk wants this within 30 minutes of USDA release — speed matters
Building the skill now...
wasde-analyzer-skill/
├── SKILL.md # Activation: /wasde-analyzer-skill
├── scripts/
│ ├── wasde_parser.py # USDA PDF table extraction
│ ├── consensus_loader.py # Bloomberg CSV import + validation
│ ├── surprise_calculator.py # Surprise score engine
│ ├── brief_generator.py # 2-page PDF brief builder
│ └── historical_compare.py # 5-year avg + month-over-month
├── references/
│ ├── wasde-table-format.md # USDA table layout documentation
│ ├── commodity-codes.md # USDA commodity ID mappings
│ ├── surprise-methodology.md # Surprise score formula + thresholds
│ └── brief-template.md # Trading desk brief structure
├── assets/
│ ├── brief_template.html # PDF template with firm header
│ └── sample_consensus.csv # Expected Bloomberg export format
├── install.sh # Cross-platform installer (14 tools)
└── README.md
Validation: PASSED | Security: PASSED
Installed at: ~/.agents/skills/wasde-analyzer-skill
To use it:
/wasde-analyzer-skill Analyze the March 2026 WASDE, consensus file at data/bloomberg-consensus-mar26.csv
Want to share this with your team?
User: Yes
Copilot:
gh repo create acme-trading/wasde-analyzer-skill --private --source=. --push
Share with your team:
git clone https://github.com/acme-trading/wasde-analyzer-skill.git ~/.agents/skills/wasde-analyzer-skill
--- On WASDE release day, a junior analyst uses it ---
Junior Analyst: /wasde-analyzer-skill WASDE just dropped. Consensus file is at data/bloomberg-mar26.csv. Run the full analysis for corn, soybeans, and wheat.
Copilot (loading wasde-analyzer-skill):
Downloading March 2026 WASDE from USDA...
Extracting supply/demand tables...
Loading consensus from data/bloomberg-mar26.csv...
Calculating surprise scores...
WASDE SURPRISE BRIEF — March 11, 2026
CORN (US)
| Metric | Feb USDA | Mar USDA | Consensus | Surprise |
|---------------------|----------|----------|-----------|----------|
| Production (mil bu) | 15,143 | 15,143 | 15,143 | 0.0% |
| Ending Stocks | 1,540 | 1,490 | 1,525 | -2.3% * |
| Stocks/Use | 10.4% | 10.1% | 10.3% | |
* BULLISH SURPRISE: USDA cut corn ending stocks 50 mil bu below consensus.
Driven by higher ethanol demand estimate (+25 mil bu) and feed/residual
revision. This is the tightest S/U ratio since 2023/24.
SOYBEANS (US)
| Metric | Feb USDA | Mar USDA | Consensus | Surprise |
|---------------------|----------|----------|-----------|----------|
| Production (mil bu) | 4,366 | 4,366 | 4,366 | 0.0% |
| Ending Stocks | 380 | 370 | 385 | -3.9% * |
| Stocks/Use | 8.6% | 8.4% | 8.7% | |
* BULLISH SURPRISE: Crush raised 15 mil bu, exports raised 10 mil bu.
Brazil's crop estimate unchanged at 169 MMT — market expected a cut.
WHEAT (ALL — US)
| Metric | Feb USDA | Mar USDA | Consensus | Surprise |
|---------------------|----------|----------|-----------|----------|
| Ending Stocks | 794 | 798 | 790 | +1.0% |
No surprise. Wheat largely unchanged. HRW stocks marginally higher on
lower food use estimate.
OVERALL SURPRISE SCORE: 6.2 / 10 (Moderately bullish grains)
PDF brief generated: reports/wasde-brief-2026-03-11.pdf
Key takeaway for the desk: Corn and beans both tighter than expected.
The corn stocks cut is the headline — first sub-1,500 ending stocks
estimate this marketing year. Watch the May corn contract for a gap
higher on the open.
Want me to email this to the trading desk distribution list?
=============================================================
SKILL 2: Crop Condition & Weather Monitor
=============================================================
The weather/crop analyst on the team creates another skill:
User: /agent-skill-creator Every Monday during growing season (April-October) I check the USDA Crop Progress report for corn and soybean condition ratings, compare good/excellent percentages against the 5-year average and last year, pull 7-day and 14-day weather forecasts from NOAA for the Corn Belt states (Iowa, Illinois, Indiana, Minnesota, Nebraska, Ohio), check soil moisture from the US Drought Monitor, and write a "Crop & Weather Weekly" for our research clients. I also maintain a chart tracking the condition index through the season. Here are my notes on how I calculate the crop condition index: references/condition-index-formula.txt
Copilot (loading agent-skill-creator skill):
Reading references/condition-index-formula.txt...
I see — you use the Brugler weighted index: (Very Poor * 1 + Poor * 2 + Fair * 3 + Good * 4 + Excellent * 5) / 5. This gives a single score out of 100. Let me build this.
Implicit requirements I've identified:
- Crop Progress data comes from USDA NASS Quick Stats API
- NOAA forecast needs to cover precipitation AND temperature (GDD accumulation)
- Drought Monitor categories: D0-D4 mapped to severity scores
- Growing Degree Days (GDD) tracking: base 50F for corn, base 50F for soybeans
- Client report needs both narrative + embedded charts (condition index trend, precip map)
- State-level breakdown matters — an Iowa drought doesn't offset Illinois rain
- The weekly cadence means the skill should know what "week" of the growing season it is
- Planting progress in April-May, then shifts to condition ratings June-October
Building...
crop-weather-weekly-skill/
├── SKILL.md
├── scripts/
│ ├── crop_progress.py # USDA NASS API — condition ratings + planting progress
│ ├── weather_forecast.py # NOAA 7/14-day forecast by state
│ ├── drought_monitor.py # US Drought Monitor data pull
│ ├── condition_index.py # Brugler weighted index calculator
│ ├── gdd_tracker.py # Growing degree day accumulation
│ ├── charts.py # Condition trend + precip charts
│ └── weekly_report.py # PDF/HTML report builder
├── references/
│ ├── corn-belt-states.md # State FIPS codes, county groupings
│ ├── condition-methodology.md # Index formula, historical baselines
│ ├── gdd-requirements.md # GDD targets by growth stage
│ └── client-report-format.md # Report layout spec
├── assets/
│ └── report_template.html
├── install.sh
└── README.md
Validation: PASSED | Security: PASSED
Installed at: ~/.agents/skills/crop-weather-weekly-skill
Share with your team?
User: Yes, same GitHub org
Copilot:
gh repo create acme-trading/crop-weather-weekly-skill --private --source=. --push
Done! Your team:
git clone https://github.com/acme-trading/crop-weather-weekly-skill.git ~/.agents/skills/crop-weather-weekly-skill
--- Monday morning during growing season ---
Analyst: /crop-weather-weekly-skill Generate the Crop & Weather Weekly for the week of July 14, 2026. Focus on the drought situation in western Iowa and Nebraska.
Copilot (loading crop-weather-weekly-skill):
Pulling USDA Crop Progress (released 4:00pm ET yesterday)...
Pulling NOAA 7-day and 14-day forecasts for Corn Belt...
Pulling US Drought Monitor (updated Thursday)...
Calculating condition indices...
CROP & WEATHER WEEKLY — July 14, 2026
CORN CONDITION
| State | G/E This Week | G/E Last Week | G/E 5yr Avg | Condition Index |
|-----------|---------------|---------------|-------------|-----------------|
| Iowa | 54% | 61% | 68% | 322 (below avg) |
| Illinois | 71% | 70% | 66% | 361 (above avg) |
| Indiana | 68% | 67% | 63% | 355 (above avg) |
| Minnesota | 63% | 64% | 65% | 345 (at avg) |
| Nebraska | 48% | 55% | 62% | 308 (well below)|
| Ohio | 72% | 71% | 64% | 362 (above avg) |
| NATIONAL | 62% | 64% | 65% | 344 |
Week-over-week: National corn conditions slipped 2 points. The decline is
concentrated in the western Corn Belt — Iowa dropped 7 points and Nebraska
dropped 7 points. Eastern Belt is steady to improving.
DROUGHT SITUATION
Western Iowa: 43% of the state now in D2 (severe drought), up from 31%
last week. The I-80 corridor west of Des Moines through Council Bluffs is
the epicenter. Subsoil moisture rated 62% short/very short.
Nebraska: 51% in D1 or worse. The Platte River valley from Grand Island
to North Platte hasn't received meaningful rain in 23 days. Center-pivot
irrigation is running but aquifer draw-down is being reported.
WEATHER OUTLOOK
7-day: A ridge holds over the western Plains through Thursday. Temps
100-105F in western Iowa/Nebraska. No significant precip until a cold
front arrives Saturday with scattered storms (0.25-0.75 inches, not
drought-breaking).
14-day: GFS and Euro diverge after day 8. Euro shows the ridge breaking
down with a pattern change toward more active weather. GFS keeps the
ridge. If the Euro verifies, meaningful relief arrives July 25-28.
GDD ACCUMULATION (corn, base 50F, since April 15)
| State | Actual GDD | Normal GDD | Deviation |
|-----------|------------|------------|-----------|
| Iowa | 1,842 | 1,710 | +132 (ahead — heat stress risk) |
| Illinois | 1,920 | 1,805 | +115 |
| Nebraska | 1,780 | 1,690 | +90 |
KEY TAKEAWAY: Western Corn Belt stress is accelerating during pollination
week for early-planted corn in Iowa and Nebraska. If the Euro's pattern
change doesn't verify, we could see another 3-5 point condition drop
next week. The east is fine. This is a "tale of two Corn Belts" story.
National corn condition index at 344 is the lowest for this week since
2022 (338) but well above 2012 drought (278).
[Condition Index Trend Chart embedded — shows 2026 line dipping below
5yr avg band, with 2012 and 2022 comparison lines]
PDF report generated: reports/crop-weather-weekly-2026-07-14.pdf
Want me to email this to the client distribution list?
=============================================================
SKILL 3: Basis Tracker & Export Monitor
=============================================================
The logistics/basis analyst creates a third skill:
User: /agent-skill-creator I track soybean and corn basis at 12 river elevators along the Mississippi and Illinois rivers. Every day I pull bids from DTN/Progressive Farmer, calculate basis vs the nearby CBOT futures contract, compare to the 3-year seasonal average, and flag any locations where basis moved more than 5 cents in a day. I also pull weekly USDA Export Inspections and Export Sales data to see if physical demand explains the basis moves. On Fridays I write a "Basis & Exports Weekly" for the team. Here's my spreadsheet with the 12 elevator locations and their historical basis patterns: data/elevator-basis-history.xlsx
Copilot (loading agent-skill-creator skill):
Reading data/elevator-basis-history.xlsx...
I see 12 elevators: Davenport IA, Muscatine IA, Burlington IA, Quincy IL, Beardstown IL, Havana IL, Peoria IL, Henry IL, Peru IL, St. Louis MO, Memphis TN, New Orleans LA (CIF Gulf). Each has daily basis history back to 2023. Let me build this.
Implicit requirements:
- "Nearby futures" rolls on first notice day — need a roll calendar
- Gulf basis (CIF NOLA) is the anchor — interior basis derives from it
- Barge freight rates affect interior basis — need to track St. Louis-Gulf freight
- Export Inspections = actual loadings (weekly, lagged). Export Sales = commitments (weekly, Thursday release)
- China/unknown destinations buying pattern is the key signal in export data
- Basis inversions between elevator locations signal logistical bottlenecks
- Harvest basis (Sep-Nov) behaves completely differently than non-harvest — seasonal model must account for this
Building...
basis-export-tracker-skill/
├── SKILL.md
├── scripts/
│ ├── basis_scraper.py # DTN bid scraping for 12 elevators
│ ├── futures_reference.py # CBOT nearby contract + roll calendar
│ ├── basis_calculator.py # Basis computation + 3yr seasonal avg
│ ├── alert_engine.py # 5-cent daily move alerts
│ ├── export_inspections.py # USDA weekly export inspections
│ ├── export_sales.py # USDA weekly export sales
│ ├── barge_freight.py # St. Louis-Gulf freight rates
│ └── weekly_report.py # Friday summary builder
├── references/
│ ├── elevator-locations.md # 12 locations, river mile markers, capacity
│ ├── roll-calendar.md # CBOT futures roll schedule
│ ├── seasonal-patterns.md # Basis seasonality by location
│ └── export-data-sources.md # USDA FAS endpoints
├── assets/
│ └── elevator_locations.json # Lat/long + DTN bid codes
├── install.sh
└── README.md
Validation: PASSED | Security: PASSED
Installed at: ~/.agents/skills/basis-export-tracker-skill
Shared to: github.com/acme-trading/basis-export-tracker-skill
--- Daily use by the team ---
Trader: /basis-export-tracker-skill What happened to corn basis at the river yesterday? I saw Gulf bids jumped.
Copilot (loading basis-export-tracker-skill):
Pulling yesterday's bids (March 3, 2026)...
CORN BASIS DAILY SNAPSHOT — March 3, 2026 (vs May 2026 CBOT)
| Location | Bid | Basis | Prev | Change | 3yr Avg | vs Avg |
|----------------|---------|--------|--------|--------|---------|---------|
| CIF NOLA | $4.82 | +38 | +30 | +8 * | +22 | +16 |
| Memphis | $4.58 | +14 | +10 | +4 | +5 | +9 |
| St. Louis | $4.49 | +5 | +2 | +3 | -8 | +13 |
| Peoria IL | $4.34 | -10 | -13 | +3 | -18 | +8 |
| Davenport IA | $4.27 | -17 | -19 | +2 | -25 | +8 |
| ... | | | | | | |
* ALERT: CIF Gulf corn jumped 8 cents. Largest single-day move since Jan 14.
WHAT'S DRIVING IT:
- USDA Export Sales (released Thursday): Net new corn sales of 1.82 MMT,
highest weekly total this marketing year. Unknown destinations (likely China)
booked 680,000 MT.
- Export Inspections (Monday): 1.24 MMT inspected for export, above the
pace needed to hit the USDA full-year estimate.
- Barge freight: St. Louis-Gulf up $0.45/ton this week. Low water on the
lower Mississippi near Greenville MS is creating delays — 48hr average
transit time now vs 36hr normal.
INTERPRETATION: Physical demand is pulling basis higher from the Gulf
upriver. The strength is real (export-driven) not just logistical. If
China continues buying at this pace, Gulf basis could push to +45/+50
which would pull interior basis another 5-8 cents higher.
--- Friday weekly report ---
Analyst: /basis-export-tracker-skill Generate the Basis & Exports Weekly.
Copilot:
Compiling week of Feb 28 - Mar 4, 2026...
BASIS & EXPORTS WEEKLY — March 4, 2026
HEADLINE: Gulf corn basis rallied 12 cents this week on Chinese buying.
Interior locations followed, with the entire river system firming 3-8 cents.
Soybean basis was quiet — Gulf steady at +58, interior unchanged.
CORN BASIS — WEEK OVER WEEK
[Table showing all 12 locations, weekly change, distance from seasonal avg]
The entire Mississippi River corn basis curve steepened this week.
Gulf-to-Davenport spread widened to 55 cents (vs 47 cents 3yr avg for
this week). This signals strong export pull but also tight barge
logistics. Barge freight at $14.20/ton is 18% above seasonal average.
EXPORT SCOREBOARD
| Commodity | Sales This Week | Cumulative | USDA Target | Pace |
|-----------|-----------------|------------|-------------|--------|
| Corn | 1.82 MMT | 42.1 MMT | 58.4 MMT | 104% |
| Soybeans | 0.44 MMT | 39.8 MMT | 49.7 MMT | 98% |
Corn export pace is now 4% ahead of the USDA projection. If this
continues, the April WASDE will likely raise the export estimate by
50-75 mil bu, tightening ending stocks further.
TOP BUYERS THIS WEEK (CORN)
| Destination | Volume | Notes |
|--------------------|-----------|---------------------------|
| Unknown (China) | 680,000 MT| 3rd consecutive large week |
| Mexico | 412,000 MT| Steady, as expected |
| Japan | 289,000 MT| Normal pace |
| Colombia | 145,000 MT| Above average |
PDF report generated: reports/basis-exports-weekly-2026-03-04.pdf
=============================================================
SKILL 4: Coffee Fundamental Monitor
=============================================================
The soft commodities analyst covers coffee:
User: /agent-skill-creator I monitor the global coffee market — arabica and robusta. Every week I check Brazil's CEPEA daily prices, pull ICE certified stock reports for arabica (from ICE exchange data), check Vietnam and Brazil export data from their customs agencies, track the CFTC Commitment of Traders for managed money positioning in KC coffee futures, and monitor weather in Minas Gerais (Brazil), Espirito Santo (Brazil), and the Central Highlands (Vietnam). I also watch the arabica/robusta spread because it signals substitution pressure. When frost risk hits Brazil's coffee belt in June-August, I need to be able to quickly assess the threat. Here's my methodology doc: references/coffee-research-methodology.pdf
Copilot (loading agent-skill-creator skill):
Reading references/coffee-research-methodology.pdf (12 pages)...
Comprehensive framework. I see your frost risk model uses elevation bands in Minas Gerais (areas above 900m are safe, below 700m are high risk), historical frost dates, and ECMWF ensemble forecasts for minimum temperatures. Let me build this.
Implicit requirements:
- CEPEA prices are in BRL/bag — need USD conversion using BCB exchange rate API
- ICE certified stocks distinguish between pending grading, passed, and failed
- Brazil export data from CECAFE (monthly), Vietnam from customs (lagged 2-3 weeks)
- COT data: managed money net long/short as % of open interest is the key metric, not raw contracts
- Arabica/robusta spread: KC minus RC (converted to common units), watch for narrowing below historical range
- Frost: only matters June 15 - August 15, south of 22°S latitude, below 800m elevation
- The coffee marketing year is different (Jul-Jun for Brazil arabica, Oct-Sep for Vietnam robusta)
- Flowering season (Sep-Nov in Brazil) is the other critical weather window
Building...
coffee-fundamental-skill/
├── SKILL.md
├── scripts/
│ ├── cepea_prices.py # Brazil domestic price scraper
│ ├── ice_certified_stocks.py # ICE arabica warehouse stocks
│ ├── brazil_exports.py # CECAFE monthly export data
│ ├── vietnam_exports.py # Vietnam customs export data
│ ├── cot_positioning.py # CFTC COT managed money parser
│ ├── arb_rob_spread.py # Arabica/robusta spread tracker
│ ├── frost_monitor.py # ECMWF frost risk model
│ ├── brazil_weather.py # Minas Gerais + Espirito Santo weather
│ ├── vietnam_weather.py # Central Highlands weather
│ └── weekly_report.py # Coffee Weekly builder
├── references/
│ ├── frost-risk-model.md # Elevation bands, historical frost events
│ ├── coffee-calendar.md # Marketing years, flowering/harvest windows
│ ├── brazil-regions.md # Minas Gerais sub-regions, elevation data
│ ├── data-sources.md # All API endpoints and data lags
│ └── spread-methodology.md # Arb/rob spread interpretation
├── assets/
│ └── minas-gerais-elevations.geojson
├── install.sh
└── README.md
Validation: PASSED | Security: PASSED
Installed at: ~/.agents/skills/coffee-fundamental-skill
Shared to: github.com/acme-trading/coffee-fundamental-skill
--- Frost scare in July ---
Coffee Analyst: /coffee-fundamental-skill Frost risk alert — GFS is showing a polar air mass pushing into Parana and southern Minas Gerais this weekend. Assess the threat to coffee.
Copilot (loading coffee-fundamental-skill):
Pulling ECMWF and GFS ensemble forecasts for coffee belt...
Loading elevation data for Minas Gerais sub-regions...
FROST RISK ASSESSMENT — July 18, 2026
MODEL GUIDANCE (minimum temperature forecasts, Saturday morning July 20)
| Sub-region | Elevation | GFS Min | ECMWF Min | Frost Risk |
|---------------------|-----------|---------|-----------|------------|
| Sul de Minas (<700m)| 650-700m | -1°C | +1°C | HIGH |
| Sul de Minas (>800m)| 800-1100m | +2°C | +3°C | LOW |
| Cerrado Mineiro | 800-1000m | +3°C | +4°C | MINIMAL |
| Triângulo Mineiro | 700-900m | +1°C | +3°C | MODERATE |
| Parana (north) | 400-600m | -3°C | -1°C | SEVERE |
| Espirito Santo | 500-700m | +5°C | +6°C | NONE |
THREAT ASSESSMENT:
Parana: SEVERE risk. But Parana is only ~5% of Brazil arabica production
(down from 25% in the 1990s — production shifted north after the 1994
frost). Impact would be limited to ~2-3 million bags maximum exposure.
Sul de Minas (low elevation): HIGH risk on GFS, moderate on ECMWF. This
is the critical area — Sul de Minas produces ~30% of Brazil's arabica.
However, the sub-700m low-elevation areas are a minority of production.
Most major farms are at 800-1100m where frost risk is low.
GFS vs ECMWF divergence: GFS is 2-3°C colder than ECMWF across all
regions. This matters. In the last 5 comparable events, ECMWF verified
closer to observed temps 4 out of 5 times.
HISTORICAL COMPARISON:
- July 2021 frost: Much more severe (widespread -3°C to -5°C across
Minas Gerais at all elevations). KC rallied 30% in 2 weeks.
- This event: More limited geographic scope. Closer to July 2023
scare that produced a 5% rally that fully reversed in 10 days.
MARKET POSITIONING:
Managed money is currently net long 42,300 contracts (68th percentile).
Not extreme — room for speculative buying on a frost headline.
ICE certified stocks: 812,000 bags, near 20-year lows. Low buffer =
larger price reaction to any supply shock.
BOTTOM LINE: This is a "watch closely but don't panic" event. The
probable impact is limited to low-elevation Parana and small pockets
of southern Minas Gerais. If ECMWF is right (+1°C in Sul de Minas),
this is a non-event. If GFS is right (-1°C), we're looking at
localized damage to 3-5% of the Brazil arabica crop.
Expect KC coffee to rally 3-5% on the headlines Friday/Monday regardless
of actual damage, given low certified stocks and the market's sensitivity
to anything frost-related after 2021.
Next update: I recommend re-running this Saturday when the 24-hour
forecast models converge.
=============================================================
THE TEAM'S SKILL LIBRARY — 3 MONTHS LATER
=============================================================
After 3 months, the 6-person team has built and shared these skills:
git clone .../wasde-analyzer-skill.git # Senior grain analyst
git clone .../crop-weather-weekly-skill.git # Weather/crop analyst
git clone .../basis-export-tracker-skill.git # Logistics/basis analyst
git clone .../coffee-fundamental-skill.git # Soft commodities analyst
git clone .../seasonal-spread-skill.git # Quantitative analyst
git clone .../client-briefing-skill.git # Research director
Every analyst has all 6 skills installed. The new hire who joined last
week cloned all 6 in 10 minutes and can now run any workflow the team
does — with institutional knowledge embedded in the skills.
The research director's /client-briefing-skill actually calls the other
skills internally to compile the firm's weekly flagship report. Skills
compose.
What used to take each analyst 2-3 hours of manual data pulling and
formatting now takes a single prompt. The team's output doubled. Their
research clients can't tell the difference — the reports look the same,
the analysis is the same. It's just faster, and the junior analyst can
produce the same quality as the senior.
That's the point: skills capture institutional knowledge so it doesn't
walk out the door when someone leaves, and it doesn't take 6 months
to transfer when someone new joins.
=============================================================
INSTALLING ALL TEAM SKILLS AT ONCE
=============================================================
New team member joins. The team lead sends them one message on Slack:
"Welcome! Run these to get all our research skills:"
curl -fsSL https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.sh | sh
./scripts/install-skill.sh https://github.com/acme-trading/wasde-analyzer-skill.git
./scripts/install-skill.sh https://github.com/acme-trading/crop-weather-weekly-skill.git
./scripts/install-skill.sh https://github.com/acme-trading/basis-export-tracker-skill.git
./scripts/install-skill.sh https://github.com/acme-trading/coffee-fundamental-skill.git
./scripts/install-skill.sh https://github.com/acme-trading/seasonal-spread-skill.git
./scripts/install-skill.sh https://github.com/acme-trading/client-briefing-skill.git
7 commands. 5 minutes. The new hire has the entire team's research
infrastructure on their machine, across every AI tool they use.
=============================================================
EXPANDED: PSD DATABASE + GLOBAL TRADE TRACKER (GTT) SKILLS
=============================================================
The team has API credentials for two critical data platforms:
PSD_API_KEY — USDA Foreign Agricultural Service Production,
Supply and Distribution database. Global supply/demand
balances for every commodity by country and marketing year.
Endpoint: apps.fas.usda.gov/opendatawebv2/
GTT_USER_ID — Global Trade Tracker login. 133 countries, HS 8-digit
GTT_PASSWORD trade flow data, monthly updates. REST API at
globaltradetracker.com/api/rest/
These credentials are set as environment variables. The skills never
hardcode them — they read from env at runtime.
=============================================================
SKILL 5: Global S&D Balance Sheet Builder (PSD)
=============================================================
The senior analyst who covers global grains:
User: /agent-skill-creator I use the USDA PSD database to build global supply and demand balance sheets for soybeans, corn, and wheat. For each commodity I pull production, beginning stocks, imports, domestic consumption, exports, and ending stocks — broken down by the top 10 producing and consuming countries plus a "rest of world" aggregate. I compare the current marketing year estimates to the previous 5 years to identify trends. I also calculate stocks-to-use ratios and flag any country where ending stocks changed more than 10% month-over-month — that usually signals a USDA revision worth investigating. The PSD API key is in my env as PSD_API_KEY. Here's my current Python notebook that does this manually: notebooks/psd-balance-sheets.ipynb
Copilot (loading agent-skill-creator skill):
Reading notebooks/psd-balance-sheets.ipynb...
I see your workflow: you call the PSD API for each commodity/country
combination, pivot the data into balance sheet format, compute derived
metrics, and render tables in a Jupyter notebook. Let me formalize this.
Implicit requirements I've identified:
- PSD API authentication: API key passed as header (X-Api-Key) to
apps.fas.usda.gov/opendatawebv2/ endpoints
- Commodity codes: 0440000 (soybeans), 0440000 (soybean meal/oil are
separate), 0410000 (corn), 0410000 (wheat has multiple codes by class)
- Marketing years differ by commodity and country: US corn is Sep-Aug,
Brazil soy is Feb-Jan, Argentina wheat is Dec-Nov
- "Top 10" countries shift over time — should be dynamic based on latest
production rankings, not hardcoded
- PSD data updates monthly (around the WASDE release) — need to track
the revision date to know if data is current
- Some PSD attributes are in 1000 MT, others in MT — unit normalization
- World totals in PSD double-count intra-EU trade — need EU-27 aggregate
handling
- The 10% month-over-month change alert needs to compare the same
attribute for the same country between the current and previous PSD
update, not between marketing years
Building...
psd-balance-sheet-skill/
├── SKILL.md
├── scripts/
│ ├── psd_client.py # PSD API wrapper (auth, pagination, rate limits)
│ ├── balance_sheet.py # S&D balance sheet builder (country × commodity)
│ ├── country_rankings.py # Dynamic top-N producer/consumer rankings
│ ├── stocks_to_use.py # Stocks-to-use ratio calculator + historical
│ ├── revision_detector.py # Month-over-month revision alerts (>10% change)
│ ├── marketing_years.py # Country-specific marketing year calendar
│ └── report_builder.py # PDF/HTML balance sheet report
├── references/
│ ├── psd-commodity-codes.md # USDA commodity code mappings
│ ├── psd-attribute-codes.md # Production, consumption, trade attribute IDs
│ ├── marketing-year-cal.md # By country and commodity
│ ├── eu-aggregation.md # EU-27 handling rules
│ └── methodology.md # S&D balance sheet conventions
├── assets/
│ └── country_mappings.json # PSD country codes → ISO 3166 + display names
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (PSD_API_KEY read from env, not hardcoded)
Installed at: ~/.agents/skills/psd-balance-sheet-skill
--- Monthly use right after WASDE release ---
Analyst: /psd-balance-sheet-skill USDA just updated PSD. Pull the full global soybean balance sheet for 2025/26 and compare to last month. Flag any revisions.
Copilot (loading psd-balance-sheet-skill):
Authenticating with PSD API... (using PSD_API_KEY from env)
Pulling soybean data for marketing year 2025/26...
Pulling previous month snapshot for revision comparison...
Building balance sheet...
GLOBAL SOYBEAN BALANCE SHEET — 2025/26 (March 2026 USDA update)
Units: Million Metric Tons
PRODUCTION
| Country | Mar Est | Feb Est | Revision | 5yr Avg | vs Avg |
|---------------|---------|---------|----------|---------|---------|
| Brazil | 169.0 | 169.0 | — | 148.2 | +14.0% |
| United States | 118.8 | 118.8 | — | 116.4 | +2.1% |
| Argentina | 50.0 | 52.0 | -2.0 * | 46.8 | +6.8% |
| China | 20.7 | 20.7 | — | 19.1 | +8.4% |
| India | 13.2 | 12.4 | +0.8 * | 11.8 | +11.9% |
| Paraguay | 10.8 | 10.8 | — | 9.9 | +9.1% |
| Canada | 7.1 | 7.1 | — | 6.6 | +7.6% |
| Russia | 6.8 | 6.8 | — | 5.9 | +15.3% |
| Ukraine | 5.4 | 5.4 | — | 4.2 | +28.6% |
| Bolivia | 3.3 | 3.4 | -0.1 | 3.1 | +6.5% |
| Rest of World | 22.4 | 22.5 | -0.1 | 21.0 | +6.7% |
| WORLD TOTAL | 427.5 | 428.9 | -1.4 | 393.0 | +8.8% |
REVISION ALERTS:
* Argentina production: -2.0 MMT (-3.8%). Drought in Cordoba and
Santa Fe provinces during January pod-fill stage. This is the first
cut — market expected -1.0 MMT. Further downside risk if February
rains don't materialize in southern Buenos Aires province.
* India production: +0.8 MMT (+6.5%). Late monsoon rains benefited
kharif soybean crop in Madhya Pradesh. This is unusual — USDA rarely
revises India this late in the season.
ENDING STOCKS
| Country | Mar Est | Feb Est | Stocks/Use | 5yr Avg S/U |
|---------------|---------|---------|------------|-------------|
| United States | 10.1 | 10.3 | 8.4% | 7.2% |
| Brazil | 37.2 | 37.5 | 23.1% | 21.8% |
| Argentina | 24.8 | 26.2 | 42.3% | 38.1% |
| China | 33.4 | 33.4 | 29.5% | 28.0% |
| WORLD TOTAL | 124.3 | 126.5 | 31.2% | 29.6% |
WORLD STOCKS/USE at 31.2% is slightly above the 5-year average but
tightening on the Argentina cut. Another 2 MMT cut to Argentina in April
would bring world S/U to 30.7%, which would be the tightest since 2023/24.
KEY NARRATIVE: World soy balance is comfortable but deteriorating at the
margin. The Argentina story is the swing variable. Brazil's record crop
is the cushion. Watch the April WASDE for a potential follow-through
Argentina cut if March rains disappoint.
PDF report: reports/psd-soybeans-global-2025-26-march.pdf
--- Deeper drill-down ---
Analyst: /psd-balance-sheet-skill Show me China's soybean import history from PSD — last 10 marketing years. I want to see the trajectory.
Copilot:
Pulling PSD data for China soybean imports, MY 2016/17 through 2025/26...
CHINA SOYBEAN IMPORTS — 10-Year Trajectory (Million MT)
| Marketing Year | Imports | YoY Change | Share of World Trade |
|----------------|---------|------------|----------------------|
| 2016/17 | 93.5 | | 62.1% |
| 2017/18 | 94.1 | +0.6% | 60.8% |
| 2018/19 | 82.5 | -12.3% | 55.2% ← trade war |
| 2019/20 | 98.5 | +19.4% | 60.1% |
| 2020/21 | 99.8 | +1.3% | 59.6% |
| 2021/22 | 91.6 | -8.2% | 57.4% ← hog herd |
| 2022/23 | 100.3 | +9.5% | 60.2% |
| 2023/24 | 105.5 | +5.2% | 61.0% |
| 2024/25 | 109.0 | +3.3% | 61.5% |
| 2025/26 (est) | 106.0 | -2.8% | 59.8% |
OBSERVATIONS:
- The 2018/19 dip was the US-China trade war. China diverted to Brazil.
- 2021/22 dip was the Chinese hog herd contraction (ASF recovery stall).
- The current 2025/26 estimate of 106 MMT is a -2.8% decline — first cut
in two years. USDA attributes this to slowing crush margins in China
and elevated domestic soybean stocks from the prior year's over-buying.
- China's share of world trade peaked at 62% and has been gradually
declining as SE Asian crushers (Vietnam, Bangladesh) grow.
Want me to overlay this against Brazil vs US origin splits from GATS?
=============================================================
SKILL 6: Trade Flow Intelligence (GTT)
=============================================================
The trade flow analyst creates a skill using Global Trade Tracker:
User: /agent-skill-creator I use Global Trade Tracker to monitor real-time commodity trade flows. My main workflow: I pull monthly import/export data by HS code for soybeans (1201), soybean meal (2304), corn (1005), and wheat (1001) — tracking who's buying from whom, how volumes compare to the same month last year, and whether trade is shifting between origins. For example, if China starts buying more Brazilian soybeans and fewer US soybeans, I need to catch that shift early. I also track minor but growing trade corridors (like Russian wheat to Africa, or Ukrainian corn to Southeast Asia) that could signal structural market changes. GTT credentials are in my env as GTT_USER_ID and GTT_PASSWORD. The GTT REST API is at globaltradetracker.com/api/rest/ — you get a token from /gettoken then use /getreport and /tradedetails. Here's my methodology: references/trade-flow-methodology.pdf
Copilot (loading agent-skill-creator skill):
Reading references/trade-flow-methodology.pdf...
Your methodology: origin-destination matrices by commodity, year-over-year
volume changes, market share shifts by origin country, and an "emerging
corridor" detector that flags any bilateral trade route where volume
doubled or tripled in 12 months. Let me build this.
Implicit requirements:
- GTT auth: POST to /api/rest/gettoken with GTT_USER_ID + GTT_PASSWORD,
token valid 14 days, cache and refresh as needed
- /api/rest/getreport requires: reporter, hscode, impexp, and a time
parameter (from/to in YYYY-MM or latestavailablemonths)
- HS codes at 4-digit level: 1201 (soybeans), 2304 (soybean meal),
1005 (corn), 1001 (wheat). Can drill to 6-digit for specifics
- GTT data arrives with ~2-3 month lag for some countries — need to
handle uneven reporting periods across reporters
- "Mirror data" fallback: when a country hasn't reported yet, use the
partner country's mirror data (GTT supports fallbacktomirrordata=true)
- Currency: all volumes in MT (not value) for commodity flow analysis
- Need to distinguish re-exports from domestic exports (impexp parameter)
- EU-27 can be treated as a single entity or individual members — the
skill should support both views
- The "emerging corridor" detector needs a minimum volume threshold to
avoid flagging noise (e.g., 10,000 MT/month minimum)
Building...
trade-flow-intel-skill/
├── SKILL.md
├── scripts/
│ ├── gtt_client.py # GTT REST API wrapper (auth, token caching,
│ │ # getreport, tradedetails, error handling)
│ ├── origin_dest_matrix.py # Origin × destination trade matrices
│ ├── market_share.py # Origin market share by importer
│ ├── yoy_comparison.py # Year-over-year volume changes
│ ├── corridor_detector.py # Emerging trade corridor alerts
│ ├── mirror_data.py # Mirror data fallback handler
│ ├── seasonal_pattern.py # Monthly trade seasonality by route
│ └── report_builder.py # Trade flow report (PDF + charts)
├── references/
│ ├── hs-codes.md # 1201, 2304, 1005, 1001 + sub-codes
│ ├── gtt-api-reference.md # Endpoint docs, params, response format
│ ├── country-codes.md # GTT country codes + ISO mappings
│ ├── data-lag-calendar.md # Expected reporting lag by country
│ └── methodology.md # Market share, corridor detection logic
├── assets/
│ ├── top_importers.json # Key importing countries by commodity
│ └── top_exporters.json # Key exporting countries by commodity
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (GTT_USER_ID and GTT_PASSWORD read from env, not hardcoded)
Installed at: ~/.agents/skills/trade-flow-intel-skill
Shared to: github.com/acme-trading/trade-flow-intel-skill
--- China's soybean sourcing shift ---
Analyst: /trade-flow-intel-skill Pull the latest soybean (1201) import data for China. Show me the origin breakdown — US vs Brazil vs Argentina vs others — monthly for the last 12 months. I want to see if the sourcing pattern is shifting.
Copilot (loading trade-flow-intel-skill):
Authenticating with GTT... (using GTT_USER_ID, GTT_PASSWORD from env)
Token obtained (valid 14 days, cached).
Pulling HS 1201 imports, reporter: China, last 12 available months...
Note: China's latest available data is January 2026 (2-month lag).
CHINA SOYBEAN IMPORTS BY ORIGIN — Feb 2025 to Jan 2026
Units: Thousand Metric Tons
| Month | Brazil | USA | Argentina | Uruguay | Canada | Other | TOTAL |
|----------|---------|---------|-----------|---------|--------|-------|---------|
| Feb 2025 | 4,120 | 3,890 | 210 | 85 | 120 | 195 | 8,620 |
| Mar 2025 | 5,680 | 2,410 | 340 | 140 | 80 | 210 | 8,860 |
| Apr 2025 | 7,230 | 980 | 520 | 190 | 45 | 175 | 9,140 |
| May 2025 | 8,410 | 420 | 680 | 210 | 30 | 160 | 9,910 |
| Jun 2025 | 9,100 | 310 | 750 | 180 | 25 | 190 | 10,555 |
| Jul 2025 | 8,870 | 280 | 610 | 150 | 20 | 170 | 10,100 |
| Aug 2025 | 7,640 | 350 | 480 | 120 | 15 | 155 | 8,760 |
| Sep 2025 | 5,210 | 1,870 | 320 | 80 | 45 | 140 | 7,665 |
| Oct 2025 | 3,180 | 4,560 | 180 | 50 | 190 | 160 | 8,320 |
| Nov 2025 | 2,440 | 5,890 | 120 | 40 | 280 | 175 | 8,945 |
| Dec 2025 | 2,890 | 5,420 | 150 | 55 | 250 | 190 | 8,955 |
| Jan 2026 | 3,540 | 4,680 | 200 | 70 | 210 | 180 | 8,880 |
|----------|---------|---------|-----------|---------|--------|-------|---------|
| 12M TOTAL| 68,310 | 31,060 | 4,560 | 1,370 | 1,310 | 2,100 | 108,710 |
| Share | 62.8% | 28.6% | 4.2% | 1.3% | 1.2% | 1.9% | 100% |
MARKET SHARE vs SAME 12-MONTH PERIOD LAST YEAR:
| Origin | This Year | Last Year | Shift |
|-----------|-----------|-----------|-----------|
| Brazil | 62.8% | 60.1% | +2.7 pp |
| USA | 28.6% | 31.4% | -2.8 pp |
| Argentina | 4.2% | 4.8% | -0.6 pp |
| Canada | 1.2% | 0.8% | +0.4 pp |
ANALYSIS:
Brazil gained 2.7 percentage points of China's soybean import market at
the expense of the US (-2.8 pp). This is the second consecutive year of
share shift toward Brazil.
Key drivers:
1. Brazil's record 169 MMT crop created export price competitiveness —
CFR China spread was $8-12/MT cheaper than US Gulf for most of Q2 2025
2. US Oct-Jan shipping season saw logistical delays on the Mississippi
(low water Sep-Oct) that pushed buyers to book Brazil forward
3. Canada is quietly growing — from 0.8% to 1.2% share. Canadian
soybeans move through Pacific ports (Vancouver) which is a shorter
transit to northern China
The seasonal pattern is intact (Brazil dominates Apr-Aug, US dominates
Oct-Jan) but the crossover points are shifting earlier — Brazil's share
started growing in March this year vs April last year, suggesting China
is booking Brazilian soybeans further forward.
RISK FOR US EXPORTERS: If Brazil's 2026/27 crop (planting starts Sep 2026)
achieves even 5% growth, the US share of Chinese soybean imports could
drop below 27% for the first time since the trade war year.
Want me to drill into the monthly FOB/CFR price differentials to quantify
the price competitiveness driver?
--- Emerging corridor detection ---
Analyst: /trade-flow-intel-skill Run the emerging corridor scan for wheat (1001) — which bilateral trade routes have grown the fastest in the last 12 months vs prior year?
Copilot:
Pulling HS 1001 global trade flows, latest 12 months vs prior 12...
Filtering: minimum 10,000 MT/month, growth > 100%...
EMERGING WHEAT TRADE CORRIDORS — Fastest Growing Routes
| Exporter | Importer | This 12M (KMT) | Prior 12M (KMT) | Growth |
|--------------|----------------|-----------------|-----------------|---------|
| Russia | Algeria | 4,820 | 2,140 | +125% |
| Russia | Bangladesh | 1,560 | 620 | +152% |
| Russia | Nigeria | 890 | 280 | +218% |
| Ukraine | Indonesia | 2,340 | 1,080 | +117% |
| Ukraine | Philippines | 780 | 340 | +129% |
| Australia | Vietnam | 1,120 | 480 | +133% |
| Argentina | Brazil | 5,410 | 2,890 | +87% |
| Kazakhstan | Uzbekistan | 1,890 | 780 | +142% |
TOP STRUCTURAL SHIFTS:
1. RUSSIA → AFRICA (Algeria, Nigeria): Russian wheat is aggressively
displacing French wheat in North and West Africa. Algeria historically
bought French milling wheat but Russia now offers 12-15% protein hard
wheat at $30-40/MT discount. Nigeria's growth is from near zero — this
is a new corridor. Russia now supplies 68% of Algeria's wheat imports,
up from 41% two years ago.
2. RUSSIA → BANGLADESH: Bangladesh was a traditional Australian wheat
buyer. Russian wheat is now competitive into Chittagong port at $15/MT
below Australian APW. This corridor barely existed 3 years ago.
3. UKRAINE → SOUTHEAST ASIA (Indonesia, Philippines): Ukraine rebuilt
Black Sea export logistics post-corridor agreement. Indonesian flour
mills are diversifying away from 100% Australian dependence. Ukrainian
wheat offers good protein at lower cost via Odessa-Singapore-Jakarta
route.
4. ARGENTINA → BRAZIL: Brazil's wheat self-sufficiency is only ~55%.
Argentine wheat fills the gap. The +87% growth is driven by the weak
Argentine peso making exports competitive and a below-average Brazilian
wheat crop in Rio Grande do Sul.
LOSERS (corridors that shrank):
| Exporter | Importer | This 12M (KMT) | Prior 12M (KMT) | Change |
|--------------|----------------|-----------------|-----------------|---------|
| France | Algeria | 1,240 | 3,100 | -60% |
| Australia | Bangladesh | 420 | 890 | -53% |
| USA | Nigeria | 310 | 680 | -54% |
TAKEAWAY: Russian wheat is structurally reshaping global trade flows.
The Black Sea export machine (deep water ports, low production costs,
weak ruble) is pushing traditional exporters (France, US, Australia) out
of price-sensitive emerging markets. This isn't temporary — it's
infrastructure-driven and accelerating.
=============================================================
SKILL 7: PSD + GTT Combined — Supply Chain Risk Monitor
=============================================================
The research director combines both data sources into a single skill:
User: /agent-skill-creator I need a skill that combines PSD balance sheet data with GTT trade flow data to monitor supply chain risk for our four commodities. The idea: PSD tells us the global supply picture (who's producing, who's short). GTT tells us the trade reality (who's actually shipping to whom). When those two diverge — like when a country's PSD ending stocks are falling but GTT shows they're still exporting at last year's pace — that's an early warning of a future export restriction or price spike. I also want to cross-reference GTT flows against USDA Export Sales (from the FAS Open Data API, same PSD_API_KEY) to see if announced sales are actually being shipped. API credentials: PSD_API_KEY and GTT_USER_ID/GTT_PASSWORD are in my env. See my framework doc: references/supply-chain-risk-framework.pdf
Copilot (loading agent-skill-creator skill):
Reading references/supply-chain-risk-framework.pdf...
This is a sophisticated early-warning system. Your framework defines three
risk signals: (1) stock depletion + continued exports, (2) export sale
commitments that aren't converting to shipments, (3) sudden origin
diversification by major importers. Let me build this.
Implicit requirements:
- Must call both PSD API and GTT API, correlate by commodity and country
- PSD data is marketing-year based, GTT is calendar-month — need alignment
- USDA Export Sales (FAS API, same key) provides weekly US commitments vs
shipments — the "commitment-to-shipment" conversion rate is a key metric
- Export restriction history: need a reference table of past export bans
(Russia 2010, Argentina 2022, India rice 2023) to calibrate risk levels
- The divergence detector compares: PSD ending stocks trajectory (shrinking?)
vs GTT export volumes (still high?) — when stocks fall below 15% S/U
while exports maintain pace, flag as "restriction risk"
- Alert hierarchy: GREEN (normal), YELLOW (watch), ORANGE (elevated),
RED (imminent restriction risk)
- Country-specific export policy knowledge: Russia uses floating export
tax, Argentina uses DEX + ROE system, India uses ad-hoc bans
Building...
supply-chain-risk-skill/
├── SKILL.md
├── scripts/
│ ├── psd_client.py # PSD API wrapper
│ ├── gtt_client.py # GTT API wrapper
│ ├── fas_export_sales.py # USDA FAS Export Sales API
│ ├── stock_export_divergence.py # PSD stocks vs GTT flows comparison
│ ├── commitment_tracker.py # Export sales vs actual shipments
│ ├── origin_shift_detector.py # Sudden sourcing changes by importers
│ ├── restriction_risk.py # Export ban/tax probability model
│ ├── risk_dashboard.py # Alert dashboard builder (HTML)
│ └── weekly_report.py # Supply chain risk weekly PDF
├── references/
│ ├── restriction-history.md # Past export bans with triggers/duration
│ ├── policy-mechanisms.md # How each country restricts exports
│ ├── risk-thresholds.md # S/U ratios that historically trigger bans
│ ├── psd-gtt-alignment.md # Marketing year to calendar month mapping
│ └── methodology.md # Full risk framework
├── assets/
│ └── restriction_database.json # Historical export restrictions
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (all 3 credentials read from env)
Installed at: ~/.agents/skills/supply-chain-risk-skill
Shared to: github.com/acme-trading/supply-chain-risk-skill
--- Weekly risk scan ---
Research Director: /supply-chain-risk-skill Run the weekly supply chain risk scan across all four commodities. Flag anything orange or red.
Copilot (loading supply-chain-risk-skill):
Authenticating with PSD API... OK
Authenticating with GTT... token cached, valid 12 more days
Pulling FAS Export Sales... OK
Scanning: soybeans, corn, wheat, coffee across 40+ countries...
SUPPLY CHAIN RISK DASHBOARD — Week of March 2, 2026
=============================================
RED ALERTS (0)
=============================================
None.
=============================================
ORANGE ALERTS (2)
=============================================
1. ARGENTINA — SOYBEAN MEAL EXPORTS
Risk level: ORANGE (elevated)
PSD signal: Argentina 2025/26 soybean production just cut 2 MMT to
50 MMT. Soybean crush projected at 37 MMT. Domestic soybean stocks
falling — ending stocks/use at 15.2%, approaching the 14% threshold
that historically triggers DEX tax increases.
GTT signal: Argentine soybean meal exports (HS 2304) in Nov-Jan
averaged 2.1 MMT/month — ABOVE last year's pace of 1.9 MMT/month.
Exporters appear to be front-running a potential tax hike.
DIVERGENCE: Stocks tightening + exports accelerating = classic
pre-restriction pattern. Argentina raised the soybean export tax
(DEX) from 31% to 33% in 2022 under similar conditions.
Watch for: Argentine government budget statements, central bank
reserve levels (low reserves = higher probability of tax increase
to generate USD revenue).
2. INDIA — WHEAT
Risk level: ORANGE (elevated)
PSD signal: India 2025/26 wheat ending stocks estimated at 7.8 MMT,
the lowest since 2017/18. Government procurement was below target
for the second consecutive year. S/U ratio at 7.1%.
GTT signal: India wheat exports (HS 1001) have been near zero since
the May 2022 ban, which remains in place. However, GTT shows India
IMPORTED 1.2 MMT of wheat in the last 6 months (from Russia and
Australia) — unusual for a country that is typically self-sufficient.
DIVERGENCE: India is quietly switching from net exporter to net
importer. The import volumes suggest domestic availability is tighter
than official PSD estimates reflect. If procurement fails again in
the April-May 2026 rabi harvest, India could become a structural
wheat importer for the first time in a decade.
Implication: Bullish for global wheat if India enters the import
market at scale (1.4 billion people, even small per-capita import
= large absolute volume).
=============================================
YELLOW ALERTS (3)
=============================================
3. RUSSIA — WHEAT EXPORT TAX
Status: YELLOW (watch)
The floating export tax mechanism automatically adjusts. Current tax
is $22/MT on wheat. If FOB Black Sea prices rise above $280/MT (now
at $265), tax increases to $28/MT. Not a ban risk, but a margin
squeeze for importers locked into forward purchases at current prices.
4. BRAZIL — CORN EXPORTS
Status: YELLOW (watch)
Safrinha corn (second crop) planting is 2 weeks behind average due
to late soybean harvest. If safrinha yields disappoint, Brazil's
corn S&D tightens and Jul-Oct corn exports could fall below GTT's
current pace projection. Not urgent yet — safrinha crop doesn't
ship until July.
5. US — SOYBEAN EXPORT SALES CONVERSION
Status: YELLOW (watch)
FAS Export Sales show 4.2 MMT of outstanding (unshipped) soybean
commitments to China. GTT actual shipments in Jan were 4.68 MMT.
The commitment-to-shipment conversion rate is 78%, below the 5-year
average of 85% for this point in the marketing year. Could indicate
some Chinese cancellations incoming, or just logistical delays.
Monitor next 2-3 weeks of inspection data.
=============================================
GREEN (all clear)
=============================================
Soybeans (Brazil, US, Paraguay): normal flows
Corn (US, Ukraine): normal flows
Wheat (Russia export volumes, Canada, Australia, EU): normal flows
Coffee (Brazil, Vietnam, Colombia): normal flows
PDF dashboard: reports/supply-chain-risk-2026-03-02.pdf
HTML interactive: reports/supply-chain-risk-2026-03-02.html
Next scan: March 9, 2026 (auto-scheduled).
=============================================================
COMPLETE TEAM SKILL LIBRARY — WITH PSD & GTT
=============================================================
Updated skill library after adding the data-platform skills:
SKILL CREATED BY DATA SOURCES
─────────────────────────────────────────────────────────────────
wasde-analyzer-skill Senior grain analyst USDA WASDE PDF, Bloomberg
crop-weather-weekly-skill Weather/crop analyst USDA NASS, NOAA, Drought Monitor
basis-export-tracker-skill Logistics analyst DTN bids, USDA FAS, barge freight
coffee-fundamental-skill Softs analyst CEPEA, ICE, CFTC COT, ECMWF
psd-balance-sheet-skill Senior grain analyst USDA PSD API (PSD_API_KEY)
trade-flow-intel-skill Trade flow analyst GTT REST API (GTT_USER_ID/PASSWORD)
supply-chain-risk-skill Research director PSD + GTT + FAS combined
seasonal-spread-skill Quant analyst CBOT historical, seasonal models
client-briefing-skill Research director Calls other skills internally
Environment variables required for new team members:
export PSD_API_KEY="your-usda-fas-api-key"
export GTT_USER_ID="your-gtt-username"
export GTT_PASSWORD="your-gtt-password"
export STRIPE_API_KEY="..." # only for non-ag skills
export MIXPANEL_TOKEN="..." # only for non-ag skills
The team lead adds these to the onboarding doc. Credentials are never
stored in skill code — they're always read from environment variables
at runtime. The security scanner catches any accidental hardcoding
before the skill is published.
New hire onboarding is now:
1. Get API credentials from team lead (PSD_API_KEY, GTT creds)
2. Add to ~/.zshrc or ~/.bashrc
3. Run the 7 install commands
4. Start using skills immediately
Total setup time: 15 minutes. Knowledge transfer time: zero.
Everything the team knows is in the skills.
=============================================================
EXPANDED: OPEN-METEO PROFESSIONAL API SKILLS
=============================================================
The team also has an Open-Meteo professional plan:
OPEN_METEO_API_KEY — Open-Meteo professional subscription. Unlocked:
commercial use, higher rate limits, 80+ years of
historical data, ensemble models (ECMWF 51-member,
GFS 31-member), climate projections to 2050, soil
moisture at 5 depths, soil temperature at 4 depths,
ET0 evapotranspiration, GDD, and leaf wetness.
Endpoints: api.open-meteo.com/v1/forecast,
archive.open-meteo.com/v1/archive,
ensemble-api.open-meteo.com/v1/ensemble,
climate-api.open-meteo.com/v1/climate
Open-Meteo is the weather backbone. It replaces the patchwork of NOAA,
ECMWF direct, and national weather services the team was stitching
together manually. One API, every variable, 80 years of history.
=============================================================
SKILL 8: Yield Predictor — Weather-Based Crop Yield Model
=============================================================
The quant analyst builds a yield regression model powered by weather:
User: /agent-skill-creator I want to build a crop yield prediction model that uses weather data to estimate corn and soybean yields in the US Corn Belt BEFORE the USDA publishes their official estimate. The idea: USDA doesn't release their first survey-based yield estimate until August. But weather during the growing season is the #1 driver of yield — if I can quantify the weather impact, I can have a yield estimate weeks before USDA. My approach: pull 40 years of historical daily weather from Open-Meteo (temperature, precipitation, soil moisture, evapotranspiration) for the top 8 corn-producing states, calculate growing-season metrics (cumulative GDD, total precipitation, drought stress days, excess heat days above 95F during pollination), and run a regression against USDA's final yield for each year. Then apply the model to the current season's weather to get a real-time yield estimate that updates daily. Open-Meteo API key is in my env as OPEN_METEO_API_KEY. Here's my research paper on weather-yield relationships: references/weather-yield-regression.pdf
Copilot (loading agent-skill-creator skill):
Reading references/weather-yield-regression.pdf...
Your paper identifies six weather variables that explain 78% of US corn
yield variance: (1) cumulative GDD May-Sep, (2) July precipitation, (3)
July max temp during pollination, (4) August soil moisture 0-10cm, (5)
VPD during silking, and (6) June precipitation for root establishment.
Soybeans have a similar but shifted model — critical period is Aug-Sep
instead of Jul-Aug. Let me build this.
Implicit requirements:
- Open-Meteo Historical API (archive.open-meteo.com/v1/archive):
daily data from 1984-present, variables: temperature_2m_max,
temperature_2m_min, precipitation_sum, et0_fao_evapotranspiration,
soil_moisture_0_to_1cm through 9_to_27cm, vapour_pressure_deficit
- Open-Meteo Forecast API (api.open-meteo.com/v1/forecast): same
variables, 16-day forecast, for projecting the current season forward
- API key passed as &apikey= parameter (professional plan)
- Need lat/long centroids for each state's ag district — not state
capitals, but production-weighted centroids (e.g., central Iowa
cropland at ~42.0°N, 93.5°W, not Des Moines)
- GDD calculation: base 50°F (10°C), cap at 86°F (30°C) — the standard
corn GDD formula, not simple average
- "Drought stress days": soil_moisture_0_to_1cm < 0.15 m³/m³ during
Jun-Aug. Consecutive drought days matter more than scattered ones
- "Excess heat days": temperature_2m_max > 35°C during Jul 5-25
(pollination window for corn). Each excess heat day costs ~1-2 bu/ac
- USDA final yield data (NASS QuickStats) for training the regression
- Yield trend detrending: raw yields increase ~2 bu/ac/year due to
technology. Must detrend before regression to isolate weather effect
- The model should output: point estimate, confidence interval, and
comparison to USDA's latest estimate (when available)
Building...
yield-predictor-skill/
├── SKILL.md
├── scripts/
│ ├── openmeteo_client.py # Open-Meteo API wrapper (auth, batch queries,
│ │ # historical + forecast + archive endpoints)
│ ├── weather_metrics.py # GDD, precip, drought days, excess heat, VPD,
│ │ # soil moisture — all derived metrics
│ ├── yield_regression.py # Multi-variate regression (40yr training set)
│ ├── trend_detrend.py # Technology trend removal + re-trending
│ ├── state_centroids.py # Production-weighted lat/long by state
│ ├── realtime_estimator.py # Current season: actuals + 16-day forecast
│ │ # extension + climatology for remainder
│ ├── confidence_interval.py # Bootstrap CI from regression residuals
│ ├── usda_comparison.py # Compare model vs USDA when available
│ └── report_builder.py # Yield estimate report (PDF + charts)
├── references/
│ ├── gdd-formula.md # Corn/soy GDD calculation (base/cap)
│ ├── critical-periods.md # Pollination, pod-fill, grain-fill windows
│ ├── yield-weather-lit.md # Academic literature on weather-yield models
│ ├── state-centroids.md # 8 states, ag district centroids
│ └── methodology.md # Full regression methodology
├── assets/
│ ├── centroids.json # {state: {lat, lon, weight}}
│ ├── usda_historical_yields.csv # 1984-2025 state yields from NASS
│ └── trained_model.json # Serialized regression coefficients
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (OPEN_METEO_API_KEY read from env)
Installed at: ~/.agents/skills/yield-predictor-skill
Shared to: github.com/acme-trading/yield-predictor-skill
--- Mid-July, the model starts getting interesting ---
Quant Analyst: /yield-predictor-skill Run the yield model for US corn. Where are we at for 2026?
Copilot (loading yield-predictor-skill):
Pulling Open-Meteo historical data for 2026 growing season (Apr 1 - today)...
Pulling 16-day forecast (Jul 15 - Jul 31)...
Filling Aug-Sep with 30-year climatology (weighted by current soil state)...
Running regression...
US CORN YIELD MODEL — July 15, 2026
WEATHER METRICS TO DATE (weighted across 8 states):
| Metric | 2026 Actual | 30yr Avg | Deviation |
|-------------------------------|-------------|----------|---------------|
| Cumulative GDD (Apr 15-Jul 14)| 1,580 | 1,490 | +6.0% (warm) |
| June precipitation (inches) | 4.8 | 4.3 | +11.6% (wet) |
| July precip to date (inches) | 1.1 | 2.2 | -50.0% (dry!) |
| Drought stress days (Jun-Jul) | 8 | 4 | +4 days |
| Excess heat days >95F | 3 | 1.5 | +1.5 days |
| Soil moisture 0-10cm (m³/m³) | 0.18 | 0.24 | -25.0% (low) |
| VPD avg Jul 1-14 (kPa) | 1.82 | 1.35 | +34.8% (high) |
STATE-BY-STATE BREAKDOWN:
| State | Model Yield | USDA Trend | Deviation | Key Driver |
|-----------|-------------|------------|-----------|----------------------|
| Iowa | 178 bu/ac | 198 bu/ac | -10.1% | Jul drought + heat |
| Illinois | 196 bu/ac | 202 bu/ac | -3.0% | Adequate Jun rain |
| Indiana | 189 bu/ac | 194 bu/ac | -2.6% | Moderate stress |
| Minnesota | 184 bu/ac | 192 bu/ac | -4.2% | VPD stress, ok rain |
| Nebraska | 172 bu/ac | 196 bu/ac | -12.2% | Severe Jul drought |
| Ohio | 192 bu/ac | 190 bu/ac | +1.1% | Good conditions |
| S. Dakota | 152 bu/ac | 168 bu/ac | -9.5% | Drought + thin soils |
| Wisconsin | 176 bu/ac | 182 bu/ac | -3.3% | Moderate |
NATIONAL WEIGHTED ESTIMATE:
Model yield: 181.4 bu/ac
USDA trend yield: 194.0 bu/ac (technology trend)
Model vs trend: -12.6 bu/ac (-6.5%)
90% confidence interval: 175 — 188 bu/ac
SCENARIO ANALYSIS (remainder of season):
| Scenario | Yield Est | Probability |
|----------------------------------|------------|-------------|
| Drought breaks by Jul 25 (rain) | 188 bu/ac | 35% |
| Current pattern continues | 181 bu/ac | 45% |
| Drought intensifies through Aug | 172 bu/ac | 20% |
The 16-day forecast shows ECMWF bringing a cold front through the
western Corn Belt around Jul 24-26 with 0.5-1.0 inches. If verified,
the "drought breaks" scenario becomes more likely, but the damage
during pollination week (Jul 10-20) in Iowa and Nebraska is already
locked in. Those bushels aren't coming back.
CONTEXT: USDA's July WASDE used a trend yield of 181 bu/ac (their first
estimate). Our model agrees with USDA's number this month, but for
different reasons — USDA hasn't incorporated the July heat/drought yet
(their July report uses trend, not weather). When USDA releases their
August survey-based estimate, expect them to cut to 177-183 range.
MARKET IMPLICATION: If our model is right at 181 and USDA's August
estimate comes in at 179 (a 2 bu/ac cut from trend), that removes
~280 million bushels from US production. At current demand, that would
cut ending stocks from 2.1 billion to 1.82 billion bushels and push
the stocks/use ratio from 14.5% to 12.5%. Dec corn futures should
reprice $0.25-$0.40 higher.
PDF report: reports/yield-model-corn-2026-07-15.pdf
Want me to run soybeans too? Soybean critical period (pod fill) hasn't
started yet — the model has less signal this early.
=============================================================
SKILL 9: Parana River Drought & Logistics Risk
=============================================================
The logistics analyst builds something no one else on the street has:
User: /agent-skill-creator Here's a unique edge I want to build: the Parana River system in Argentina/Brazil handles 80% of Argentine grain exports from the Rosario-Santa Fe port complex. When the Parana runs low, draft restrictions limit barge loading, which increases freight costs and delays shipments. The river level at Rosario is the single most important logistics variable for Argentine soy/corn exports. I want to track this using weather. My idea: pull historical and forecast precipitation for the Parana River watershed — the Upper Parana in Brazil (Minas Gerais, Sao Paulo, Parana, Mato Grosso do Sul) feeds the river. If rainfall in the watershed is below normal for 60+ days, river levels at Rosario drop 2-3 months later (the lag from upstream rain to downstream flow). I can use Open-Meteo's 80 years of precipitation history to build a rainfall-to-river-level lag model, then use the 16-day forecast plus seasonal climate projections to predict river levels 1-3 months ahead. Nobody on Wall Street models this — they react to draft restrictions AFTER they're announced. We'd see them coming weeks ahead. Open-Meteo key in env as OPEN_METEO_API_KEY. Also I have a spreadsheet with historical Rosario river gauge readings from Argentina's naval hydrography service: data/rosario-river-levels-1990-2026.xlsx
Copilot (loading agent-skill-creator skill):
Reading data/rosario-river-levels-1990-2026.xlsx...
35 years of daily river gauge readings at Rosario (km 416 of the Parana).
I can see the 2021-2022 historic drought clearly — river dropped to 0.08m
(normal is ~3.5m), which caused $2.4 billion in extra freight costs for
Argentine exporters. Let me build this.
Implicit requirements:
- Open-Meteo Historical API: daily precipitation_sum for 12 sub-basins
across the Upper Parana watershed in Brazil (lat/long grid covering
~800,000 km² of catchment area)
- Open-Meteo Forecast API: 16-day precipitation forecast for same grid
- Open-Meteo Climate API: seasonal precipitation projections (CMIP6
models) for 1-3 month outlook
- Ensemble API (ensemble-api.open-meteo.com): ECMWF 51-member and GFS
31-member ensembles for probabilistic rainfall forecasts — critical
for the "will it rain enough?" question
- The rainfall-to-river-level lag varies by sub-basin: Upper Parana
(Mato Grosso do Sul) has a 30-45 day lag to Rosario, Tietê tributary
(São Paulo) has 45-60 day lag, Paranaíba (Minas Gerais/Goiás) has
60-90 day lag
- Itaipu Dam releases affect downstream flow — need to account for
regulated vs natural flow
- Draft restriction thresholds: below 2.0m at Rosario = Panamax vessels
can't fully load. Below 1.0m = barges limited to 60% capacity.
Below 0.5m = effective port shutdown for ocean vessels
- Export calendar: Argentine soy harvest is Mar-May, corn harvest is
Mar-Jun. Peak export season is Apr-Aug. River problems during this
window are catastrophic for basis and FOB premiums
- The skill should output: current river level, 30/60/90-day predicted
level, probability of draft restrictions, and estimated freight cost
impact
Building...
parana-river-risk-skill/
├── SKILL.md
├── scripts/
│ ├── openmeteo_client.py # Open-Meteo API wrapper (all 4 endpoints)
│ ├── watershed_rainfall.py # 12 sub-basin precipitation aggregation
│ ├── lag_model.py # Rainfall-to-river-level lag regression
│ │ # (30/45/60/90 day lags by sub-basin)
│ ├── river_level_predictor.py # Combines: actuals + forecast + climate +
│ │ # ensemble probabilities → predicted level
│ ├── ensemble_probabilities.py # ECMWF 51-member rainfall probability
│ │ # distribution for watershed
│ ├── draft_restriction.py # Threshold model: level → loading capacity
│ ├── freight_impact.py # Estimated $/MT cost increase by level
│ ├── export_window_risk.py # Overlay predictions on export calendar
│ └── report_builder.py # Parana River Risk Report (PDF + charts)
├── references/
│ ├── parana-watershed.md # 12 sub-basins, areas, lag times
│ ├── rosario-gauge.md # Gauge location, datum, thresholds
│ ├── draft-restrictions.md # Historical restrictions + impacts
│ ├── itaipu-releases.md # Dam regulation effects
│ └── methodology.md # Lag model, ensemble approach
├── assets/
│ ├── sub_basins.geojson # 12 watershed polygons with centroids
│ ├── rosario_historical.csv # River gauge 1990-2026
│ └── trained_lag_model.json # Serialized lag coefficients
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (OPEN_METEO_API_KEY read from env)
Installed at: ~/.agents/skills/parana-river-risk-skill
Shared to: github.com/acme-trading/parana-river-risk-skill
--- February, heading into Argentine export season ---
Logistics Analyst: /parana-river-risk-skill What's the river outlook for the April-August export window? I need to know if we should be hedging freight.
Copilot (loading parana-river-risk-skill):
Pulling Open-Meteo historical precip for Parana watershed (last 180 days)...
Pulling 16-day forecast (ECMWF + GFS)...
Pulling ECMWF 51-member ensemble for next 15 days...
Pulling Climate API seasonal projection (Mar-Aug 2026)...
Running lag model...
PARANA RIVER RISK REPORT — February 28, 2026
CURRENT STATUS:
River level at Rosario: 2.85m (normal for late Feb: 3.8m)
Status: BELOW NORMAL but above restriction threshold (2.0m)
WATERSHED RAINFALL — LAST 90 DAYS (Nov-Feb):
| Sub-basin | Actual (mm) | Normal (mm) | Deficit |
|---------------------|-------------|-------------|----------|
| Upper Parana (MS) | 680 | 820 | -17.1% |
| Tietê (SP) | 590 | 780 | -24.4% |
| Paranaíba (MG/GO) | 710 | 850 | -16.5% |
| Iguaçu (PR) | 820 | 790 | +3.8% |
| Paraguay River | 440 | 620 | -29.0% |
| TOTAL WATERSHED | 3,240 | 3,860 | -16.1% |
The Tietê (São Paulo) and Paraguay River sub-basins are significantly
below normal. The Iguaçu (Paraná state) is the only sub-basin at or
above normal.
16-DAY FORECAST:
| Period | Forecast Precip | Normal | Outlook |
|-----------------|-----------------|---------|-------------|
| Mar 1-7 | 35mm | 45mm | Below normal|
| Mar 8-15 | 50mm | 42mm | Above normal|
A frontal system around Mar 10-12 brings the best rain chance in weeks,
but it's concentrated over the Iguaçu sub-basin (southern watershed),
which has the shortest lag to Rosario. Upper Parana stays drier.
ENSEMBLE PROBABILITY (ECMWF 51-member, next 15 days):
- Probability of total watershed rainfall > normal: 22%
- Probability of total watershed rainfall < 75% of normal: 41%
- Probability of total watershed rainfall < 50% of normal: 12%
PREDICTED RIVER LEVELS AT ROSARIO:
| Period | Predicted Level | Normal | Restriction Risk |
|-------------|-----------------|---------|------------------|
| March | 2.6m ± 0.4m | 3.5m | LOW (>2.0m) |
| April | 2.1m ± 0.5m | 3.0m | MODERATE (near threshold) |
| May | 1.6m ± 0.6m | 2.5m | HIGH (<2.0m likely) |
| June | 1.3m ± 0.7m | 2.2m | HIGH |
| July | 1.5m ± 0.8m | 2.0m | MODERATE-HIGH |
| August | 1.8m ± 0.7m | 2.1m | MODERATE |
PROBABILITY OF DRAFT RESTRICTIONS (level < 2.0m) BY MONTH:
| April | May | June | July | August |
|-------|------|------|------|--------|
| 38% | 72% | 81% | 65% | 52% |
FREIGHT IMPACT ESTIMATE:
Current Up-River freight (Rosario-to-vessel): $18/MT
If level drops to 1.5m (May estimate): $28-32/MT (+$10-14/MT)
If level drops to 1.0m (worst case): $38-45/MT (+$20-27/MT)
For context: Argentine FOB soybean premium is currently +$8/MT over
CBOT. A $14/MT freight increase would push FOB premiums to +$22/MT,
which is close to the $25/MT peak during the 2021-22 Parana drought.
CLIMATE MODEL SEASONAL OUTLOOK (Mar-Aug 2026):
5 of 7 CMIP6 models show below-normal precipitation for the Upper
Parana watershed through May, with a return to normal by July. This
is consistent with the current weak La Niña signal, which historically
reduces rainfall in southern Brazil and the Parana basin.
RECOMMENDATION:
High probability (72%) of draft restrictions in May, coinciding with
peak Argentine soybean export shipments. This is a tradeable event:
- Argentine FOB soy basis will widen
- Brazilian soy basis (Paranaguá, Santos) will strengthen as buyers
divert from Rosario
- Barge freight futures (if available) should be bought
- CBOT May-July soybean spread could steepen on logistics premium
If you want to hedge, do it now — by the time restrictions are
announced (typically 2-3 weeks before they bite), the freight market
will have already moved.
PDF: reports/parana-river-risk-2026-02-28.pdf
=============================================================
SKILL 10: Global Crop Calendar & Anomaly Scanner
=============================================================
The weather analyst builds a skill that scans every major growing region
on Earth simultaneously — the "Bloomberg terminal for crop weather":
User: /agent-skill-creator I want a skill that monitors weather anomalies across every major crop-producing region globally — all at once. The commodity markets move when weather deviates from normal in a key region at a critical growth stage. The problem: there are 30+ regions that matter and each has a different crop calendar. I can't manually check weather for Brazil, Argentina, US, EU, Black Sea, India, China, SE Asia, and Australia every day. I want the skill to: (1) know the crop calendar for each commodity in each region (planting, vegetative, reproductive, harvest), (2) pull the current weather from Open-Meteo for each region daily, (3) compare against the 30-year climatology, (4) flag any region where a critical weather metric (precip, temp, soil moisture) deviates beyond 1.5 standard deviations from normal during a critical growth phase, and (5) rank the anomalies by market impact (a drought during US corn pollination matters more than excess rain during Ukrainian wheat dormancy). Use Open-Meteo's historical archive for the 30-year baselines and the forecast API for the forward-looking 16-day window. OPEN_METEO_API_KEY is in my env. Here's my spreadsheet with all the regions and crop calendars: data/global-crop-calendar.xlsx
Copilot (loading agent-skill-creator skill):
Reading data/global-crop-calendar.xlsx...
32 region-commodity combinations across 14 countries. Each with planting,
vegetative, reproductive, and harvest date ranges. This is a proper global
surveillance system. Let me build this.
Implicit requirements:
- Open-Meteo Historical API: 30-year daily climatology (1994-2023)
for 32 regions. Variables: temperature_2m_max, temperature_2m_min,
precipitation_sum, soil_moisture_0_to_7cm, et0_fao_evapotranspiration,
vapour_pressure_deficit
- Open-Meteo Forecast API: current + 16-day for all 32 regions
- Each region needs multiple grid points (not just one centroid) to
capture spatial variability — a 3x3 grid (~100km spacing) per region
- The 30-year climatology must be pre-computed and cached (not pulled
daily — 32 regions × 30 years = too many API calls in real-time)
- Standard deviation calculation: for each variable, each day-of-year,
each region → mean and stddev from 30-year history
- "Market impact weight": reproductive stage anomalies weighted 3x,
vegetative 2x, planting/harvest 1x. Production volume of the region
also weights the score (Iowa corn matters more than Ohio corn)
- Output: a ranked "heat map" — red/orange/yellow/green for each
region-commodity pair, sorted by composite impact score
- The scanner should run in < 30 seconds despite querying 32 regions
(batch and parallelize Open-Meteo calls, 3x3 grid = 288 locations)
- Ensemble API for the 16-day window adds probabilistic dimension —
"65% chance this anomaly persists through next week"
Building...
crop-anomaly-scanner-skill/
├── SKILL.md
├── scripts/
│ ├── openmeteo_client.py # Open-Meteo API wrapper (batch, parallel)
│ ├── climatology_builder.py # Pre-compute 30yr normals + stddev
│ │ # (run once, cache to assets/)
│ ├── anomaly_detector.py # Current weather vs climatology,
│ │ # z-score by variable by region
│ ├── growth_stage_tracker.py # What stage is each crop in today?
│ ├── impact_scorer.py # Anomaly × growth stage × production
│ │ # volume = composite impact score
│ ├── ensemble_persistence.py # Will the anomaly continue? (ECMWF ensemble)
│ ├── region_grid.py # 3x3 grid generator per region
│ ├── dashboard_builder.py # Global heat map (HTML interactive)
│ └── daily_briefing.py # "Top 5 anomalies today" PDF
├── references/
│ ├── crop-calendar.md # 32 region-commodity growth phases
│ ├── region-definitions.md # Lat/long bounds, production weights
│ ├── anomaly-thresholds.md # z-score levels, impact weighting
│ ├── historical-analogues.md # Past anomaly events + market outcomes
│ └── methodology.md # Full scoring methodology
├── assets/
│ ├── regions.json # 32 regions with grids + weights
│ ├── crop_calendar.json # Growth phase dates by region-commodity
│ ├── climatology_cache/ # Pre-computed 30yr normals (per region)
│ │ ├── us-corn-belt.json
│ │ ├── brazil-center-west.json
│ │ ├── argentina-pampas.json
│ │ └── ... (29 more)
│ └── production_weights.json # Regional share of global production
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (OPEN_METEO_API_KEY read from env)
Installed at: ~/.agents/skills/crop-anomaly-scanner-skill
Shared to: github.com/acme-trading/crop-anomaly-scanner-skill
--- Daily morning scan ---
Research Director: /crop-anomaly-scanner-skill Morning scan. What's flashing?
Copilot (loading crop-anomaly-scanner-skill):
Pulling current weather for 32 regions (288 grid points)...
Comparing against 30-year climatology...
Scoring by growth stage and production weight...
GLOBAL CROP ANOMALY SCANNER — March 4, 2026, 07:15 ET
TOP 5 ANOMALIES BY MARKET IMPACT:
#1 ARGENTINA PAMPAS — Soybeans (pod fill) SCORE: 9.2
┌──────────────────────────────────────────────────────────────────┐
│ Precipitation last 30 days: 42mm (normal: 98mm) z = -2.31 │
│ Soil moisture 0-7cm: 0.12 m³/m³ (normal: 0.22) z = -2.05 │
│ Max temperature avg: 34.2°C (normal: 30.8°C) z = +1.72 │
│ VPD avg: 2.14 kPa (normal: 1.48 kPa) z = +1.89 │
│ Growth stage: REPRODUCTIVE (R5 pod fill) — CRITICAL │
│ Ensemble: 78% chance below-normal precip continues 15 days │
│ │
│ ANALOGUE: Feb 2018 (similar z-scores) → Argentina lost 20 MMT │
│ of soybeans, CBOT rallied $2.50/bu over 6 weeks. │
│ Current deviation isn't as severe yet but accelerating. │
└──────────────────────────────────────────────────────────────────┘
#2 US SOUTHERN PLAINS — Winter wheat (jointing) SCORE: 6.8
┌──────────────────────────────────────────────────────────────────┐
│ Precipitation last 60 days: 28mm (normal: 72mm) z = -2.08 │
│ Soil moisture 0-7cm: 0.14 m³/m³ (normal: 0.21) z = -1.78 │
│ Growth stage: VEGETATIVE (jointing, approaching boot) │
│ Region: Kansas, Oklahoma, Texas panhandle │
│ Ensemble: 55% below-normal precip continues, 30% near-normal │
│ │
│ HRW wheat entering its most water-sensitive phase. If drought │
│ persists through March, expect USDA to lower winter wheat │
│ condition ratings and KC wheat to firm. │
└──────────────────────────────────────────────────────────────────┘
#3 VIETNAM CENTRAL HIGHLANDS — Robusta coffee (cherry dev) SCORE: 5.4
┌──────────────────────────────────────────────────────────────────┐
│ Precipitation last 30 days: 8mm (normal: 22mm) z = -1.62 │
│ Temperature avg: 26.8°C (normal: 24.1°C) z = +1.87 │
│ Growth stage: REPRODUCTIVE (cherry development) │
│ Region: Dak Lak, Lam Dong, Gia Lai provinces │
│ Ensemble: 60% chance dry pattern continues through mid-March │
│ │
│ Vietnam = 40% of global robusta. Dry + warm during cherry dev │
│ reduces bean size and weight. Could shave 1-2 MMT off the │
│ 2026/27 harvest estimate. RC robusta may firm on this. │
└──────────────────────────────────────────────────────────────────┘
#4 INDIA — Rabi wheat (grain fill) SCORE: 4.9
┌──────────────────────────────────────────────────────────────────┐
│ Max temperature: 33.5°C (normal: 28.9°C) z = +2.12 │
│ Growth stage: REPRODUCTIVE (grain fill, 3-4 weeks to harvest) │
│ Region: Punjab, Haryana, Uttar Pradesh, Madhya Pradesh │
│ │
│ Terminal heat stress. March heat during grain fill is the #1 │
│ yield risk for Indian wheat. The 2022 heatwave cost India 5 MMT │
│ and triggered the export ban. Current temps not yet at 2022 │
│ levels but approaching. Watch closely this week. │
└──────────────────────────────────────────────────────────────────┘
#5 BRAZIL CENTER-WEST — Safrinha corn (vegetative) SCORE: 4.1
┌──────────────────────────────────────────────────────────────────┐
│ Precipitation last 14 days: 18mm (normal: 55mm) z = -1.68 │
│ Growth stage: VEGETATIVE (V6-V8, recently planted) │
│ Region: Mato Grosso, Goiás, Mato Grosso do Sul │
│ │
│ Safrinha corn was planted late (soy harvest delay) and now │
│ hitting a dry spell during early vegetative growth. Not critical │
│ yet — safrinha corn is drought-tolerant in early stages. But if │
│ dryness persists into April (tasseling), this moves to #1. │
└──────────────────────────────────────────────────────────────────┘
REGIONS ALL CLEAR (no anomalies >1.5 stddev in critical phases):
EU (France wheat, Germany rapeseed), Black Sea (Ukraine corn/wheat,
Russia wheat), Australia (canola, wheat — dormant/off-season), China
(winter wheat — adequate snow cover), US Corn Belt (pre-planting,
soil moisture recharging), Brazil South (soybean harvest on pace),
SE Asia (palm oil — normal monsoon), Canada (off-season).
Full dashboard: reports/anomaly-dashboard-2026-03-04.html
PDF briefing: reports/crop-anomalies-2026-03-04.pdf
Want me to drill deeper into any of these, or pull up the historical
analogue analysis for the Argentina situation?
--- Drilling into a specific alert ---
Analyst: /crop-anomaly-scanner-skill Pull up the full historical analogue for Argentina #1. How bad could this get?
Copilot:
Searching 30 years for matching patterns: Pampas soybeans, February
precip z < -2.0, soil moisture z < -1.5, during reproductive phase...
ARGENTINA SOYBEAN DROUGHT — HISTORICAL ANALOGUES
5 matching events found:
| Year | Feb Precip z | Soil z | Outcome | CBOT Impact |
|---------|--------------|--------|---------------------|----------------|
| 2017/18 | -2.45 | -2.20 | 20 MMT production loss | +$2.50/bu (6wk) |
| 2008/09 | -2.62 | -2.41 | 16 MMT production loss | +$1.80/bu (4wk) |
| 2011/12 | -1.95 | -1.70 | 12 MMT production loss | +$3.20/bu (8wk) |
| 2003/04 | -1.88 | -1.55 | 7 MMT production loss | +$0.90/bu (3wk) |
| 2022/23 | -3.10 | -2.80 | 25 MMT production loss | +$1.40/bu (4wk) |
CURRENT 2025/26 vs ANALOGUES:
Feb precip z: -2.31 (between 2017/18 and 2008/09 severity)
Soil moisture z: -2.05
PRODUCTION IMPACT ESTIMATE:
Based on analogues, the current deviation pattern suggests a production
loss of 8-18 MMT from USDA's current 50 MMT estimate.
| Scenario | Production | Loss from USDA | Probability |
|------------------|------------|----------------|-------------|
| Rain arrives Mar 10-15 | 45 MMT | -5 MMT | 22% |
| Continued dry Mar | 40 MMT | -10 MMT | 48% |
| Drought deepens | 35 MMT | -15 MMT | 30% |
Note: USDA already cut 2 MMT in March (to 50 from 52). The market has
priced in ~3-4 MMT of further downside. If the "continued dry" scenario
plays out (10 MMT total cut), there's 6-7 MMT of production loss NOT
yet in the price.
SOYBEAN MEAL IMPACT: Argentina = 45% of global soybean meal exports.
A 10 MMT soy production loss = ~7.5 MMT less crush = ~5.5 MMT less
meal exports. Meal importers (EU, SE Asia) would need to source from
US or Brazil. CBOT soybean meal could rally $30-50/short ton.
16-DAY ENSEMBLE OUTLOOK (ECMWF 51-member):
Probability of meaningful rain (>25mm) in Pampas next 15 days: 28%
Probability of continued dry (<10mm) next 15 days: 52%
Probability of drought-breaking event (>50mm): 8%
RECOMMENDATION: The analogues and ensemble data both point toward the
"continued dry" scenario as most likely. USDA will likely cut another
3-5 MMT in the April WASDE. The market is under-pricing this risk.
=============================================================
SKILL 11: Planting Window Advisor
=============================================================
A completely different use case — this one faces the production side,
not the trading desk. An analyst who also advises farmer clients:
User: /agent-skill-creator Our brokerage has farmer clients across the Midwest who ask us every spring: "When should I plant?" I want a skill that answers this using weather data. The decision depends on: (1) soil temperature at 2-inch depth — corn needs >50F sustained for 3 days, soybeans need >55F, (2) soil moisture — too wet and you get compaction, too dry and you need irrigation, the sweet spot is 0.20-0.30 m³/m³, (3) the 7-day forecast — no point planting if a freeze or heavy rain is coming, (4) accumulated GDD so the crop reaches maturity before the first fall frost. Open-Meteo has soil temperature at 0cm and 6cm depth, soil moisture at multiple levels, and the 16-day forecast. For any lat/long a farmer gives me, I want the skill to say "GO — plant corn now" or "WAIT — soil temp at 48F, need 2 more warm days" or "RISK — planting window closing, frost date approaching". OPEN_METEO_API_KEY is in my env.
Copilot (loading agent-skill-creator skill):
This is a decision-support tool for planting timing. Let me formalize
the agronomic rules and build it.
Implicit requirements:
- Open-Meteo Forecast API: soil_temperature_6cm (closest to 2-inch
depth), soil_moisture_0_to_1cm, temperature_2m_min (freeze risk),
precipitation_sum, for any user-provided lat/long
- Open-Meteo Historical API: need average first fall frost date
(temperature_2m_min < 0°C) from 30-year history at the location
to calculate "days to maturity available"
- Corn maturity: needs 2,500-2,800 GDD (base 50F) depending on
hybrid maturity class. Soybean: 2,200-2,600 GDD
- The skill must accept a location (lat/long, county, zip code, or
city name) and hybrid maturity (short/medium/full season)
- "GO/WAIT/RISK" traffic light must consider ALL factors simultaneously
— soil temp alone isn't enough if rain is forecast
- Workability factor: if precipitation > 15mm in last 48 hours, soil
is too wet for heavy equipment regardless of other factors
- Farmers want a 5-day window recommendation, not just "today" —
"Best planting day this week: Thursday"
Building...
planting-window-skill/
├── SKILL.md
├── scripts/
│ ├── openmeteo_client.py # Open-Meteo API wrapper
│ ├── soil_readiness.py # Soil temp + moisture check
│ ├── freeze_risk.py # 16-day freeze probability
│ ├── workability.py # Field trafficability from recent precip
│ ├── gdd_projection.py # GDD remaining vs maturity requirement
│ │ # vs average first frost date
│ ├── window_optimizer.py # Score each day in the next 14 days,
│ │ # recommend best planting window
│ ├── frost_date_calculator.py # 30-year avg first fall frost by location
│ └── advisor_output.py # GO/WAIT/RISK with plain-English reasoning
├── references/
│ ├── planting-rules.md # Agronomic decision rules
│ ├── gdd-maturity-table.md # GDD requirements by hybrid class
│ ├── soil-thresholds.md # Temperature and moisture thresholds
│ └── methodology.md
├── assets/
│ └── maturity_zones.json # Hybrid maturity GDD by latitude band
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED
Installed at: ~/.agents/skills/planting-window-skill
Shared to: github.com/acme-trading/planting-window-skill
--- A farmer client calls in April ---
Broker: /planting-window-skill One of my clients near Ames, Iowa (42.03°N, 93.47°W) wants to plant corn this week. Full-season hybrid (2,700 GDD). Is he good to go?
Copilot (loading planting-window-skill):
Pulling Open-Meteo data for 42.03°N, 93.47°W...
Forecast: 16 days | Soil data: current + forecast
Historical: calculating average first fall frost date...
PLANTING WINDOW ADVISOR — Ames, Iowa (42.03°N, 93.47°W)
Crop: Corn | Hybrid: Full season (2,700 GDD required)
Date: April 14, 2026
CURRENT CONDITIONS:
┌────────────────────────────────────────────────────────────────┐
│ Soil temp (6cm depth): 52.1°F (need: >50°F for 3 days) │
│ Consecutive days >50°F: 4 days ✓ PASS │
│ Soil moisture (0-7cm): 0.27 m³/m³ (ideal: 0.20-0.30) ✓ │
│ Last significant rain: 3 days ago (12mm) ✓ WORKABLE │
│ Avg first fall frost: October 12 (30yr avg) │
│ Days from today to frost: 181 days │
│ GDD available (Apr14-Oct12): ~2,850 (based on 30yr avg) │
│ GDD required (full season): 2,700 │
│ GDD margin: 150 GDD (5.6% buffer) ✓ OK │
└────────────────────────────────────────────────────────────────┘
7-DAY FORECAST:
| Day | High | Low | Precip | Soil Temp | Verdict |
|-----------|-------|-------|--------|-----------|--------------|
| Mon 4/14 | 68°F | 45°F | 0mm | 52°F | PLANTABLE |
| Tue 4/15 | 72°F | 48°F | 0mm | 53°F | PLANTABLE * |
| Wed 4/16 | 70°F | 50°F | 0mm | 54°F | PLANTABLE * |
| Thu 4/17 | 64°F | 46°F | 8mm | 53°F | MARGINAL |
| Fri 4/18 | 58°F | 40°F | 22mm | 50°F | TOO WET |
| Sat 4/19 | 55°F | 38°F | 5mm | 48°F | TOO COOL/WET |
| Sun 4/20 | 62°F | 42°F | 0mm | 49°F | RECOVERING |
════════════════════════════════════════════════════════════════
RECOMMENDATION: GO — PLANT TUESDAY OR WEDNESDAY
════════════════════════════════════════════════════════════════
Best window: Tuesday April 15 and Wednesday April 16. Soil is warm,
moisture is ideal, and 48 hours of dry weather ahead gives excellent
field conditions. Thursday is marginal (light rain incoming). Friday
onward is too wet — a 22mm rain event will make fields unworkable
for 2-3 days.
If your client misses the Tue-Wed window, next opportunity is likely
Monday April 21 after the weekend system clears and fields dry out
(soil needs ~48hr of dry weather after 22mm of rain to be trafficable).
GDD margin is tight at 5.6% for a full-season hybrid. If planting
slips past April 25, I'd recommend switching to a medium-season hybrid
(2,500 GDD) to guarantee maturity before frost. Every day of planting
delay after April 20 costs roughly 1-1.5 bu/ac in yield potential.
=============================================================
COMPLETE TEAM SKILL LIBRARY — WITH OPEN-METEO
=============================================================
Updated library with the weather-powered skills:
SKILL DATA SOURCES USE CASE
──────────────────────────────────────────────────────────────────────────────
wasde-analyzer-skill USDA WASDE, Bloomberg Monthly S&D analysis
crop-weather-weekly-skill USDA NASS, NOAA, Drought Mon. Weekly crop report
basis-export-tracker-skill DTN, USDA FAS, barge freight Daily basis + exports
coffee-fundamental-skill CEPEA, ICE, CFTC, ECMWF Coffee market monitor
psd-balance-sheet-skill USDA PSD API Global balance sheets
trade-flow-intel-skill GTT REST API Trade flow shifts
supply-chain-risk-skill PSD + GTT + FAS Export restriction risk
yield-predictor-skill Open-Meteo + NASS historical Pre-USDA yield estimates
parana-river-risk-skill Open-Meteo (4 endpoints) River logistics risk
crop-anomaly-scanner-skill Open-Meteo (all 32 regions) Global weather alerts
planting-window-skill Open-Meteo forecast + archive Farmer planting advice
seasonal-spread-skill CBOT historical Seasonal spread models
client-briefing-skill Calls other skills internally Weekly flagship report
Environment variables required:
export OPEN_METEO_API_KEY="your-professional-api-key"
export PSD_API_KEY="your-usda-fas-api-key"
export GTT_USER_ID="your-gtt-username"
export GTT_PASSWORD="your-gtt-password"
The Open-Meteo skills are the ones that give the team a genuine
informational edge. Every bank and fund has PSD data and GTT access.
But almost nobody is systematically converting granular weather data
into crop yield estimates, river level predictions, and global anomaly
scores in real-time. The data is public (Open-Meteo). The edge isn't
the data — it's the skill that knows what to do with it.
=============================================================
EXPANDED: DATA INGESTION PIPELINE SKILLS
=============================================================
Beyond API wrappers, the team now builds skills that create automated
data ingestion pipelines — pulling, parsing, normalizing, and storing
data from sources that don't have clean APIs. Raw satellite rasters,
government FTP dumps, vessel tracking feeds, and fire detection data.
These are the plumbing skills that feed the analytical skills above.
=============================================================
SKILL 12: NOAA Satellite Crop Monitor (NDVI / VHI Pipeline)
=============================================================
The remote sensing analyst on the team:
User: /agent-skill-creator I need to build a data pipeline that ingests NOAA STAR's weekly Vegetation Health Products — specifically the Smoothed NDVI (SMN), Vegetation Condition Index (VCI), Temperature Condition Index (TCI), and Vegetation Health Index (VHI). These are satellite-derived datasets at 4km resolution covering the entire globe, updated weekly. The data lives at star.nesdis.noaa.gov/data/pub0018/VHPdata4users/data/Blended_VH_4km/ — GeoTIFF files organized by year and week number. There's no API — you have to wget the files, parse the GeoTIFF rasters, and extract values for the regions you care about. I want the skill to: (1) automatically download the latest weekly GeoTIFF files for VHI, VCI, SMN, and TCI, (2) clip the rasters to our 32 crop regions (same regions as the anomaly scanner), (3) compute area-weighted average VHI/VCI/NDVI for each region, (4) compare to the same-week historical average (NOAA has data from 1981), (5) flag any region where VHI drops below 40 (drought stress) or VCI drops below 35 (vegetation deterioration), and (6) produce a weekly "Satellite Crop Monitor" report. This is the same data that USDA FAS uses in their Crop Explorer tool, but we'd have it parsed and actionable in our own pipeline instead of waiting for their interpretation. I have no special credentials — this data is public. Here's the NOAA documentation I saved: references/noaa-vh-products-guide.pdf
Copilot (loading agent-skill-creator skill):
Reading references/noaa-vh-products-guide.pdf...
This is a GeoTIFF raster ingestion problem. NOAA publishes global 4km
vegetation health products weekly as individual .tif files. The skill
needs to handle: file discovery (new files appear weekly by week number),
HTTP download (wget-style, no authentication), raster parsing (GeoTIFF
→ numpy arrays), spatial clipping (global raster → regional means),
and time-series comparison (current week vs 40+ year baseline). Let me
build this.
Implicit requirements:
- Data URL pattern:
https://www.star.nesdis.noaa.gov/data/pub0018/VHPdata4users/
data/Blended_VH_4km/geo_TIFF/VHI/VHI_YYYY_WW.tif
(similarly for VCI, SMN, TCI — separate directories)
- Files are global 4km GeoTIFF rasters: 10000 × 3616 pixels, WGS84
- Week numbering follows NOAA convention (ISO week), published with
~5-7 day lag
- Need rasterio or GDAL to parse GeoTIFF (standard geospatial Python)
- Region clipping: define bounding boxes or polygon masks for each of
the 32 crop regions, extract pixel values within each polygon
- Area weighting: pixels at different latitudes cover different areas
(cos(lat) correction)
- VHI interpretation thresholds from NOAA:
<10 = extreme drought, 10-20 = severe drought, 20-30 = moderate
drought, 30-40 = mild drought, 40-60 = normal, >60 = favorable
- Historical baseline: download archived annual .gz files from 1981-2023
for same-week comparison (one-time setup, then incremental weekly)
- Storage: cache downloaded GeoTIFFs locally in data/noaa-vh/ to avoid
re-downloading. Only fetch the latest week's files each run.
- NDVI (SMN) absolute values matter for crop identification; VHI and
VCI are relative indices that already account for the local baseline
- Dependencies: rasterio, numpy, shapely (for polygon clipping).
These are common geospatial packages — not exotic
Building...
noaa-crop-monitor-skill/
├── SKILL.md
├── scripts/
│ ├── noaa_downloader.py # wget-style fetcher for weekly GeoTIFFs
│ │ # (VHI, VCI, SMN, TCI directories)
│ │ # handles retries, caching, new file detection
│ ├── raster_parser.py # GeoTIFF → numpy array using rasterio
│ │ # handles projection, nodata values, masking
│ ├── region_clipper.py # Clip global raster to 32 crop regions
│ │ # using polygon masks, area-weighted mean
│ ├── baseline_builder.py # One-time: download 1981-2023 archives,
│ │ # compute per-week per-region mean and stddev
│ │ # for VHI, VCI, SMN, TCI (cached to assets/)
│ ├── anomaly_detector.py # Current week vs baseline: z-scores and
│ │ # threshold alerts (VHI<40, VCI<35)
│ ├── trend_tracker.py # Rolling 4-week, 8-week, 12-week VHI trends
│ │ # (is stress building or recovering?)
│ ├── ndvi_crop_stage.py # NDVI curve analysis: is greenup on time?
│ │ # early/late planting detection from SMN
│ └── report_builder.py # Weekly Satellite Crop Monitor (PDF + maps)
├── references/
│ ├── noaa-vh-products.md # Product definitions, thresholds, caveats
│ ├── geotiff-format.md # Raster specs, projection, resolution
│ ├── region-polygons.md # 32 region definitions (bounding boxes)
│ ├── vhi-interpretation.md # What VHI values mean for crop yields
│ └── methodology.md
├── assets/
│ ├── region_polygons.geojson # 32 crop region masks
│ ├── baselines/ # Pre-computed weekly baselines (1981-2023)
│ │ ├── us-corn-belt.json # mean + stddev by week for VHI/VCI/SMN
│ │ ├── brazil-center-west.json
│ │ └── ... (30 more)
│ └── noaa_week_calendar.json # ISO week → date mapping
├── data/ # Local cache for downloaded GeoTIFFs
│ └── noaa-vh/ # (gitignored, created on first run)
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (no credentials needed — public data)
Installed at: ~/.agents/skills/noaa-crop-monitor-skill
Shared to: github.com/acme-trading/noaa-crop-monitor-skill
--- First run: building the historical baseline ---
Analyst: /noaa-crop-monitor-skill Initialize the pipeline. Download the historical baseline and run the first weekly scan.
Copilot (loading noaa-crop-monitor-skill):
STEP 1: Building historical baseline (one-time setup)
Downloading NOAA VH archives for 1981-2023...
This will take 15-20 minutes (downloading 43 annual .gz archives).
Downloading: VHI_1981.gz... done (34 MB)
Downloading: VHI_1982.gz... done (34 MB)
...
Downloading: VHI_2023.gz... done (42 MB)
Extracting and computing per-week per-region baselines...
Processing 2,236 weekly rasters × 32 regions = 71,552 data points...
Baseline computed and cached to assets/baselines/
Each region now has a 42-year mean and standard deviation for every
week of the year, for each of VHI, VCI, SMN, and TCI.
STEP 2: Downloading current week's data
Fetching Week 09 (Feb 24 - Mar 2, 2026):
- VHI_2026_09.tif... done (18 MB)
- VCI_2026_09.tif... done (18 MB)
- SMN_2026_09.tif... done (18 MB)
- TCI_2026_09.tif... done (18 MB)
STEP 3: Clipping to 32 crop regions and computing anomalies...
SATELLITE CROP MONITOR — Week 09 (Feb 24 - Mar 2, 2026)
ALERTS (VHI < 40 or VCI < 35):
| Region | VHI | VCI | TCI | NDVI | Status |
|-----------------------|------|------|------|-------|-----------------|
| Argentina Pampas | 28 | 24 | 32 | 0.41 | SEVERE STRESS |
| Argentina Chaco | 34 | 30 | 38 | 0.38 | MODERATE STRESS |
| US Southern Plains | 36 | 31 | 41 | 0.29 | MODERATE STRESS |
| India Central (MP) | 38 | 36 | 40 | 0.34 | MILD STRESS |
| Vietnam Highlands | 39 | 37 | 42 | 0.52 | MILD STRESS |
CROSS-VALIDATION WITH ANOMALY SCANNER:
All 5 satellite stress regions match the top 5 weather anomalies
from the crop-anomaly-scanner-skill. The satellite data CONFIRMS the
weather-based signals — this isn't a false alarm from one data source.
REGIONAL DETAIL — ARGENTINA PAMPAS:
VHI at 28 is the lowest for Week 9 since 2023 (when VHI hit 18 during
the historic drought) and well below the 42-year average of 55 for this
week. The VHI has been declining for 6 consecutive weeks:
| Week | VHI | Trend |
|------|------|----------|
| W03 | 52 | Normal |
| W04 | 48 | Slipping |
| W05 | 44 | Slipping |
| W06 | 40 | Threshold|
| W07 | 35 | Stress |
| W08 | 31 | Stress |
| W09 | 28 | Severe |
The trajectory is accelerating downward. In the 2018 drought analogue,
VHI bottomed at 22 in Week 11 before rain brought partial recovery.
If the current trajectory holds, we could see VHI in the low 20s by
mid-March — which historically correlates with 15-25% soybean yield
reduction in the affected area.
NDVI CROP STAGE ANALYSIS:
The SMN (smoothed NDVI) at 0.41 for Argentina Pampas is concerning
because soybeans at pod-fill stage should have peak NDVI of 0.65-0.75.
An NDVI of 0.41 during reproductive stage means canopy is already
deteriorating — leaves are senescing prematurely due to drought stress.
This damage is irreversible even if rain arrives now.
REGIONS ALL FAVORABLE (VHI > 55):
| Region | VHI | Status | Notes |
|-----------------------|------|------------|--------------------------|
| Brazil Center-West | 62 | Favorable | Soy harvest underway |
| Brazil South | 58 | Normal | Soy harvest 60% complete |
| US Corn Belt | N/A | Dormant | Pre-season, snow cover |
| EU France | 64 | Favorable | Winter wheat looks good |
| EU Germany | 61 | Favorable | Rapeseed on track |
| Black Sea Ukraine | 56 | Normal | Winter wheat emerging |
| Black Sea Russia | 59 | Normal | Winter wheat dormant |
| Australia East | 68 | Favorable | Canola finished harvest |
| China NE | N/A | Dormant | Winter, snow cover |
PDF report: reports/satellite-crop-monitor-wk09-2026.pdf
Maps: reports/vhi-global-map-wk09-2026.png
Pipeline is now configured. It will check for new NOAA data every
Monday and generate the weekly report automatically.
--- A few weeks later, the analyst cross-references ---
Analyst: /noaa-crop-monitor-skill Overlay the Argentina VHI trend against the 2018 and 2023 drought tracks. How close are we to those events?
Copilot:
Pulling VHI time series for Argentina Pampas: 2018, 2023, and 2026...
ARGENTINA PAMPAS — VHI TRAJECTORY COMPARISON
Week 2018 (severe) 2023 (historic) 2026 (current)
────────────────────────────────────────────────────────────
W01 58 52 60
W02 56 48 58
W03 54 42 52
W04 50 36 48
W05 46 30 44
W06 41 24 40
W07 36 20 35
W08 30 18 31
W09 26 16 28 ← current
W10 23 15 ?
W11 22 (bottom) 14 (bottom) ?
W12 25 15 ?
W13 32 20 ?
W14 40 28 ?
ASSESSMENT:
The 2026 track is running almost exactly on the 2018 path — 1-2 VHI
points higher at each week. The 2023 event was significantly worse
(VHI bottomed at 14 vs 2018's 22).
If 2026 follows the 2018 pattern:
- VHI bottoms around 22-24 in weeks 10-11 (mid-March)
- Recovery begins week 12 if autumn rains arrive
- Total soybean production loss: 15-20 MMT (2018 outcome)
If 2026 follows the 2023 pattern (worse case):
- VHI drops to 14-16, no recovery until week 14
- Total soybean production loss: 22-28 MMT (2023 outcome)
Current trajectory: closer to 2018 than 2023. The 2023 event had
exceptional heat on top of drought (TCI at 12), while 2026's TCI
is at 32 — hot but not extreme.
The satellite data and the weather data are telling the same story:
this is a significant but not historic event. USDA is probably 5-8 MMT
behind reality right now (their March estimate was 50 MMT; satellite
data suggests 42-45 MMT is more likely).
=============================================================
SKILL 13: NASA FIRMS Fire Monitor — Crop Residue & Deforestation
=============================================================
A creative use of fire data for commodity research:
User: /agent-skill-creator NASA FIRMS provides near-real-time satellite fire detection globally — every thermal anomaly picked up by MODIS and VIIRS satellites, available within 3 hours via REST API at firms.modaps.eosdis.nasa.gov. Most people use this for wildfire tracking, but I've realized it has two powerful applications for commodity research: (1) Crop residue burning in Brazil's Cerrado signals land clearing for new soybean planting — if I see a spike in fire detections in Mato Grosso in August-September, it means farmers are clearing more land for the next season, which predicts INCREASED soybean acreage. (2) In India and Southeast Asia, post-harvest rice straw burning (October-November) intensity correlates with the size of the kharif rice harvest — more burning = bigger harvest, which is bearish for rice prices. I want a skill that ingests FIRMS data via their API (free, need a MAP_KEY from earthdata.nasa.gov), clips fire detections to our crop regions, counts fire pixels by week, compares to historical patterns, and generates alerts when fire activity deviates significantly. My MAP_KEY is in env as NASA_FIRMS_KEY. Here's my analysis showing the fire-acreage correlation in Brazil: references/firms-acreage-correlation.pdf
Copilot (loading agent-skill-creator skill):
Reading references/firms-acreage-correlation.pdf...
Fascinating — your analysis shows a 0.82 R² between Aug-Sep FIRMS fire
counts in Mato Grosso and the following season's soybean planted area
(CONAB data). That's a strong signal hidden in plain sight. And the India
rice burning correlation is 0.74 R² — not as clean but still tradeable.
Let me build this.
Implicit requirements:
- NASA FIRMS REST API: https://firms.modaps.eosdis.nasa.gov/api/area/
Parameters: source (VIIRS_SNPP, MODIS_NRT), coordinates (bounding box
or country), day_range (1-10), date, format (json, csv)
- API key: NASA_FIRMS_KEY passed as MAP_KEY parameter
- VIIRS is higher resolution (375m) than MODIS (1km) — prefer VIIRS
for fire pixel counts, use MODIS for longer historical record
- Fire pixels need to be filtered: confidence > 75% to exclude
false positives (gas flares, industrial heat, volcanoes)
- For Brazil land clearing: focus on Cerrado biome (Mato Grosso,
Goiás, Tocantins, Bahia western, Maranhão southern). The Amazon
biome fires are deforestation — politically different but also
signals acreage expansion into new areas
- Seasonal patterns: Brazil burning peaks Aug-Sep (dry season), then
drops sharply when rains arrive in October. Early start to burning
season (July) or late end (October) is itself a signal
- For India/SE Asia: focus on Punjab, Haryana (wheat stubble, Oct-Nov),
and Thailand/Myanmar (rice straw, Feb-Apr)
- Historical fire data: FIRMS has archives back to 2001 (MODIS) and
2012 (VIIRS). Need to build year-by-year fire pixel counts for
each region for the correlation model
- CONAB soybean area data for Brazil, USDA PSD for India rice
production — these are the training targets for the regression
- Output: weekly fire pixel count by region, deviation from
historical, and implied acreage/production signal
Building...
fire-crop-monitor-skill/
├── SKILL.md
├── scripts/
│ ├── firms_client.py # NASA FIRMS REST API wrapper
│ │ # (auth, bounding box queries, pagination)
│ ├── fire_counter.py # Filter by confidence, clip to regions,
│ │ # aggregate fire pixel counts by week
│ ├── brazil_clearing.py # Cerrado + Amazon fire → acreage signal
│ │ # correlation with CONAB planting data
│ ├── asia_burning.py # India/SE Asia post-harvest burn intensity
│ │ # → production signal
│ ├── historical_baselines.py # 2001-2025 fire pixel baselines by region
│ ├── season_detector.py # Burning season start/end date tracking
│ │ # (early start = more clearing than expected)
│ ├── deforestation_tracker.py # Amazon-specific: frontier expansion monitor
│ └── report_builder.py # Fire Monitor report (PDF + heat maps)
├── references/
│ ├── firms-api-reference.md # API endpoints, params, rate limits
│ ├── fire-acreage-model.md # R² coefficients, regression methodology
│ ├── biome-boundaries.md # Cerrado vs Amazon vs Atlantic Forest
│ ├── burning-calendar.md # Expected seasonal patterns by region
│ └── methodology.md
├── assets/
│ ├── region_bboxes.json # Bounding boxes for FIRMS queries
│ ├── biome_masks.geojson # Cerrado/Amazon/Pantanal boundaries
│ ├── fire_baselines.json # 2001-2025 weekly fire counts by region
│ └── conab_soy_area.csv # Brazil soybean planted area 2001-2026
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (NASA_FIRMS_KEY read from env)
Installed at: ~/.agents/skills/fire-crop-monitor-skill
Shared to: github.com/acme-trading/fire-crop-monitor-skill
--- Late August, burning season in Brazil ---
Analyst: /fire-crop-monitor-skill How's the burning season in Mato Grosso tracking? What does it imply for 2026/27 soy acreage?
Copilot (loading fire-crop-monitor-skill):
Pulling FIRMS VIIRS data for Cerrado region, last 90 days...
Comparing against 2001-2025 historical baselines...
BRAZIL CERRADO FIRE MONITOR — August 25, 2026
FIRE PIXEL COUNTS (VIIRS, confidence > 75%)
| Month | 2026 | 2025 | 5yr Avg | vs Avg |
|----------|--------|--------|---------|---------|
| June | 8,420 | 6,890 | 7,100 | +18.6% |
| July | 24,300 | 18,900 | 19,200 | +26.6% |
| Aug 1-25 | 52,800 | 38,400 | 41,500 | +27.2% |
TOTAL JUN-AUG: 85,520 (highest since 2020)
BY SUB-REGION:
| Sub-region | 2026 Fire px | vs 5yr Avg | Signal |
|------------------------|-------------|------------|---------------------|
| Mato Grosso (Cerrado) | 38,200 | +31% | Strong expansion |
| Goiás | 14,800 | +22% | Moderate expansion |
| Tocantins | 9,400 | +18% | Moderate |
| Bahia West (MATOPIBA) | 12,600 | +42% | RAPID expansion |
| Maranhão South | 10,520 | +28% | Strong expansion |
MATOPIBA ALERT: The Bahia West / MATOPIBA frontier shows fire pixel
counts 42% above the 5-year average. This is the most active clearing
frontier in Brazil — new soybean acreage expanding into former
Cerrado grassland. This sub-region has shown the highest fire growth
rate for three consecutive years.
ACREAGE SIGNAL (regression model, R² = 0.82):
Based on the historical fire-to-acreage correlation, current burning
levels project:
| Metric | 2025/26 Actual | 2026/27 Projected |
|----------------------------|----------------|-------------------|
| Brazil soy planted area | 46.2M hectares | 48.1M hectares |
| Year-over-year change | | +1.9M ha (+4.1%) |
| Implied production (trend) | | 175-180 MMT |
This +4.1% acreage expansion, combined with trend yields, suggests
Brazil's 2026/27 soybean crop could reach 175-180 MMT — a new record
and 6-11 MMT above the current 2025/26 crop of 169 MMT.
MARKET IMPLICATION: This is bearish for CBOT soybeans on a 6-12 month
horizon. More Brazilian supply = more competition for US exports in
the 2026/27 marketing year. However, this is already partially
expected — the market consensus is for ~2% acreage growth. The fire
data suggests 4%+ is more likely.
AMAZON BIOME NOTE: Amazon fire detections are also elevated (+35%
vs 5yr avg), but this is a separate dynamic — Amazon deforestation
is a reputational/regulatory risk for Brazilian exports (EU
deforestation regulation), not an acreage expansion signal. Some
European buyers may reduce Brazilian soy purchases if Amazon fires
make headlines again.
BURNING SEASON TIMING: The season started 2 weeks early this year
(first sustained fires in mid-June vs typical early July). Early start
is itself a signal — it indicates farmers had drier conditions and
were more aggressive about clearing. This correlates with the upper
end of the acreage projection.
=============================================================
SKILL 14: Vessel Tracking — Grain Shipment Intelligence
=============================================================
The logistics analyst builds a pipeline from AIS vessel data:
User: /agent-skill-creator I want to track grain vessel movements to verify and predict export shipment volumes in real-time. The traditional data sources (USDA Export Inspections, GTT) have 1-4 week lags. But by tracking bulk carrier vessels via AIS (Automatic Identification System), I can see shipments BEFORE they show up in official data. My idea: use a vessel tracking API to monitor Panamax and Capesize bulk carriers departing key grain export ports (Santos, Paranaguá, and São Francisco do Sul in Brazil; Rosario/San Lorenzo in Argentina; US Gulf ports; Odessa/Mykolaiv in Ukraine; Novorossiysk in Russia). When a bulk carrier departs a grain port with a draft indicating full cargo, I can estimate tonnage from the vessel's DWT and draft. By aggregating departures weekly, I can build a near-real-time export volume tracker that leads official data by 2-3 weeks. I have an AIS data subscription — credentials in my env as AIS_API_KEY. The API gives me vessel positions, port calls, vessel particulars (DWT, draft), and ETA. Here's my methodology: references/vessel-export-methodology.pdf
Copilot (loading agent-skill-creator skill):
Reading references/vessel-export-methodology.pdf...
Your approach: filter vessels by type (bulk carrier), DWT range (Panamax
40-80K DWT, Capesize 80-200K DWT), monitor departures from grain ports,
estimate cargo weight from loaded draft vs ballast draft × DWT ratio,
classify probable commodity based on port (Santos = soy, Rosario = soy
meal, US Gulf = corn/soy), and aggregate into weekly volume estimates.
This is essentially building a private export inspection tracker. Let me
build it.
Implicit requirements:
- AIS API: vessel positions, port call history, vessel particulars
(DWT, current draft, flag, destination). Auth via AIS_API_KEY
- Port definitions: specific berth/terminal polygons, not just city
coordinates. Santos has grain terminals (Cargill, Bunge, Cofco) and
container terminals — need to distinguish
- Draft-to-cargo estimation: a Panamax at 14.5m draft (loaded) vs 7m
(ballast) carrying 65,000 DWT = approximately 58,000 MT of cargo.
The formula: cargo_MT ≈ DWT × (current_draft - ballast_draft) /
(loaded_draft - ballast_draft). Accuracy: ±8%
- Destination inference: when a vessel departs Santos for "Singapore"
or "CNSHA" (Shanghai), the destination tells us the buyer. Vessels
to China = soybean. Vessels to EU = soybean meal. Vessels to
Egypt/Algeria = wheat
- "Line-up" tracking: vessels at anchor or waiting to load = pending
exports. Count of vessels in the line-up × average cargo = pipeline
volume indicator
- Need to separate grain vessels from iron ore, coal, and other bulk
commodities at the same ports. Use vessel history: if a Panamax
was last at a grain terminal, its current cargo is probably grain
- Historical vessel departure data for backtesting: compare estimated
vs actual export inspections to calibrate the model
Building...
vessel-grain-tracker-skill/
├── SKILL.md
├── scripts/
│ ├── ais_client.py # AIS API wrapper (positions, port calls,
│ │ # vessel particulars, rate limiting)
│ ├── port_monitor.py # Define grain ports, terminal polygons,
│ │ # monitor arrivals and departures
│ ├── cargo_estimator.py # Draft-to-cargo tonnage estimation
│ ├── commodity_classifier.py # Port + destination + history → probable
│ │ # commodity (soy, corn, wheat, meal)
│ ├── lineup_counter.py # Vessels at anchor / waiting to load
│ ├── weekly_aggregator.py # Sum departures by port, commodity, dest
│ ├── official_comparison.py # Compare vs USDA Export Inspections when
│ │ # available (calibration + lead time)
│ └── report_builder.py # Vessel Intelligence Weekly (PDF + maps)
├── references/
│ ├── grain-ports.md # Port locations, terminal IDs, berth polygons
│ ├── vessel-types.md # Panamax/Capesize specs, draft ranges
│ ├── cargo-estimation.md # Draft-to-tonnage formula + accuracy
│ ├── destination-mapping.md # Port codes → country → probable commodity
│ └── methodology.md
├── assets/
│ ├── port_polygons.geojson # Grain terminal berth boundaries
│ ├── vessel_type_specs.json # DWT ranges, draft ranges by class
│ └── port_commodity_map.json # Port → most likely commodity
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (AIS_API_KEY read from env)
Installed at: ~/.agents/skills/vessel-grain-tracker-skill
Shared to: github.com/acme-trading/vessel-grain-tracker-skill
--- Real-time export tracking ---
Logistics Analyst: /vessel-grain-tracker-skill What's the Brazilian soybean export pace looking like this week? I want to compare to the GTT data we'll get in 2 months.
Copilot (loading vessel-grain-tracker-skill):
Pulling AIS data for Santos, Paranaguá, São Francisco do Sul...
Identifying grain-loaded departures (Panamax/Capesize, draft > 12m)...
Estimating cargo tonnage...
BRAZIL SOYBEAN VESSEL TRACKER — Week of Mar 2-8, 2026
DEPARTURES FROM GRAIN PORTS (estimated soybean cargo):
| Port | Vessels | Est. Cargo (KMT) | Destinations |
|-----------------------|---------|-------------------|------------------------|
| Santos | 14 | 812 | China 9, EU 3, Egypt 2 |
| Paranaguá | 8 | 456 | China 6, Japan 1, TW 1 |
| São Francisco do Sul | 4 | 228 | China 3, Bangladesh 1 |
| WEEKLY TOTAL | 26 | 1,496 | |
COMPARISON TO PACE:
| Metric | This Week | Same Week 2025 | YoY Change |
|---------------------------|-----------|----------------|------------|
| Vessel departures | 26 | 22 | +18% |
| Estimated tonnage | 1,496 KMT | 1,280 KMT | +16.9% |
| 4-week rolling avg | 1,380 KMT | 1,190 KMT | +16.0% |
DESTINATION BREAKDOWN (all 3 ports combined):
| Destination | Vessels | Tonnage (KMT) | Share |
|----------------|---------|---------------|--------|
| China | 18 | 1,044 | 69.7% |
| EU | 3 | 174 | 11.6% |
| Egypt | 2 | 116 | 7.8% |
| Japan | 1 | 58 | 3.9% |
| Taiwan | 1 | 58 | 3.9% |
| Bangladesh | 1 | 46 | 3.1% |
LINE-UP (vessels waiting to load as of today):
| Port | Vessels Waiting | Est. Days to Clear |
|-----------------------|-----------------|--------------------|
| Santos | 42 | 18 days (normal) |
| Paranaguá | 28 | 14 days (normal) |
| São Francisco do Sul | 11 | 8 days (light) |
| TOTAL | 81 | |
The line-up at 81 vessels is consistent with peak export season. This
time last year it was 74 vessels — the 9.5% increase aligns with the
record 169 MMT crop moving through the pipeline.
LEAD INDICATOR: Our vessel-based estimate of 1,496 KMT this week will
show up in official Brazilian customs (SECEX) data in 3-4 weeks, and
in GTT in 6-8 weeks. We're seeing the exports NOW.
MONTHLY PACE PROJECTION (March 2026):
At current weekly pace, Brazil is on track to export ~6.0 MMT of
soybeans in March. This would be the highest March on record,
surpassing March 2023's 5.5 MMT. The early harvest (90% complete in
Mato Grosso) is pushing shipments forward.
IMPLICATION: When this volume shows up in official SECEX data in late
March and GTT data in May, it will confirm that Brazil is front-loading
exports. China-bound vessel share at 70% is above the 5-year average
of 64%, reinforcing the market share shift we saw in the GTT trade
flow analysis.
=============================================================
SKILL 15: Copernicus Sentinel-2 Field-Level NDVI
=============================================================
For analysts who need to zoom in from country-level to individual
fields — something NOAA's 4km resolution can't do:
User: /agent-skill-creator Our firm is getting into precision agriculture consulting alongside commodity research. I need a skill that pulls Sentinel-2 satellite imagery from the Copernicus Data Space Ecosystem and computes NDVI at 10-meter resolution for specific farm fields. A farmer or agronomist gives us a field boundary (as a GeoJSON polygon or just a lat/long point with radius), and we compute: (1) current NDVI for that field, (2) NDVI time-series for the current growing season (every cloud-free overpass, roughly every 5 days), (3) comparison to the same field's NDVI in previous years, (4) within-field variability (are parts of the field stressed while others are fine?). The Copernicus Data Space has free API access — I registered at dataspace.copernicus.eu and have OAuth2 credentials. COPERNICUS_CLIENT_ID and COPERNICUS_CLIENT_SECRET are in my env. The Sentinel Hub Process API can compute NDVI server-side using evalscripts (no need to download raw bands). Here's the API docs I saved: references/sentinel-hub-process-api.pdf
Copilot (loading agent-skill-creator skill):
Reading references/sentinel-hub-process-api.pdf...
The Sentinel Hub Process API takes a bounding box, an evalscript
(JavaScript that computes NDVI from B04 and B08 bands), and returns
a processed GeoTIFF or JSON. Cloud masking is done via the SCL
(Scene Classification Layer). This means we don't download raw imagery
— the heavy lifting happens server-side. Let me build this.
Implicit requirements:
- Copernicus Data Space OAuth2: POST to identity.dataspace.copernicus.eu
with client_id + client_secret to get bearer token
- Sentinel Hub Process API: POST to sh.dataspace.copernicus.eu/api/v1/process
with evalscript, bounding box, time range, output format
- NDVI evalscript: (B08 - B04) / (B08 + B04) — standard formula
- Cloud masking: use SCL band, exclude pixels classified as cloud,
cloud shadow, snow/ice, or no data
- 10m resolution means a 100-hectare field = 100,000 pixels. That's
enough resolution to see within-field variability (waterlogged low
spots, compacted headlands, variable soil types)
- Time-series: query all available scenes for the field in the current
growing season. Sentinel-2 revisits every 5 days. After cloud
filtering, expect ~3-4 usable scenes per month
- Inter-year comparison: pull the same dates from 2023, 2024, 2025
for the same field polygon. Normalize by day-of-year
- Within-field variability: compute per-pixel NDVI, then generate
a coefficient of variation (CV) map. High CV = stressed patches.
Also compute zonal stats: mean, P10, P25, P50, P75, P90
- Output options: NDVI value (JSON), NDVI map (GeoTIFF colorized),
time-series chart (PNG), variability map (PNG)
- Rate limits: Copernicus free tier allows 300 requests/minute
and 40,000 Processing Units/month. A single field NDVI request
uses ~1 PU. We have headroom
Building...
sentinel-field-ndvi-skill/
├── SKILL.md
├── scripts/
│ ├── copernicus_auth.py # OAuth2 token management (auto-refresh)
│ ├── sentinel_client.py # Sentinel Hub Process API wrapper
│ ├── ndvi_calculator.py # Evalscript builder, NDVI request, cloud mask
│ ├── field_timeseries.py # Growing season NDVI curve for a field
│ ├── interyear_compare.py # Same field, same dates, previous years
│ ├── variability_map.py # Within-field CV map + zonal statistics
│ ├── field_health_report.py # Field Health Report builder (PDF + maps)
│ └── batch_processor.py # Process multiple fields in one run
├── references/
│ ├── sentinel-hub-api.md # Process API endpoints, evalscripts
│ ├── ndvi-interpretation.md # What NDVI values mean by crop and stage
│ ├── cloud-masking.md # SCL classes, filtering strategy
│ ├── sentinel2-bands.md # Band specifications (B04, B08, etc.)
│ └── methodology.md
├── assets/
│ ├── evalscripts/
│ │ ├── ndvi.js # Standard NDVI evalscript
│ │ ├── ndvi_masked.js # NDVI with cloud masking
│ │ └── enhanced_vegetation.js # EVI for dense canopies
│ └── ndvi_colormap.json # Color ramp for NDVI visualization
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (COPERNICUS_CLIENT_ID/SECRET read from env)
Installed at: ~/.agents/skills/sentinel-field-ndvi-skill
Shared to: github.com/acme-trading/sentinel-field-ndvi-skill
--- An agronomist client asks about their field ---
Agronomist: /sentinel-field-ndvi-skill Check the corn field for the Petersen farm. Here's the boundary: data/petersen-north-field.geojson. How does it look compared to last year?
Copilot (loading sentinel-field-ndvi-skill):
Authenticating with Copernicus Data Space... token obtained.
Reading field boundary: 156 hectares, Boone County, Iowa
Querying Sentinel-2 scenes for Jul 1 - Jul 15, 2026...
3 cloud-free scenes found: Jul 2, Jul 7, Jul 12.
Computing NDVI...
FIELD HEALTH REPORT — Petersen Farm, North Field (156 ha)
Boone County, Iowa | Corn | July 15, 2026
CURRENT NDVI (July 12 scene):
| Metric | Value | Interpretation |
|-----------------|-------|-----------------------------------|
| Mean NDVI | 0.72 | Good (expected: 0.75-0.85) |
| P10 (worst 10%) | 0.48 | Stress in parts of the field |
| P25 | 0.64 | Below expected |
| P50 (median) | 0.74 | Normal |
| P90 (best 10%) | 0.84 | Excellent |
| Coef. Variation | 0.16 | Moderate variability (>0.12 = flag)|
WITHIN-FIELD VARIABILITY MAP:
[Generated: reports/petersen-north-variability-2026-07-12.tif]
The northwest corner (approx. 22 hectares) shows NDVI of 0.45-0.55,
significantly below the field average. This area corresponds to the
lower-elevation zone that was waterlogged during the June 18 heavy
rain event (38mm in 2 hours per Open-Meteo data). The saturated
soil likely damaged root development during V4-V6 stage. The rest
of the field looks healthy.
YEAR-OVER-YEAR COMPARISON (same dates ±3 days):
| Year | Mean NDVI (early Jul) | Notes |
|------|-----------------------|---------------------------------|
| 2024 | 0.81 | Excellent year, above-trend yield|
| 2025 | 0.78 | Good, trend yield |
| 2026 | 0.72 | Below recent years |
The field is tracking 8-12% below the previous two years. Most of
the deficit is concentrated in that NW low spot. If we exclude the
damaged 22 hectares, the remaining 134 hectares have a mean NDVI
of 0.77 — close to normal.
GROWING SEASON NDVI CURVE:
[Generated: reports/petersen-north-timeseries-2026.png]
The NDVI curve shows a normal green-up trajectory until late June,
then a plateau at 0.72 instead of the expected peak of 0.82-0.85.
This plateau coincides with the waterlogging event. The NW corner
is pulling the whole-field average down.
RECOMMENDATION FOR THE AGRONOMIST:
- The NW 22 hectares will likely yield 140-150 bu/ac vs the field
average of 185-195 bu/ac. That's a 30-40 bu/ac loss on 14% of
the field = roughly 4-6 bu/ac whole-field yield reduction.
- Consider variable-rate nitrogen application for the stressed zone
if there's still time (doubtful at V12+ stage)
- For next year: tile drainage in the NW low spot would prevent
recurrence. The field's yield history likely shows this same zone
underperforming in every wet year
=============================================================
FINAL TEAM SKILL LIBRARY — FULL DATA PIPELINE STACK
=============================================================
SKILL DATA SOURCES PIPELINE TYPE
────────────────────────────────────────────────────────────────────────────────
ANALYSIS SKILLS (interpret data):
wasde-analyzer-skill USDA WASDE PDF, Bloomberg PDF parsing
crop-weather-weekly-skill USDA NASS, NOAA, Drought Mon. Multi-source aggregation
basis-export-tracker-skill DTN, USDA FAS, barge freight Web scraping + API
coffee-fundamental-skill CEPEA, ICE, CFTC, ECMWF Multi-source aggregation
yield-predictor-skill Open-Meteo + NASS historical Weather → yield regression
crop-anomaly-scanner-skill Open-Meteo (32 regions) Real-time anomaly detection
planting-window-skill Open-Meteo forecast + archive Decision support
DATA PLATFORM SKILLS (query structured APIs):
psd-balance-sheet-skill USDA PSD API REST API → balance sheets
trade-flow-intel-skill GTT REST API REST API → trade matrices
supply-chain-risk-skill PSD + GTT + FAS combined Multi-API correlation
DATA INGESTION SKILLS (raw data → actionable intelligence):
noaa-crop-monitor-skill NOAA STAR GeoTIFF (wget) Raster ingestion pipeline
fire-crop-monitor-skill NASA FIRMS REST API Fire → acreage signal
vessel-grain-tracker-skill AIS vessel tracking API Shipping → export estimates
sentinel-field-ndvi-skill Copernicus Sentinel-2 API Satellite → field health
parana-river-risk-skill Open-Meteo watershed model Weather → river level prediction
ORCHESTRATION SKILLS:
seasonal-spread-skill CBOT historical Quantitative models
client-briefing-skill Calls other skills internally Report compilation
Environment variables for the full stack:
# Weather
export OPEN_METEO_API_KEY="your-professional-api-key"
# Government data
export PSD_API_KEY="your-usda-fas-api-key"
# Trade data
export GTT_USER_ID="your-gtt-username"
export GTT_PASSWORD="your-gtt-password"
# Satellite
export NASA_FIRMS_KEY="your-earthdata-map-key"
export COPERNICUS_CLIENT_ID="your-copernicus-client-id"
export COPERNICUS_CLIENT_SECRET="your-copernicus-client-secret"
# Vessel tracking
export AIS_API_KEY="your-ais-subscription-key"
WORKFLOW SKILLS (process automation):
publication-compliance-skill Internal style/legal/citation rules Pre-submission compliance check
email-thread-intel-skill Email threads (.eml/.msg/raw text) Intent extraction & action items
agdb-query-assistant-skill Internal PostgreSQL data warehouse Natural language → safe SQL queries
ENTERPRISE ADOPTION SKILLS (GlobalAgri Capital scenario):
export-inspections-skill USDA FAS public CSV Weekly export pace tracker
wasde-extractor-skill USDA WASDE PDF (pages 12-19) Monthly S&D extraction
yield-model-skill MATLAB wrapper + Databricks inputs Existing model made runnable
daily-assessment-skill Broker emails + Google Sheet + FX Physical price assessment
databricks-bridge-skill Databricks SQL connector Skill outputs → shared lake
24 skills. 12 data sources. Three desks. One on-ramp.
The junior analyst who joined last month can type:
/noaa-crop-monitor-skill Morning scan
/vessel-grain-tracker-skill Brazil soy exports this week
/fire-crop-monitor-skill Cerrado burning season update
And get the same output that took the senior team 6 months to learn
how to produce manually. The institutional knowledge isn't in people's
heads anymore — it's in the skills. If someone leaves, the skills stay.
If someone joins, they're productive on day one.
That's what a skill library looks like when a team takes it seriously.
=============================================================
SKILL 16: Corporate Publication Compliance Checker
=============================================================
An agriculture commodity research analyst at a large bank or trading
house doesn't just write analysis — they publish it. Every client-facing
report must conform to corporate style guidelines, regulatory
disclosures, data citation standards, and compliance language. Getting
flagged by the compliance department delays publication by 2-3 days
and embarrasses the analyst. This skill catches problems before
submission.
User: /agent-skill-creator I'm a senior ag commodity analyst at a global bank. Every research note, weekly report, and market commentary I publish has to pass through our compliance and editorial review. The problem is I keep getting sent back for the same issues: missing disclaimers, inconsistent date formats, using "will" instead of "may" (forward-looking language compliance), citing data without proper attribution, inconsistent units (switching between bushels and metric tonnes without converting), and not following our house style guide. I waste 2-3 hours per report fixing these things AFTER compliance flags them. I want a skill that acts as a pre-submission compliance checker. I give it my draft and it tells me every issue before I send it to compliance. Here are our internal documents: references/house-style-guide.pdf (our editorial standards), references/compliance-language-rules.pdf (regulated language requirements from Legal), references/data-citation-policy.md (how to cite USDA, Bloomberg, exchange data), and references/report-templates/ (approved report templates for different publication types). This has to work for: weekly crop reports, flash market commentaries, quarterly outlook pieces, and client presentation decks.
Copilot (loading agent-skill-creator skill):
Reading references/house-style-guide.pdf...
Reading references/compliance-language-rules.pdf...
Reading references/data-citation-policy.md...
Scanning references/report-templates/ (4 templates found)...
This is a rule-based document validation skill. The challenge isn't
AI creativity — it's codifying dozens of specific, non-negotiable
rules from your internal documents and checking them exhaustively.
Every rule needs to be traceable back to a source document so the
analyst trusts the feedback. Let me build this.
Implicit requirements from your documents:
COMPLIANCE LANGUAGE RULES (from Legal):
- Forward-looking statements must use hedging language: "may",
"could", "we expect", "is likely to" — NEVER "will", "shall",
"is going to" when discussing future prices or production
- Every report must include the standard disclaimer block (provided
in compliance-language-rules.pdf, 3 variants: short/medium/full)
- Short disclaimer for flash commentaries (< 500 words)
- Medium disclaimer for weekly reports
- Full disclaimer for quarterly outlooks and client presentations
- Conflict of interest disclosure: if the bank has a trading position
in the commodity discussed, a specific sentence must appear
- "Not investment advice" language required in all external-facing
publications
- No price targets without the qualifier "our estimate" or "our model
suggests" — regulatory requirement for non-broker-dealer entities
- Analyst certification statement ("I, [name], certify that the views
expressed in this report accurately reflect my personal views...")
required for all quarterly publications
HOUSE STYLE GUIDE:
- Date format: "March 4, 2026" in body text. Never "3/4/2026" or
"04/03/2026" (ambiguous US/EU). Tables may use "Mar-26" shorthand
- Numbers: spell out one through nine, use numerals for 10+. Exception:
all numbers in data tables, all units ("5 MMT" not "five MMT")
- Units: metric tonnes (MT) is the house standard. If bushels are used
(for US-centric analysis), must include MT conversion in parentheses.
E.g., "52 bu/ac (3.5 MT/ha)" — never bushels without conversion
- Abbreviations: define on first use. "The U.S. Department of
Agriculture (USDA) released..." then "USDA" thereafter
- Report title format: "[COMMODITY] [TYPE] — [Date]"
E.g., "SOYBEANS WEEKLY — March 4, 2026"
- Section headers: ALL CAPS, no period. ("SUPPLY AND DEMAND" not
"Supply and demand.")
- Data freshness: every data point must include its reference date.
"Soybean exports reached 5.2 MMT (USDA, as of Feb 28)" — never
cite data without indicating when it was current
- Bloomberg data: cite as "Source: Bloomberg" with the ticker in
parentheses. E.g., "CBOT soybeans closed at $11.42/bu (S 1, Source:
Bloomberg)"
- USDA data: cite the specific report. "Source: USDA WASDE, February
2026" not just "Source: USDA"
- Exchange data: cite exchange name. "ICE Arabica (KC 1)" not just
"coffee futures"
- Rounding: prices to 2 decimal places, volumes to 1 decimal (MMT)
or whole numbers (MT), yields to 1 decimal (bu/ac or MT/ha)
- "Bearish" and "bullish" must be qualified: "bearish for nearby
futures" or "bullish for the 2026/27 outlook" — never standalone
"this is bullish"
DATA CITATION POLICY:
- Every chart, table, and key data point needs a source line
- Proprietary model outputs must be labeled: "Source: [Bank Name]
Estimates" or "Source: [Bank Name] Model"
- Third-party data cannot be republished in full — only excerpts with
proper attribution (Bloomberg redistribution terms)
- CFTC COT data: "Source: CFTC Commitments of Traders, as of [date]"
- Client-shared data: if a client provided proprietary data, it must
NOT appear in any published report without explicit permission
TEMPLATE CONFORMANCE:
- Each report type has an approved structure (section order, required
sections, optional sections)
- Weekly crop report template: Title → Executive Summary → Price
Action → Weather → Crop Conditions → Supply & Demand → Trade →
Outlook → Disclaimer
- Flash commentary template: Title → Key Point (1-2 sentences) →
Analysis (3-5 paragraphs) → Implication → Short Disclaimer
- Quarterly outlook: Title → Executive Summary → Macro Context →
Detailed S&D → Regional Breakdown → Price Forecast → Risk Factors
→ Analyst Certification → Full Disclaimer
- Missing a required section = compliance rejection
Building...
publication-compliance-skill/
├── SKILL.md
├── scripts/
│ ├── compliance_checker.py # Main orchestrator: load draft,
│ │ # run all rule engines, output report
│ ├── language_rules.py # Forward-looking language scanner,
│ │ # prohibited phrases, hedging checker
│ ├── disclaimer_checker.py # Verify correct disclaimer variant
│ │ # is present and matches report type
│ ├── style_checker.py # Date formats, number formatting,
│ │ # abbreviation first-use, unit rules
│ ├── citation_checker.py # Data source attribution validation,
│ │ # date freshness, Bloomberg/USDA/CFTC
│ ├── template_checker.py # Section order/presence vs template,
│ │ # title format, header style
│ ├── unit_converter.py # Detect bare bushel/MT values, suggest
│ │ # dual-unit format
│ └── report_builder.py # Compliance Pre-Check Report (PDF)
├── references/
│ ├── house-style-rules.md # Parsed style guide rules (machine-
│ │ # readable checklist format)
│ ├── compliance-phrases.md # Prohibited/required phrases + context
│ ├── disclaimer-templates.md # Short/medium/full disclaimer text
│ ├── citation-formats.md # Correct citation format by source
│ ├── report-templates.md # Section structure by report type
│ └── methodology.md
├── assets/
│ ├── prohibited_phrases.json # "will rise", "shall increase", etc.
│ ├── hedging_phrases.json # "may", "could", "we expect", etc.
│ ├── abbreviation_registry.json # Known abbreviations and expansions
│ ├── unit_conversions.json # bu/ac↔MT/ha, bu↔MT by commodity
│ ├── citation_patterns.json # Regex patterns for valid citations
│ └── templates/
│ ├── weekly_crop.json # Required/optional sections + order
│ ├── flash_commentary.json
│ ├── quarterly_outlook.json
│ └── client_presentation.json
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (no external credentials needed — all rules are local)
Installed at: ~/.agents/skills/publication-compliance-skill
Shared to: github.com/acme-trading/publication-compliance-skill
--- The analyst runs a pre-submission check on a weekly report ---
Analyst: /publication-compliance-skill Check this draft before I send it to compliance: drafts/soybeans-weekly-2026-03-04.md
Copilot (loading publication-compliance-skill):
Loading draft: drafts/soybeans-weekly-2026-03-04.md
Detected report type: Weekly Crop Report (from title format)
Running all compliance checks...
PUBLICATION COMPLIANCE PRE-CHECK
Report: SOYBEANS WEEKLY — March 4, 2026
Type: Weekly Crop Report
Word count: 2,847
════════════════════════════════════════════════════════
CRITICAL ISSUES (must fix before submission — compliance will reject)
════════════════════════════════════════════════════════
1. FORWARD-LOOKING LANGUAGE VIOLATION [Line 34]
Found: "Brazilian exports will exceed 90 MMT this season"
Rule: Never use "will" for future market/production outcomes
Fix: "Brazilian exports are expected to exceed 90 MMT..."
Source: compliance-language-rules.pdf §3.2
2. FORWARD-LOOKING LANGUAGE VIOLATION [Line 67]
Found: "Prices are going to test $10.50 support"
Rule: "going to" implies certainty about future prices
Fix: "Prices may test $10.50 support" or "Prices could test..."
Source: compliance-language-rules.pdf §3.2
3. MISSING DISCLAIMER [End of document]
Found: No disclaimer block detected
Rule: Weekly reports require the MEDIUM disclaimer variant (¶2-4
of the standard disclaimer, including non-investment-advice
language and data redistribution notice)
Fix: Append the medium disclaimer from templates/disclaimers.md
Source: compliance-language-rules.pdf §1.1
4. UNQUALIFIED PRICE TARGET [Line 89]
Found: "Fair value for Nov soybeans is $11.20"
Rule: Price targets must include attribution qualifier
Fix: "Our model suggests fair value for Nov soybeans near $11.20"
Source: compliance-language-rules.pdf §4.1
5. BARE DATA WITHOUT SOURCE [Line 52]
Found: "China imported 8.4 MMT of soybeans in February"
Rule: All data points require source and reference date
Fix: "China imported 8.4 MMT of soybeans in February (Source:
China Customs, as of Mar 1, 2026)"
Source: data-citation-policy.md §2.1
════════════════════════════════════════════════════════
STYLE ISSUES (should fix — editor will flag)
════════════════════════════════════════════════════════
6. DATE FORMAT [Line 12]
Found: "3/4/2026"
Rule: Body text requires "March 4, 2026" (never numeric M/D/Y)
Fix: "March 4, 2026"
Source: house-style-guide.pdf §7.1
7. DATE FORMAT [Line 78]
Found: "Feb 28th"
Rule: No ordinal suffixes on dates ("st", "nd", "rd", "th")
Fix: "Feb 28" (table) or "February 28" (body text)
Source: house-style-guide.pdf §7.1
8. UNIT CONSISTENCY [Line 23]
Found: "US yield of 52 bu/ac"
Rule: Bushels require metric conversion in parentheses
Fix: "US yield of 52 bu/ac (3.5 MT/ha)"
Source: house-style-guide.pdf §8.3
9. UNIT CONSISTENCY [Lines 41, 56, 71]
Found: Three more bare bushel references without MT conversion
Fix: Add "(X.X MT/ha)" or "(X.X MT)" after each bushel figure
Source: house-style-guide.pdf §8.3
10. ABBREVIATION FIRST USE [Line 8]
Found: "CONAB reported..." (first occurrence)
Rule: Abbreviations must be defined on first use
Fix: "Brazil's National Supply Company (CONAB) reported..."
Source: house-style-guide.pdf §6.2
11. ABBREVIATION FIRST USE [Line 15]
Found: "ABIOVE estimates..." (first occurrence)
Fix: "The Brazilian Vegetable Oil Industry Association (ABIOVE)
estimates..."
Source: house-style-guide.pdf §6.2
12. STANDALONE SENTIMENT [Line 92]
Found: "This is bearish."
Rule: Bearish/bullish must be qualified with timeframe and scope
Fix: "This is bearish for nearby CBOT soybean futures" or
"...bearish for the 2025/26 US export outlook"
Source: house-style-guide.pdf §11.1
13. NUMBER FORMATTING [Line 44]
Found: "production fell by 3 MMT"
Rule: Spell out one–nine; BUT exception for units — numerals OK.
Actually this IS correct (3 MMT uses numeral with unit).
Status: FALSE POSITIVE — no action needed.
════════════════════════════════════════════════════════
CITATION ISSUES (fix for data integrity)
════════════════════════════════════════════════════════
14. VAGUE USDA CITATION [Line 29]
Found: "Source: USDA"
Rule: Must specify which USDA report
Fix: "Source: USDA WASDE, February 2026" or "Source: USDA FAS
PSD, February 2026"
Source: data-citation-policy.md §3.1
15. MISSING BLOOMBERG TICKER [Line 61]
Found: "Source: Bloomberg"
Rule: Bloomberg citations require the terminal ticker
Fix: "Source: Bloomberg (S 1 Comdty)"
Source: data-citation-policy.md §3.3
16. STALE DATA REFERENCE [Line 47]
Found: "USDA projects 2025/26 exports at 1,825 million bushels"
Note: This is from the FEBRUARY WASDE. The March WASDE was
published yesterday (March 3). You should either update to
the March figure or add "(February estimate, prior to
March revision)"
Source: data-citation-policy.md §4.1
════════════════════════════════════════════════════════
TEMPLATE CHECK
════════════════════════════════════════════════════════
Weekly Crop Report — Required sections:
✓ Title (correct format: "SOYBEANS WEEKLY — March 4, 2026")
✓ Executive Summary
✓ Price Action
✓ Weather
✓ Crop Conditions
✓ Supply & Demand
✓ Trade
✗ Outlook (MISSING — required section)
✗ Disclaimer (MISSING — see Critical Issue #3)
Section header format:
✓ "PRICE ACTION" — correct (ALL CAPS, no period)
✓ "WEATHER" — correct
✗ "Crop Conditions" [Line 38] — should be "CROP CONDITIONS"
✗ "Supply and Demand." [Line 50] — remove period, use ALL CAPS:
"SUPPLY AND DEMAND"
════════════════════════════════════════════════════════
SUMMARY
════════════════════════════════════════════════════════
Critical (compliance will reject): 5 issues
Style (editor will flag): 6 issues (1 false positive)
Citation: 3 issues
Template: 2 missing sections, 2 header fixes
──────────────────────────────────────────────────────
TOTAL: 16 issues (15 real, 1 false positive)
ESTIMATED TIME TO FIX: 15-20 minutes
Without this check, compliance would have returned the draft in 2-3
business days with the same findings. Now you can fix everything in
one pass, resubmit clean, and publish on schedule.
Pre-check report: reports/compliance-check-soybeans-weekly-2026-03-04.pdf
--- The analyst fixes everything and re-runs ---
Analyst: /publication-compliance-skill Re-check the updated draft: drafts/soybeans-weekly-2026-03-04-v2.md
Copilot (loading publication-compliance-skill):
Loading draft: drafts/soybeans-weekly-2026-03-04-v2.md
Running all compliance checks...
PUBLICATION COMPLIANCE PRE-CHECK
Report: SOYBEANS WEEKLY — March 4, 2026
Type: Weekly Crop Report (v2)
Word count: 3,012
✓ Forward-looking language: PASSED (0 violations)
✓ Disclaimer: PASSED (medium variant detected, text matches template)
✓ Price targets: PASSED (all qualified with "our model suggests")
✓ Data citations: PASSED (all sources include report name and date)
✓ Date formats: PASSED (all "Month DD, YYYY" format)
✓ Unit consistency: PASSED (all bushel figures include MT conversion)
✓ Abbreviations: PASSED (all defined on first use)
✓ Sentiment qualifiers: PASSED ("bearish for nearby CBOT futures")
✓ Bloomberg tickers: PASSED (all citations include ticker)
✓ Template structure: PASSED (all 9 required sections present, correct order)
✓ Section headers: PASSED (all ALL CAPS, no periods)
✓ Data freshness: PASSED (updated to March WASDE figures)
RESULT: CLEAN — Ready for compliance submission.
0 critical issues. 0 style issues. 0 citation issues.
This draft should pass compliance review on first submission.
--- A flash commentary during a volatile session ---
Analyst: /publication-compliance-skill Quick check on this flash note I wrote during the session: drafts/flash-argentina-drought-2026-03-05.md
Copilot (loading publication-compliance-skill):
Loading draft: drafts/flash-argentina-drought-2026-03-05.md
Detected report type: Flash Commentary (from title + word count: 380)
Running compliance checks...
PUBLICATION COMPLIANCE PRE-CHECK
Report: SOYBEANS FLASH — Argentina Drought Deepens, March 5, 2026
Type: Flash Commentary
Word count: 380
CRITICAL:
1. DISCLAIMER VARIANT MISMATCH [End of document]
Found: Medium disclaimer (312 words)
Rule: Flash commentaries (< 500 words) use the SHORT disclaimer
(87 words). Using the medium variant makes the disclaimer
almost as long as the analysis itself.
Fix: Replace with short disclaimer from templates/disclaimers.md
Source: compliance-language-rules.pdf §1.1
STYLE:
2. FORWARD-LOOKING LANGUAGE [Line 8]
Found: "production will fall to 38-42 MMT"
Fix: "production could fall to 38-42 MMT"
3. MISSING SOURCE DATE [Line 5]
Found: "Buenos Aires Grain Exchange estimates"
Fix: "Buenos Aires Grain Exchange estimates (as of Mar 4, 2026)"
TEMPLATE:
✓ Title format: correct
✓ Key Point section: present
✓ Analysis section: present
✓ Implication section: present
✗ Disclaimer: present but wrong variant (see Critical #1)
SUMMARY: 1 critical, 2 style, 0 citation. Fix in 5 minutes.
The disclaimer swap is the one that matters. Compliance WILL reject
a flash note with a medium disclaimer — it looks like you copy-pasted
from a weekly template without adjusting.
--- Quarterly outlook — the most scrutinized report type ---
Analyst: /publication-compliance-skill Full audit on the Q2 outlook before it goes to the MD for sign-off: drafts/soybeans-q2-outlook-2026.md
Copilot (loading publication-compliance-skill):
Loading draft: drafts/soybeans-q2-outlook-2026.md
Detected report type: Quarterly Outlook (from title + template match)
Running compliance checks (FULL AUDIT mode for quarterly)...
PUBLICATION COMPLIANCE FULL AUDIT
Report: SOYBEANS QUARTERLY OUTLOOK — Q2 2026
Type: Quarterly Outlook
Word count: 8,420
This report type receives the highest compliance scrutiny. Quarterly
outlooks are distributed to institutional clients and may be cited in
media. Running all checks at maximum sensitivity.
════════════════════════════════════════════════════════
CRITICAL ISSUES
════════════════════════════════════════════════════════
1. MISSING ANALYST CERTIFICATION [End of document]
Rule: Quarterly outlooks require the analyst certification
statement: "I, [Name], certify that the views expressed in
this report accurately reflect my personal views and that no
part of my compensation was, is, or will be related to the
specific recommendations or views expressed herein."
Fix: Add certification between Risk Factors and Full Disclaimer
Source: compliance-language-rules.pdf §6.1
2. FORWARD-LOOKING LANGUAGE (3 instances) [Lines 112, 245, 389]
"Prices will recover..." → "Prices may recover..."
"China will import..." → "China is expected to import..."
"The trade war will escalate..." → "The trade war could escalate..."
3. PROPRIETARY MODEL OUTPUT WITHOUT LABEL [Line 201]
Found: Table with "Price Forecast" column showing $10.80, $11.40,
$12.10 for Q2, Q3, Q4
Rule: Proprietary model outputs must be labeled "Source: [Bank]
Estimates" or "Source: [Bank] Quantitative Model"
Fix: Add source line under table: "Source: [Bank Name] Quantitative
Commodity Model. Forecasts are subject to revision."
════════════════════════════════════════════════════════
STYLE ISSUES
════════════════════════════════════════════════════════
4. UNIT CONSISTENCY [8 instances]
Found 8 bushel-only figures missing metric conversions.
Quarterly outlooks have international readership — metric
conversions are especially important.
[Line 45] "51.5 bu/ac" → "51.5 bu/ac (3.46 MT/ha)"
[Line 78] "1,825 M bu" → "1,825 million bushels (49.7 MMT)"
... (6 more, see full report)
5. ROUNDING [Lines 156, 203]
Found: "exports at 5.23456 MMT"
Rule: Volumes round to 1 decimal place for MMT
Fix: "exports at 5.2 MMT"
════════════════════════════════════════════════════════
CITATION ISSUES
════════════════════════════════════════════════════════
6. STALE DATA (WASDE) [Lines 67, 89, 134]
Your draft cites "USDA WASDE, February 2026" in three places.
The March WASDE has been published. For a quarterly outlook going
to print in March, all WASDE references should be March 2026
unless you're specifically discussing the February-to-March
revision.
7. THIRD-PARTY DATA REDISTRIBUTION [Line 290]
Found: Full reproduction of a Bloomberg table (12 rows of daily
CBOT settlement prices)
Rule: Bloomberg data redistribution terms limit verbatim
reproduction. Summarize, chart, or excerpt — don't reproduce
full daily settlement tables.
Fix: Replace with a summary ("CBOT soybeans traded in a $10.20-
$11.60 range during Q1") or a chart, with "Source: Bloomberg"
════════════════════════════════════════════════════════
TEMPLATE CHECK
════════════════════════════════════════════════════════
Quarterly Outlook — Required sections:
✓ Title
✓ Executive Summary
✓ Macro Context
✓ Detailed S&D
✓ Regional Breakdown
✓ Price Forecast
✓ Risk Factors
✗ Analyst Certification (MISSING — see Critical #1)
✓ Full Disclaimer (correct variant, text matches)
Section order: CORRECT (all sections in approved sequence)
════════════════════════════════════════════════════════
SUMMARY
════════════════════════════════════════════════════════
Critical: 3 issues (certification, language, model label)
Style: 9 issues (8 unit conversions, 1 rounding)
Citation: 2 issues (stale WASDE, Bloomberg redistribution)
Template: 1 missing section
──────────────────────────────────────────────────────
TOTAL: 15 issues
ESTIMATED TIME TO FIX: 30-40 minutes
The Bloomberg redistribution flag is the one that could cause
real problems. Legal has flagged analysts before for reproducing
terminal data verbatim. Summarize or chart it — don't copy the table.
The analyst certification is a simple paste, but forgetting it on a
quarterly that goes to 200+ institutional clients would be a career
embarrassment. This is exactly why you run the checker first.
Full audit report: reports/compliance-audit-soy-q2-outlook-2026.pdf
=============================================================
WHY THIS SKILL WORKS
=============================================================
The publication compliance skill is probably the highest-ROI skill in
the entire library. Consider:
WITHOUT THE SKILL:
- Analyst writes report: 3-4 hours
- Submits to compliance: 1 day turnaround (best case)
- Gets 10-15 issues back: 1-2 hours to fix
- Resubmits: another 1 day turnaround
- Gets 2-3 more issues: 30 min to fix
- Final approval: maybe day 4 after writing
- Total: 5-7 hours of analyst time + 2-4 days of calendar time
WITH THE SKILL:
- Analyst writes report: 3-4 hours
- Runs /publication-compliance-skill: 30 seconds
- Fixes all 15 issues in one pass: 20-40 minutes
- Submits clean draft to compliance: passes first time
- Total: 4-5 hours of analyst time + 1 day of calendar time
SAVINGS: 2-3 hours per report × 4 reports/month = 8-12 hours/month
per analyst. For a team of 6 analysts, that's 50-70 hours/month of
senior analyst time recovered.
But the real value isn't the hours — it's the publication speed.
A weekly crop report that publishes Monday morning instead of
Wednesday afternoon is infinitely more valuable to clients who trade
on it. Timeliness IS the product in commodity research.
The skill also serves as institutional knowledge preservation. When the
head of compliance retires, the rules don't disappear — they're codified
in the skill's reference files. When a new regulation changes the
disclaimer language, you update one JSON file and every analyst's next
check reflects the change automatically.
This is the kind of skill that doesn't seem exciting — no satellite
data, no vessel tracking, no yield models. But it's the one the team
uses every single day, and it's the one the managing director notices
because reports stop getting bounced back.
=============================================================
SKILL 17: Email Thread Intelligence — Intent & Requirements Extractor
=============================================================
Every analyst, PM, and researcher has lived this nightmare: a 47-message
email thread spanning 3 weeks, 9 participants, 4 conflicting opinions,
2 scope changes buried in reply #31, and one critical deadline mentioned
once in a forwarded attachment. Someone asks "what did we actually agree
to?" and nobody can answer without re-reading the entire chain. This
skill reads the mess and tells you what's real.
User: /agent-skill-creator I spend at least an hour a day trying to parse long email threads from clients, internal stakeholders, and cross-functional teams. The problem isn't individual emails — it's threads that mutate over time. A client starts by asking for one thing, then someone on our side proposes an alternative, then the client's boss jumps in and changes the scope, then there are 15 replies about scheduling that bury the actual decision, and by reply #40 nobody remembers what was originally asked. I need a skill that I can paste an email thread into (or point at a .eml/.msg file) and get back: (1) the ACTUAL requirements — not what was first asked, but what was LAST agreed to, tracking how requirements evolved through the thread, (2) all action items with owners and deadlines, (3) open questions that were asked but never answered, (4) decisions that were made (and WHO made them — authority matters), (5) scope changes — what was added, removed, or modified from the original request, and (6) conflicting statements where two people said incompatible things and nobody resolved it. I work in commodity research but this is a universal problem — every knowledge worker has it. Here's an example of the kind of thread I deal with: references/sample-client-thread.eml (62 messages, 12 participants, 3 weeks).
Copilot (loading agent-skill-creator skill):
Reading references/sample-client-thread.eml...
62 messages. 12 participants. 21 days. This is a textbook case of
requirements drift buried in conversational noise. The core challenge
is distinguishing signal from noise: most messages are scheduling,
acknowledgments, CC additions, and side conversations. The real
decisions are in maybe 8-10 messages. Let me build a skill that
finds them.
Implicit requirements:
- Input formats: raw pasted text, .eml files (RFC 5322), .msg files
(Outlook), or a batch of .eml files for multi-thread analysis
- Thread reconstruction: emails arrive out of order, have inconsistent
quoting styles (>, |, inline), forwarded sub-threads, and sometimes
broken In-Reply-To headers. Need to rebuild the conversation tree
- Participant identification: same person may appear as "John Smith",
"John", "JS", "john.smith@acme.com", and "Smith, John (London)".
Need entity resolution across the thread
- Authority detection: not all participants are equal. A director
saying "let's do X" overrides an analyst suggesting "maybe Y".
Detect seniority signals from: email signatures (titles), CC vs TO
position, who others defer to, explicit authority statements ("I've
approved this")
- Temporal tracking: requirements stated in message #5 may be
superseded by message #28. The skill must track the EVOLUTION,
not just extract from the latest message
- Implicit vs explicit: "sounds good" in reply to a proposal = implicit
agreement. "Per our call, we agreed to..." = explicit decision.
Both matter but carry different confidence levels
- Negation detection: "Actually, scratch that — let's go with plan B"
negates everything in the preceding proposal
- Attachment awareness: "see attached SOW" or "per the deck I sent
Tuesday" — flag that a requirement lives outside the email body
- Cross-thread references: "as discussed in the other thread about
the Brazil report" — flag that context exists elsewhere
- Output must be structured, scannable, and cite specific messages
by sender + timestamp so the analyst can verify
Building...
email-thread-intel-skill/
├── SKILL.md
├── scripts/
│ ├── thread_parser.py # Parse .eml/.msg/raw text into
│ │ # structured message objects
│ │ # (sender, date, body, quoted text)
│ ├── thread_reconstructor.py # Rebuild conversation tree from
│ │ # In-Reply-To, References, quoting
│ │ # patterns, and timestamp ordering
│ ├── participant_resolver.py # Entity resolution: merge "John",
│ │ # "JS", "john.smith@acme.com" into
│ │ # one person with role/seniority
│ ├── intent_tracker.py # Track requirements through the
│ │ # thread: initial ask → modifications
│ │ # → supersessions → final state
│ ├── decision_extractor.py # Find explicit decisions, implicit
│ │ # agreements, and authority signals
│ ├── action_item_finder.py # "Can you send me..." / "I'll have
│ │ # this by Friday" / "ACTION: ..."
│ │ # with owner + deadline extraction
│ ├── conflict_detector.py # Find incompatible statements from
│ │ # different participants that were
│ │ # never explicitly resolved
│ ├── question_tracker.py # Questions asked but never answered
│ │ # in subsequent messages
│ ├── scope_diff.py # Compare initial request vs final
│ │ # agreed state: added/removed/changed
│ └── report_builder.py # Thread Intelligence Brief (markdown
│ # + optional PDF)
├── references/
│ ├── parsing-patterns.md # Email quoting styles, signature
│ │ # patterns, forwarding formats
│ ├── intent-signals.md # Linguistic markers for decisions,
│ │ # proposals, agreements, rejections
│ ├── authority-heuristics.md # How to infer seniority from email
│ │ # metadata and language patterns
│ └── methodology.md
├── assets/
│ ├── decision_phrases.json # "let's go with", "approved", "agreed"
│ ├── action_phrases.json # "can you", "please send", "I'll do"
│ ├── negation_phrases.json # "actually", "scratch that", "instead"
│ ├── hedge_phrases.json # "maybe", "what if", "just thinking"
│ │ # (proposals, not decisions)
│ └── title_seniority.json # "MD" > "Director" > "VP" > "Associate"
│ # (for authority weighting)
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (no external APIs — all processing is local)
Installed at: ~/.agents/skills/email-thread-intel-skill
Shared to: github.com/acme-trading/email-thread-intel-skill
--- The analyst pastes a nightmarish client thread ---
Analyst: /email-thread-intel-skill Parse this thread and tell me what the client actually wants. I've been CC'd into the middle of it and I'm lost: emails/client-brazil-soy-report-thread.eml
Copilot (loading email-thread-intel-skill):
Parsing emails/client-brazil-soy-report-thread.eml...
47 messages, 9 participants, spanning Feb 10 – Mar 3, 2026.
Reconstructing conversation tree...
Resolving participants...
Extracting requirements, decisions, and action items...
THREAD INTELLIGENCE BRIEF
Subject: "RE: RE: FW: Brazil Soy Report — Scope & Deliverables"
════════════════════════════════════════════════════════
PARTICIPANTS (resolved)
════════════════════════════════════════════════════════
| Name | Role | Org | Messages | Authority |
|--------------------|-----------------------|------------|----------|-----------|
| Sarah Chen | Portfolio Manager | Client | 8 | HIGH |
| David Park | Head of Research | Client | 3 | HIGHEST |
| Lisa Nakamura | Research Analyst | Client | 12 | MEDIUM |
| Tom Bradley | Trading Desk | Client | 6 | MEDIUM |
| You (Maria Santos) | Senior Analyst | Our Firm | 7 | — |
| James Wilson | Head of Ag Research | Our Firm | 4 | HIGH |
| Alex Rivera | Junior Analyst | Our Firm | 5 | LOW |
| Priya Sharma | Sales Coverage | Our Firm | 1 | LOW |
| Rachel Kim | Compliance | Our Firm | 1 | N/A |
Note: "Lisa N.", "L. Nakamura", and "lisa.nakamura@clientfund.com"
are the same person (12 messages total, not 3 people with 4 each).
════════════════════════════════════════════════════════
REQUIREMENTS EVOLUTION (what changed over time)
════════════════════════════════════════════════════════
ORIGINAL REQUEST (Feb 10, Sarah Chen):
"We need a deep-dive report on Brazil soybean production risk for
the 2025/26 season. 15-20 pages. Focus on weather impact and
export pace. Deadline: end of February."
MODIFICATION #1 (Feb 14, Lisa Nakamura):
"Can you also include Argentina? The drought situation there is
getting interesting. Maybe a comparative section."
Status: ACCEPTED by Sarah Chen (Feb 14): "Good idea Lisa, yes
please include Argentina."
→ SCOPE EXPANDED: Argentina added as comparative section
MODIFICATION #2 (Feb 18, Tom Bradley, Trading Desk):
"For the trading desk, we also need short-term price scenarios.
Like what happens to the May-July spread if USDA cuts Argentina
by 5 MMT in March. Give us 3 scenarios with price targets."
Status: PARTIALLY ACCEPTED by Sarah Chen (Feb 19): "The scenarios
are useful but let's keep it to 2 scenarios — bull and bear case.
Three is too many for the investment committee."
→ SCOPE EXPANDED: Price scenarios added, but 2 not 3
MODIFICATION #3 (Feb 24, David Park, Head of Research):
"I want this to also serve as input for our quarterly allocation
meeting on March 15. Add a one-page executive summary that a
generalist portfolio manager can read in 2 minutes. And push
the deadline to March 10 — we need it 5 days before the meeting."
Status: THIS IS THE FINAL AUTHORITY. David Park is the most senior
client participant. No one contradicted this.
→ DEADLINE CHANGED: Feb 28 → March 10
→ SCOPE EXPANDED: Executive summary added (1 page, generalist audience)
→ PURPOSE EXPANDED: Now serves quarterly allocation meeting
MODIFICATION #4 (Feb 26, Lisa Nakamura):
"One more thing — can you include a section on Chinese demand? I
know it's not in the original scope but it's really driving the
price action."
Status: ⚠️ NEVER EXPLICITLY APPROVED OR REJECTED. Sarah Chen
did not respond to this message. Lisa does not have authority to
expand scope unilaterally. James Wilson (our side) replied "we can
look into it" — but that's our internal response, not client
approval.
→ AMBIGUOUS: China demand section — in scope or not?
════════════════════════════════════════════════════════
FINAL AGREED REQUIREMENTS (as of last message, Mar 3)
════════════════════════════════════════════════════════
✓ CONFIRMED:
1. Deep-dive on Brazil soybean production risk (2025/26)
— Weather impact, crop conditions, production estimates
— Source: Sarah Chen, Feb 10 (original request)
2. Argentina comparative section (drought analysis)
— Source: Lisa Nakamura, Feb 14 → approved by Sarah Chen
3. Two price scenarios: bull case and bear case
— Include May-July spread implications
— Source: Tom Bradley, Feb 18 → modified by Sarah Chen to 2 scenarios
4. One-page executive summary for generalist audience
— Source: David Park, Feb 24 (highest authority)
5. Export pace analysis (Brazil)
— Source: Sarah Chen, Feb 10 (original request)
6. Length: 15-20 pages (excluding exec summary)
— Source: Sarah Chen, Feb 10 (never modified)
7. Deadline: March 10, 2026
— Source: David Park, Feb 24 (overrode original Feb 28)
⚠️ UNRESOLVED:
8. China demand section — requested by Lisa (Feb 26), never approved
by Sarah or David. Recommend: email Sarah directly to confirm
before spending time on this.
✗ SUPERSEDED (no longer valid):
9. "3 price scenarios" — Tom Bradley's request was narrowed to 2 by
Sarah Chen. Do NOT deliver 3 scenarios.
10. "End of February deadline" — overridden by David Park to March 10.
════════════════════════════════════════════════════════
ACTION ITEMS
════════════════════════════════════════════════════════
| # | Action | Owner | Deadline | Status |
|---|-------------------------------------|-----------------|-----------|-----------|
| 1 | Deliver Brazil/Argentina soy report | Maria Santos | Mar 10 | IN PROGRESS|
| 2 | Send interim data tables to Lisa | Alex Rivera | Feb 28 | ⚠️ OVERDUE |
| 3 | Confirm China section in/out | Maria Santos | ASAP | OPEN |
| 4 | Share draft for internal review | Maria Santos | Mar 5 | OPEN |
| 5 | Compliance review of draft | Rachel Kim | Mar 7 | PENDING |
| 6 | Schedule client call for Mar 12 | Priya Sharma | Mar 3 | ⚠️ OVERDUE |
NOTE: Action item #2 is OVERDUE. Alex Rivera agreed on Feb 20 to
"send the PSD tables by end of the month." It's now March 3. Lisa
asked about it on Feb 28 and got no response. This needs follow-up
immediately — the client noticed.
════════════════════════════════════════════════════════
UNANSWERED QUESTIONS
════════════════════════════════════════════════════════
1. Lisa Nakamura (Feb 22): "Should the price scenarios use the
March WASDE numbers or our own estimates?"
→ Nobody responded. This affects the entire scenarios section.
Recommend: ask Sarah or decide internally and state assumption.
2. Tom Bradley (Feb 25): "Can you include the May-July spread chart
going back 10 years? I want to show the trading committee."
→ Nobody responded. Simple request, probably should just do it.
3. Sarah Chen (Feb 27): "What format are you thinking — Word doc
or PDF? Last time the formatting was off in PDF."
→ James Wilson replied "we'll send both" (Mar 1). But did Maria
confirm? The thread ended without Maria acknowledging.
════════════════════════════════════════════════════════
CONFLICTS (incompatible statements, never resolved)
════════════════════════════════════════════════════════
CONFLICT #1: Report audience
- Sarah Chen (Feb 10): "This is for our ag research team" (specialist
audience, technical depth expected)
- David Park (Feb 24): "Add a one-page exec summary for a generalist
portfolio manager" (implies the REPORT will be read by generalists)
These aren't necessarily incompatible — the report can be technical
with a generalist exec summary. But clarify: is the generalist going
to read ONLY the exec summary, or the whole report? If the whole
report, the writing style needs to shift.
CONFLICT #2: Argentina depth
- Lisa Nakamura (Feb 14): "Maybe a comparative section" (brief)
- Tom Bradley (Feb 20): "The Argentina drought is the real story —
give it equal weight to Brazil" (deep)
Sarah Chen approved "include Argentina" but didn't specify depth.
These two colleagues are asking for different things. Recommend:
3-5 pages on Argentina (not a full separate analysis, but more than
a sidebar).
════════════════════════════════════════════════════════
SCOPE DIFF (original → final)
════════════════════════════════════════════════════════
ORIGINAL (Feb 10) → FINAL (as of Mar 3)
──────────────────────────────────────────────────────
Brazil only → Brazil + Argentina comparative
No price scenarios → 2 price scenarios (bull/bear)
No exec summary → 1-page exec summary (generalist)
15-20 pages → 15-20 pages + exec summary
Due: end of February → Due: March 10
Audience: ag research → Audience: ag research + PM (exec summary)
No spread analysis → May-July spread implications
No China coverage → China: ⚠️ UNRESOLVED
The scope has approximately DOUBLED since the original request.
The deadline moved back by 10 days, but the scope grew faster than
the timeline. Flag this to James Wilson — this may need a revised
LOE estimate.
════════════════════════════════════════════════════════
RECOMMENDED NEXT STEPS
════════════════════════════════════════════════════════
1. URGENT: Follow up on Alex's overdue data tables to Lisa (Feb 28)
2. Email Sarah Chen directly: "Should we include a China demand
section? Lisa suggested it — want to confirm before we invest
the time." (5 seconds of her time, saves you 4 hours of work)
3. Ask Sarah or Lisa: "For the price scenarios, should we use USDA's
official estimates or our internal model?" (unanswered question #1)
4. Just include the 10-year May-July spread chart — it's easy, Tom
asked for it, and nobody objected
5. Send both Word and PDF per James's commitment
6. Flag to James Wilson that scope has doubled — is the March 10
deadline still realistic with current resources?
--- Quick follow-up on a different thread ---
Analyst: /email-thread-intel-skill Quick scan — just the action items and deadlines from this internal thread: emails/weekly-publication-schedule.eml
Copilot (loading email-thread-intel-skill):
Parsing emails/weekly-publication-schedule.eml...
23 messages, 5 participants (all internal), spanning Feb 28 – Mar 4.
Quick scan mode (action items + deadlines only)...
ACTION ITEMS — Weekly Publication Schedule Thread
| # | Action | Owner | Deadline | Source Message |
|---|---------------------------------------|----------------|---------------|----------------------|
| 1 | Soybeans Weekly draft | Maria Santos | Mon Mar 4 9am | James W., Feb 28 |
| 2 | Wheat Weekly draft | Alex Rivera | Mon Mar 4 9am | James W., Feb 28 |
| 3 | Coffee Flash (if ICE moves > 3%) | Maria Santos | Same day | James W., Feb 28 |
| 4 | Update S&D model with March WASDE | Alex Rivera | Tue Mar 5 | Maria S., Mar 3 |
| 5 | Client call prep deck (Chen account) | Maria Santos | Wed Mar 5 | Priya S., Mar 1 |
| 6 | Review all drafts before compliance | James Wilson | Mon Mar 4 2pm | James W., Feb 28 |
SCHEDULING CONFLICT DETECTED:
Maria Santos has 3 deliverables due Monday morning (items 1, 3, 6)
plus the Chen report (from the other thread) in progress. James
Wilson committed to review "all drafts by 2pm Monday" — but Maria's
soybeans draft is due at 9am and James typically doesn't review
until after lunch. Recommend: send James the draft Friday evening
for early Monday review.
OVERDUE: None — all deadlines are upcoming.
UNANSWERED: Alex Rivera hasn't acknowledged item #4 (WASDE update).
--- The universal use case: "what did we decide on the call?" ---
Analyst: /email-thread-intel-skill Someone took rough notes during a client call and emailed them out. Parse these notes and give me the real decisions and follow-ups. There were "action items" listed but I don't think they're complete: emails/call-notes-chen-account-mar3.eml
Copilot (loading email-thread-intel-skill):
Parsing emails/call-notes-chen-account-mar3.eml...
1 message (call notes email) + 6 reply messages (corrections/additions).
Processing notes + corrections...
CALL INTELLIGENCE — Chen Account, March 3, 2026
STATED IN ORIGINAL NOTES (sent by Priya Sharma):
- "Client wants the report by March 10" ✓ Consistent with thread
- "Discussed including China demand section" — VAGUE
- "Tom wants spread analysis" ✓ Consistent with thread
- Action items listed: "Maria to send draft by Mar 7"
CORRECTIONS FROM REPLY CHAIN:
- James Wilson (Mar 3, 4:12pm): "Actually, Sarah said March 10 for
FINAL, not draft. Draft review should be internal by March 7.
Priya's notes have this backwards."
- Lisa Nakamura (Mar 3, 5:30pm): "To clarify — I asked about China
and Sarah said 'if there's time, sure, but don't delay the report
for it.' So it's optional, not required."
THIS IS CRITICAL. The reply chain CONTRADICTS the original notes:
| Item | Original Notes Say | Replies Corrected To |
|--------------------|-----------------------|-----------------------------|
| March 10 deadline | Report due Mar 10 | FINAL due Mar 10, draft Mar 7|
| China section | "Discussed" | Optional — don't delay for it|
| Draft to client | "Maria to send by Mar 7" | Mar 7 is INTERNAL review |
If you followed the original notes, you'd send the client a draft on
March 7 (wrong — that's the internal review date) and you'd spend
4 hours on the China section (unnecessary — Sarah said optional).
REAL ACTION ITEMS (merged from notes + corrections):
| # | Action | Owner | Deadline | Confidence |
|---|----------------------------------|---------------|----------|------------|
| 1 | Internal draft ready | Maria Santos | Mar 7 | HIGH |
| 2 | James reviews draft | James Wilson | Mar 7-8 | HIGH |
| 3 | Compliance review | Rachel Kim | Mar 8-9 | MEDIUM |
| 4 | Final report to client | Maria Santos | Mar 10 | HIGH |
| 5 | China section (OPTIONAL) | Maria Santos | only if time | MEDIUM |
| 6 | Include 10yr spread chart | Alex Rivera | with draft| HIGH |
The notes Priya sent are 60% accurate. The reply corrections are
essential. If you'd only read Priya's email, you'd have the wrong
deadline structure and waste time on an optional section.
=============================================================
WHY THIS SKILL WORKS
=============================================================
This skill is universal. It's not specific to commodity research,
finance, or any industry. Every knowledge worker in every company
deals with:
- Email threads that mutate requirements over 20+ messages
- Meeting notes that don't match what was actually discussed
- Scope creep buried in casual replies ("oh and can you also...")
- Action items with no clear owner or deadline
- Questions that get asked but fall through the cracks
- Authority ambiguity — who actually has the power to decide?
The skill doesn't need APIs, credentials, or external data. It runs
entirely on the text you give it. The intelligence is in the parsing:
- TEMPORAL TRACKING: message #5 says X, message #28 overrides X
with Y. The skill knows Y is current, not X.
- AUTHORITY WEIGHTING: the Head of Research saying "do this"
outweighs a junior analyst suggesting "maybe that."
- SILENCE DETECTION: a question asked in message #15 that nobody
answered in the next 32 messages is a dropped ball.
- IMPLICIT AGREEMENT: "sounds good" = soft yes. "I've approved
this" = hard yes. Both are agreements but at different confidence.
- NEGATION AWARENESS: "Actually, scratch that" makes everything
before it in that reply irrelevant.
The ROI is immediate and measurable:
WITHOUT THE SKILL:
- Re-read 47-message thread: 30-45 minutes
- Still miss 2-3 buried decisions or scope changes
- Start working on superseded requirements (wasted hours)
- Miss an overdue action item (damages client relationship)
- Misinterpret call notes (wrong deliverable timeline)
WITH THE SKILL:
- Paste thread, get intelligence brief: 30 seconds
- Full visibility into requirements evolution
- Clear action items with owners and deadlines
- Conflicts and unanswered questions surfaced explicitly
- Zero time re-reading — jump straight to acting
The skill pays for itself the first time it catches a scope change
you would have missed, or surfaces an overdue action item that was
about to become a client complaint.
=============================================================
SKILL 18: Internal Database Query Assistant — Onboarding
Non-Technical Analysts to Company Data
=============================================================
This is arguably the most common enterprise problem: the company has
a rich internal database (or data warehouse, or lakehouse) with years
of proprietary data — trade records, position history, client
portfolios, internal forecasts, broker contacts, shipping logs. The
data team built it, documented it (partially), and gave everyone
read-only credentials. The problem? Most analysts can't write SQL.
They depend on the data team for every ad-hoc query, wait 2-3 days
for a response, and often get back something different from what they
asked for because the request was ambiguous. This skill turns the
database documentation and schema into a query-writing assistant that
knows the company's specific tables, naming conventions, gotchas, and
business logic — so non-technical analysts can get answers in seconds
instead of days.
User: /agent-skill-creator Our firm has an internal PostgreSQL data warehouse called "agdb" that contains 15 years of proprietary commodity data — trade executions, position history, client order flow, internal S&D model outputs, broker price indications, shipping fixtures, and warehouse stock reports. The data team documented it in a Confluence-style wiki that I've exported here: references/agdb-schema-docs.pdf (142 pages — every table, every column, every relationship). The problem is nobody outside the data team knows how to query it. I'm one of 12 commodity analysts who have read-only access (via a connection string in env as AGDB_READ_DSN) but I don't really know SQL. When I need data, I send a Slack message to the data team and wait 1-3 days. Sometimes they misunderstand what I need and I wait another day for a revision. I want a skill that: (1) understands our entire schema — all 87 tables, the relationships, the naming conventions, the business logic embedded in the column definitions, (2) lets me ask questions in plain English and generates safe, read-only SQL queries, (3) EXPLAINS what the query does before running it so I can verify it's what I meant, (4) runs the query and formats the results into a clean table or chart, (5) knows our firm-specific conventions — like that "position" means net position (long minus short), that our fiscal year starts April 1, that prices in the trades table are in cents per bushel for grains but dollars per metric tonne for oilseeds, and (6) has guardrails so I can't accidentally run something destructive or pull restricted client data. I also want my colleagues to use this — some know basic SQL, some know zero. Here's a sample of common queries the data team runs for us: references/common-queries-catalog.pdf (their top 50 most-requested queries with SQL).
Copilot (loading agent-skill-creator skill):
Reading references/agdb-schema-docs.pdf (142 pages)...
Reading references/common-queries-catalog.pdf...
This is a schema-aware query generation skill with safety guardrails.
The 142-page schema doc is the gold — it contains the institutional
knowledge that makes queries correct (fiscal year conventions, unit
differences, net position logic). The top-50 query catalog is the
training set — these are proven-correct queries I can decompose into
patterns. Let me build this.
Implicit requirements from your documents:
SCHEMA OVERVIEW (from agdb-schema-docs.pdf):
- 87 tables across 8 schemas:
trading.* — 14 tables (executions, positions, orders, fills)
market.* — 11 tables (prices, curves, settlements, vol surfaces)
research.* — 9 tables (forecasts, model outputs, S&D balances)
shipping.* — 12 tables (fixtures, vessel tracking, freight rates)
warehouse.* — 8 tables (stocks, receipts, deliveries, locations)
clients.* — 10 tables (accounts, portfolios, order history)
reference.* — 15 tables (instruments, exchanges, brokers, regions)
audit.* — 8 tables (change logs, access logs, query logs)
- Naming convention: snake_case everywhere, e.g. trading.daily_positions,
market.settlement_prices
- Primary keys: all tables use surrogate integer IDs (table_id)
- Foreign keys: instrument_id links to reference.instruments across
all schemas. client_id links to clients.accounts
- Temporal columns: trade_date (date), created_at (timestamp with tz),
updated_at (timestamp). Most analytical queries use trade_date
- Soft deletes: is_deleted boolean on most tables (must filter!)
FIRM-SPECIFIC CONVENTIONS (critical for correct queries):
- "Position" = net position (long_qty - short_qty), NOT gross
- Fiscal year: April 1 – March 31 (FY2026 = Apr 2025 – Mar 2026)
- Crop year: varies by commodity:
US corn/soy: Sep 1 – Aug 31
US wheat: Jun 1 – May 31
Brazil soy: Feb 1 – Jan 31
Coffee: Oct 1 – Sep 30
- Price units in trading.executions:
Grains (corn, wheat, oats): cents per bushel (divide by 100 for $/bu)
Oilseeds (soybeans, canola): cents per bushel
Oilseed products (meal, oil): dollars per short ton (meal), cents
per pound (oil)
Coffee: cents per pound
Sugar: cents per pound
Cotton: cents per pound
Freight: $/MT (worldscale for tankers)
- When analysts say "P&L", they mean realized + unrealized, marked to
the prior day's settlement (market.settlement_prices)
- The research.forecasts table contains both published and draft
forecasts. Always filter: status = 'published' unless explicitly
looking at drafts
- The clients.* schema is RESTRICTED: only client_id, region, and
segment columns are accessible to analysts. Personal details
(name, contact, AUM) require compliance approval
SAFETY REQUIREMENTS:
- READ-ONLY: connection uses a read-only PostgreSQL role. But the
skill should also validate queries before execution — no INSERT,
UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, GRANT
- QUERY LIMITS: auto-append LIMIT 10000 to any query without an
explicit LIMIT (prevent accidental full-table scans on 500M+ row
tables)
- CLIENT DATA REDACTION: if a query touches clients.* schema,
automatically exclude name, email, phone, address columns. Replace
with client_id only
- AUDIT LOGGING: log every query executed (query text, user, timestamp,
row count) to a local file for the data team to review
- EXPLAIN BEFORE RUN: always show the generated SQL and a plain-English
explanation before executing. User must confirm or modify
- TIMEOUT: 30-second query timeout. If exceeded, suggest adding
filters or ask the data team for help
- NO JOINS ON AUDIT.*: the audit schema is for compliance only — never
join it into analytical queries
Building...
agdb-query-assistant-skill/
├── SKILL.md
├── scripts/
│ ├── query_generator.py # Natural language → SQL translation
│ │ # using schema context + conventions
│ ├── schema_loader.py # Parse schema docs into structured
│ │ # metadata (tables, columns, types,
│ │ # relationships, conventions)
│ ├── query_validator.py # Safety checks: read-only enforcement,
│ │ # LIMIT injection, client data
│ │ # redaction, audit schema blocking
│ ├── query_explainer.py # SQL → plain English explanation
│ │ # ("This query finds all soybean
│ │ # trades from the last 30 days...")
│ ├── query_executor.py # Run query via AGDB_READ_DSN, handle
│ │ # timeouts, format results
│ ├── result_formatter.py # Output as table, CSV, chart, or
│ │ # summary depending on result shape
│ ├── unit_converter.py # Auto-convert cents/bu to $/bu,
│ │ # $/short ton to $/MT, etc. based
│ │ # on commodity context
│ ├── common_queries.py # Pre-built query templates from the
│ │ # top-50 catalog (parameterized)
│ └── audit_logger.py # Log all executed queries locally
├── references/
│ ├── schema-summary.md # Human-readable schema overview
│ │ # (condensed from 142-page PDF)
│ ├── table-catalog.md # All 87 tables with descriptions
│ ├── column-conventions.md # Price units, date conventions,
│ │ # fiscal year, crop year logic
│ ├── relationship-map.md # Foreign key graph (what joins what)
│ ├── common-patterns.md # Top-50 query patterns decomposed
│ ├── restricted-tables.md # Client data restrictions, audit
│ │ # schema rules
│ ├── gotchas.md # is_deleted filter, draft forecasts,
│ │ # timezone handling, null semantics
│ └── methodology.md
├── assets/
│ ├── schema_metadata.json # Machine-readable schema (87 tables,
│ │ # ~1,200 columns, all FK relationships)
│ ├── unit_map.json # Commodity → price unit mapping
│ ├── crop_year_map.json # Commodity → crop year start month
│ ├── fiscal_calendar.json # FY mapping (FY2026 = Apr 2025–Mar 2026)
│ ├── restricted_columns.json # Columns that require redaction
│ ├── query_templates.json # Parameterized top-50 queries
│ └── sql_blocklist.json # Prohibited SQL keywords/patterns
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (AGDB_READ_DSN read from env, read-only enforced,
client data redacted, audit logging enabled)
Installed at: ~/.agents/skills/agdb-query-assistant-skill
Shared to: github.com/acme-trading/agdb-query-assistant-skill
--- A non-technical analyst asks their first question ---
Analyst (no SQL experience): /agdb-query-assistant-skill What was our total soybean trading volume last month?
Copilot (loading agdb-query-assistant-skill):
Loading schema context for agdb...
I'll query the trading.executions table for soybean trades in
February 2026. A few things I need to account for:
- "Soybeans" maps to instrument_group = 'soybeans' in
reference.instruments (includes CBOT soybeans, soybean meal,
soybean oil). Did you mean just soybeans, or the whole complex?
- "Volume" could mean: number of contracts (trade_qty), notional
value (trade_qty × price × multiplier), or metric tonnes
(trade_qty × contract_size_mt)
- "Last month" = February 2026 (Feb 1–28)
I'll assume you mean the soybeans complex (beans + meal + oil),
measured in contracts, for February 2026. Let me know if you
meant something different.
Here's the query I'd run:
┌─────────────────────────────────────────────────────────┐
│ SELECT │
│ i.instrument_name, │
│ COUNT(*) AS num_trades, │
│ SUM(e.trade_qty) AS total_contracts, │
│ SUM(e.trade_qty * i.contract_size_mt) AS total_mt │
│ FROM trading.executions e │
│ JOIN reference.instruments i │
│ ON e.instrument_id = i.instrument_id │
│ WHERE i.instrument_group = 'soybeans' │
│ AND e.trade_date >= '2026-02-01' │
│ AND e.trade_date < '2026-03-01' │
│ AND e.is_deleted = FALSE │
│ GROUP BY i.instrument_name │
│ ORDER BY total_contracts DESC; │
└─────────────────────────────────────────────────────────┘
PLAIN ENGLISH: "Find all soybean complex trades (soybeans, meal, oil)
executed in February 2026 that haven't been deleted. Count the number
of trades and sum the contracts and metric tonnes, broken down by
specific instrument."
SAFETY CHECK: ✓ Read-only (SELECT only)
SAFETY CHECK: ✓ No client data accessed
SAFETY CHECK: ✓ is_deleted filter applied
SAFETY CHECK: ✓ Date range bounded (won't scan full history)
Run this query? [Yes / Modify / Cancel]
Analyst: Yes
Copilot:
Running query... (0.3 seconds, 4 rows returned)
SOYBEAN COMPLEX TRADING VOLUME — February 2026
| Instrument | Trades | Contracts | Metric Tonnes |
|-------------------|--------|-----------|---------------|
| CBOT Soybeans | 342 | 18,450 | 2,518,418 |
| CBOT Soybean Meal | 198 | 9,200 | 920,000 |
| CBOT Soybean Oil | 156 | 7,800 | 424,322 |
| DCE Soybeans No.1 | 28 | 1,400 | 14,000 |
| TOTAL | 724 | 36,850 | 3,876,740 |
Notes:
- Metric tonnes are calculated from contract size (CBOT soybeans =
136.08 MT/contract, CBOT meal = 100 ST ≈ 90.7 MT, CBOT oil =
60,000 lbs ≈ 27.2 MT per contract, DCE = 10 MT/contract)
- This includes both buy and sell sides. Our NET volume (buys minus
sells) would require a different query — let me know if you want
that instead
- DCE soybeans volume is low — that's normal, we rarely trade
Dalian directly
Query logged to audit/query-log-2026-03-04.csv
--- The analyst digs deeper with a follow-up ---
Analyst: /agdb-query-assistant-skill How does that compare to the same month last year? And show me the trend for the last 12 months.
Copilot (loading agdb-query-assistant-skill):
Good follow-up. I'll expand the date range to Mar 2025 – Feb 2026
(12 months) and include Feb 2025 for the year-over-year comparison.
┌─────────────────────────────────────────────────────────┐
│ SELECT │
│ DATE_TRUNC('month', e.trade_date) AS month, │
│ SUM(e.trade_qty) AS total_contracts, │
│ SUM(e.trade_qty * i.contract_size_mt) AS total_mt, │
│ COUNT(*) AS num_trades │
│ FROM trading.executions e │
│ JOIN reference.instruments i │
│ ON e.instrument_id = i.instrument_id │
│ WHERE i.instrument_group = 'soybeans' │
│ AND e.trade_date >= '2025-02-01' │
│ AND e.trade_date < '2026-03-01' │
│ AND e.is_deleted = FALSE │
│ GROUP BY DATE_TRUNC('month', e.trade_date) │
│ ORDER BY month; │
└─────────────────────────────────────────────────────────┘
PLAIN ENGLISH: "Sum soybean complex contracts by month for the last
13 months (Feb 2025 through Feb 2026) to show the trend and enable
a year-over-year comparison."
Run this query? [Yes / Modify / Cancel]
Analyst: Yes
Copilot:
Running query... (0.8 seconds, 13 rows returned)
SOYBEAN COMPLEX — MONTHLY TRADING VOLUME (contracts)
| Month | Contracts | vs Prev Month | Trades |
|----------|-----------|---------------|--------|
| Feb 2025 | 31,200 | | 612 |
| Mar 2025 | 34,800 | +11.5% | 688 |
| Apr 2025 | 29,400 | -15.5% | 571 |
| May 2025 | 33,100 | +12.6% | 649 |
| Jun 2025 | 38,200 | +15.4% | 741 |
| Jul 2025 | 42,500 | +11.3% | 822 |
| Aug 2025 | 35,600 | -16.2% | 694 |
| Sep 2025 | 30,200 | -15.2% | 589 |
| Oct 2025 | 28,800 | -4.6% | 562 |
| Nov 2025 | 32,400 | +12.5% | 634 |
| Dec 2025 | 26,100 | -19.4% | 508 |
| Jan 2026 | 34,500 | +32.2% | 672 |
| Feb 2026 | 36,850 | +6.8% | 724 |
YEAR-OVER-YEAR: Feb 2026 (36,850) vs Feb 2025 (31,200) = +18.1%
TREND OBSERVATIONS:
- Volume peaked in July 2025 (42,500 contracts) — coincides with
the Argentina drought scare that drove CBOT to $13.40
- December 2025 was the low point (26,100) — typical year-end
position flattening before FY close (our fiscal year ends March 31)
- January–February 2026 rebound (+32% and +7%) likely driven by the
current Argentina drought driving renewed speculative activity
- YoY growth of 18% suggests the desk is more active this year,
possibly due to higher volatility creating more trading opportunities
[Chart generated: reports/soy-volume-trend-12m.png]
--- A more experienced analyst writes a complex question ---
Senior Analyst: /agdb-query-assistant-skill I need to see our net soybean position by trader, broken down by contract month, as of close of business yesterday. Include the average entry price and the mark-to-market P&L using yesterday's settlement. I need this for the weekly risk meeting.
Copilot (loading agdb-query-assistant-skill):
This requires joining 3 tables: trading.daily_positions (net position
by trader and instrument), reference.instruments (contract details),
and market.settlement_prices (yesterday's marks). The P&L calculation
uses the firm's convention: (settlement_price - avg_entry_price) ×
net_qty × contract_multiplier, with the sign convention that positive
= profit on longs, negative = loss on longs.
Important conventions:
- Prices in trading.daily_positions.avg_entry_price are in CENTS per
bushel (firm convention for grains). Settlement prices in
market.settlement_prices are also in cents per bushel.
- The P&L output should be in DOLLARS (not cents). So the formula
includes a /100 conversion.
- CBOT soybean contract multiplier = 5,000 bushels
- I need to handle both outright and spread positions. The
daily_positions table has a position_type column ('outright' or
'spread') — I'll include both but flag them.
┌─────────────────────────────────────────────────────────┐
│ SELECT │
│ p.trader_name, │
│ i.instrument_name, │
│ i.contract_month, │
│ p.position_type, │
│ p.net_qty AS net_contracts, │
│ ROUND(p.avg_entry_price / 100.0, 4) AS avg_entry_usd,│
│ ROUND(s.settlement_price / 100.0, 4) AS settle_usd, │
│ ROUND( │
│ (s.settlement_price - p.avg_entry_price) │
│ * p.net_qty * i.contract_multiplier │
│ / 100.0, 2 │
│ ) AS mtm_pnl_usd │
│ FROM trading.daily_positions p │
│ JOIN reference.instruments i │
│ ON p.instrument_id = i.instrument_id │
│ JOIN market.settlement_prices s │
│ ON p.instrument_id = s.instrument_id │
│ AND s.price_date = '2026-03-03' │
│ WHERE i.instrument_group = 'soybeans' │
│ AND p.position_date = '2026-03-03' │
│ AND p.is_deleted = FALSE │
│ AND p.net_qty != 0 │
│ ORDER BY p.trader_name, i.contract_month; │
└─────────────────────────────────────────────────────────┘
PLAIN ENGLISH: "For each trader, show their net soybean position
by contract month as of March 3, 2026. Convert prices from cents
to dollars. Calculate mark-to-market P&L by comparing each trader's
average entry price to yesterday's settlement, multiplied by their
net contracts and the contract multiplier (5,000 bushels). Exclude
flat positions (net_qty = 0) and deleted records."
SAFETY CHECK: ✓ Read-only
SAFETY CHECK: ✓ No client data
SAFETY CHECK: ✓ is_deleted filtered
SAFETY CHECK: ✓ Single date (no full-table scan)
Run this query? [Yes / Modify / Cancel]
Senior Analyst: Yes
Copilot:
Running query... (0.4 seconds, 18 rows returned)
NET SOYBEAN POSITION BY TRADER — COB March 3, 2026
| Trader | Contract | Type | Net Lots | Avg Entry | Settle | MTM P&L ($) |
|--------------|------------|----------|----------|-----------|---------|----------------|
| Chen, David | May-26 | outright | +340 | $10.8200 | $10.9450| +$212,500.00 |
| Chen, David | Jul-26 | outright | +180 | $10.9600 | $11.0800| +$108,000.00 |
| Chen, David | May/Jul | spread | -120 | -$0.1400 | -$0.1350| +$3,000.00 |
| Lopez, Ana | May-26 | outright | -200 | $11.0400 | $10.9450| +$95,000.00 |
| Lopez, Ana | Nov-26 | outright | +150 | $10.4200 | $10.5600| +$105,000.00 |
| Patel, Raj | May-26 | outright | +420 | $10.7800 | $10.9450| +$351,750.00 |
| Patel, Raj | Jul-26 | outright | +280 | $10.8400 | $11.0800| +$336,000.00 |
| Patel, Raj | May/Jul | spread | +200 | -$0.0600 | -$0.1350| -$75,000.00 |
| ... | ... | ... | ... | ... | ... | ... |
DESK SUMMARY:
| Trader | Net Outrights | Gross Lots | Total MTM P&L |
|--------------|---------------|------------|----------------|
| Chen, David | +400 | 640 | +$323,500 |
| Lopez, Ana | -50 | 350 | +$200,000 |
| Patel, Raj | +500 | 900 | +$612,750 |
| DESK TOTAL | +850 | 1,890 | +$1,136,250 |
NOTES FOR YOUR RISK MEETING:
- Desk is net long 850 soybean contracts (~115,830 MT). This is
within the 1,000-contract desk limit per the risk policy
- Patel has the largest position (500 net lots, $613K MTM). His
May/Jul spread is underwater (-$75K) while outrights are up big
- Lopez is the only trader net short (-50 lots). Her short May
position is profitable — she sold near the high
- If March WASDE (tomorrow) surprises bearish, the desk's +850 net
long is exposed. A $0.20/bu decline = -$850K to the desk P&L
--- A brand-new hire who has never seen the database ---
New Analyst (first week): /agdb-query-assistant-skill I just joined the team. I'm supposed to update the weekly S&D balance sheet but I don't know where the data lives. Where are the production, consumption, and trade numbers? And how are they organized?
Copilot (loading agdb-query-assistant-skill):
Welcome aboard! The S&D data lives in the research.* schema. Let me
walk you through the tables you'll need for the weekly balance sheet.
YOUR KEY TABLES:
1. research.sd_balances — The main S&D table
This is where the team's published balance sheets live. One row
per commodity × country × crop year × balance item × forecast date.
Key columns:
- commodity (e.g. 'soybeans', 'corn', 'wheat')
- country (ISO 3166-1 alpha-2: 'US', 'BR', 'AR', 'CN')
- crop_year (e.g. '2025/26' — note: slash format, not dash)
- item (e.g. 'production', 'crush', 'exports', 'imports',
'feed_use', 'ending_stocks', 'beginning_stocks')
- value_mt (metric tonnes — ALL values are in MT, never bushels)
- forecast_date (date the estimate was published internally)
- status ('published' or 'draft' — always filter for
'published' unless James tells you otherwise)
- analyst_id (who created this estimate)
2. research.sd_history — Historical revisions
Every time someone updates a balance sheet number, the old value
is preserved here. Useful for tracking how your team's estimates
evolved over time (what did we think in January vs what we think
now).
3. research.model_outputs — The quantitative model results
The quant team runs regression models for yield, demand, etc.
Their outputs land here. The analysts then review and adjust
these before publishing to sd_balances.
4. reference.crop_years — Crop year calendar
Maps crop_year strings to actual date ranges by commodity.
Critical because '2025/26' means different dates for corn
(Sep 1, 2025 – Aug 31, 2026) vs wheat (Jun 1, 2025 – May 31, 2026).
THE WEEKLY BALANCE SHEET WORKFLOW:
Your weekly task is to:
1. Pull the LATEST published balance for each commodity
2. Compare to the PREVIOUS week's balance
3. Note what changed and why
4. Publish in the weekly report
Here's the query to get the latest US soybeans balance sheet:
┌─────────────────────────────────────────────────────────┐
│ SELECT │
│ b.item, │
│ ROUND(b.value_mt / 1000000.0, 2) AS value_mmt, │
│ b.forecast_date, │
│ a.analyst_name │
│ FROM research.sd_balances b │
│ JOIN reference.analysts a │
│ ON b.analyst_id = a.analyst_id │
│ WHERE b.commodity = 'soybeans' │
│ AND b.country = 'US' │
│ AND b.crop_year = '2025/26' │
│ AND b.status = 'published' │
│ AND b.forecast_date = ( │
│ SELECT MAX(forecast_date) │
│ FROM research.sd_balances │
│ WHERE commodity = 'soybeans' │
│ AND country = 'US' │
│ AND crop_year = '2025/26' │
│ AND status = 'published' │
│ ) │
│ ORDER BY │
│ CASE b.item │
│ WHEN 'beginning_stocks' THEN 1 │
│ WHEN 'production' THEN 2 │
│ WHEN 'imports' THEN 3 │
│ WHEN 'total_supply' THEN 4 │
│ WHEN 'crush' THEN 5 │
│ WHEN 'exports' THEN 6 │
│ WHEN 'feed_use' THEN 7 │
│ WHEN 'residual' THEN 8 │
│ WHEN 'total_use' THEN 9 │
│ WHEN 'ending_stocks' THEN 10 │
│ END; │
└─────────────────────────────────────────────────────────┘
PLAIN ENGLISH: "Get the most recently published US soybeans 2025/26
balance sheet, with each line item in million metric tonnes, ordered
in standard S&D format (supply items first, then demand, then stocks)."
Run this query? [Yes / Modify / Cancel]
New Analyst: Yes
Copilot:
Running query... (0.2 seconds, 10 rows returned)
US SOYBEANS 2025/26 BALANCE SHEET (latest internal estimate)
Published: March 3, 2026 | Analyst: Maria Santos
| Item | MMT |
|-------------------|---------|
| Beginning Stocks | 9.52 |
| Production | 118.84 |
| Imports | 0.68 |
| TOTAL SUPPLY | 129.04 |
| Crush | 63.50 |
| Exports | 49.67 |
| Feed & Residual | 4.90 |
| Seed & Other | 5.22 |
| TOTAL USE | 123.29 |
| ENDING STOCKS | 5.75 |
This is YOUR TEAM'S estimate, not USDA's. USDA's February WASDE
had ending stocks at 10.34 MMT (281 million bushels). Your team
is MUCH tighter at 5.75 MMT — which is why the desk is net long.
The difference is mainly in exports: your team has 49.67 MMT vs
USDA's 47.90 MMT.
USEFUL COMMANDS FOR YOUR FIRST WEEK:
Ask me:
- "Show me how our estimate changed over the last 4 weeks" (revision
tracking from sd_history)
- "Compare our balance to USDA" (if USDA data is in market.external_sd)
- "What's the Brazil balance sheet?" (same query, country = 'BR')
- "Who last updated the corn balance?" (analyst_id + forecast_date)
- "Show me all commodities we cover" (distinct commodities in
sd_balances)
I'll generate the SQL, explain it, and run it — you don't need to
learn SQL. But I'll show you every query so you start to recognize
the patterns. Most analysts pick up enough SQL to modify queries
within 2-3 weeks of using this skill.
--- An analyst asks something the skill should refuse ---
Analyst: /agdb-query-assistant-skill Show me the full client list with their AUM and contact details. I need to send out the weekly report.
Copilot (loading agdb-query-assistant-skill):
⛔ RESTRICTED DATA REQUEST
The clients.accounts table contains personally identifiable
information (name, email, phone, address) and sensitive financial
data (AUM, portfolio details) that are classified as RESTRICTED
under the firm's data governance policy.
Your read-only database role can see:
- client_id (anonymized identifier)
- region (e.g., 'APAC', 'EMEA', 'Americas')
- segment (e.g., 'institutional', 'corporate', 'retail')
For client names, contact details, or AUM data, you need to:
1. Contact the Sales/CRM team — they manage the distribution list
2. Use the firm's CRM system (Salesforce) for contact details
3. If you need client data for analytical purposes, request
compliance approval through the data governance portal
I CANNOT run a query that exposes client PII, even with your
read-only credentials. This is a firm policy, not a technical
limitation — the columns exist in the database but the skill is
configured to redact them.
WHAT I CAN DO: If you need aggregate client metrics for research
purposes (e.g., "how many institutional clients are in APAC?"),
I can query that without exposing individual records:
┌─────────────────────────────────────────────────────────┐
│ SELECT │
│ region, │
│ segment, │
│ COUNT(*) AS client_count │
│ FROM clients.accounts │
│ WHERE is_active = TRUE │
│ AND is_deleted = FALSE │
│ GROUP BY region, segment │
│ ORDER BY region, segment; │
└─────────────────────────────────────────────────────────┘
Would this help, or do you need the full contact list from Sales?
--- An analyst asks a question that requires business logic ---
Analyst: /agdb-query-assistant-skill What's our soybean crush margin right now? And how does it compare to the 5-year average for this time of year?
Copilot (loading agdb-query-assistant-skill):
Crush margin is a CALCULATED value, not stored directly. It requires
the firm's specific formula (from the schema docs, section 14.3):
Board Crush Margin ($/bu) =
(Soybean Meal price × 0.022) + (Soybean Oil price × 11.0)
- Soybean price
Where:
- Soybean price: $/bu from market.settlement_prices (CBOT S 1)
- Soybean Meal price: $/short ton from market.settlement_prices (CBOT SM 1)
- Soybean Oil price: ¢/lb from market.settlement_prices (CBOT BO 1)
- The 0.022 converts $/short ton to $/bu for meal (yield: 44 lbs
meal per bushel, 1 short ton = 2000 lbs, so 1 bu → 0.022 tons)
- The 11.0 converts ¢/lb to $/bu for oil (yield: 11 lbs oil per
bushel, price in cents → 11 lbs × price / 100)
⚠️ IMPORTANT: The prices in our database are stored in DIFFERENT
units per commodity:
- Soybeans: cents/bu → divide by 100 for $/bu
- Meal: dollars/short ton (already in $)
- Oil: cents/lb → used directly in the formula (the 11.0 factor
handles the conversion)
┌─────────────────────────────────────────────────────────┐
│ WITH latest AS ( │
│ SELECT │
│ MAX(price_date) AS pd │
│ FROM market.settlement_prices │
│ WHERE price_date <= CURRENT_DATE │
│ ), │
│ prices AS ( │
│ SELECT │
│ i.instrument_code, │
│ s.settlement_price, │
│ s.price_date │
│ FROM market.settlement_prices s │
│ JOIN reference.instruments i │
│ ON s.instrument_id = i.instrument_id │
│ CROSS JOIN latest l │
│ WHERE s.price_date = l.pd │
│ AND i.instrument_code IN ('S_1', 'SM_1', 'BO_1') │
│ ), │
│ margin AS ( │
│ SELECT │
│ p_s.price_date, │
│ ROUND(p_s.settlement_price / 100.0, 4) AS soy_usd, │
│ ROUND(p_sm.settlement_price, 2) AS meal_usd_ton, │
│ ROUND(p_bo.settlement_price, 4) AS oil_cents_lb, │
│ ROUND( │
│ (p_sm.settlement_price * 0.022) │
│ + (p_bo.settlement_price * 11.0 / 100.0) │
│ - (p_s.settlement_price / 100.0) │
│ , 4) AS crush_margin_usd │
│ FROM prices p_s │
│ JOIN prices p_sm ON p_sm.instrument_code = 'SM_1' │
│ JOIN prices p_bo ON p_bo.instrument_code = 'BO_1' │
│ WHERE p_s.instrument_code = 'S_1' │
│ ) │
│ SELECT * FROM margin; │
└─────────────────────────────────────────────────────────┘
PLAIN ENGLISH: "Get yesterday's settlement prices for soybeans,
soybean meal, and soybean oil. Calculate the board crush margin
using the firm's standard formula. Convert all prices to consistent
units (dollars per bushel for the final margin)."
Run this query? [Yes / Modify / Cancel]
Analyst: Yes, and also the 5-year average
Copilot:
Running current margin query... (0.2 seconds)
Running 5-year seasonal average... (1.4 seconds)
SOYBEAN CRUSH MARGIN — March 3, 2026
CURRENT:
| Component | Price | Contribution |
|---------------|-------------------|---------------|
| Soybeans (S1) | $10.9450/bu | -$10.9450 |
| Meal (SM1) | $312.40/short ton | +$6.8728 |
| Oil (BO1) | 45.82¢/lb | +$5.0402 |
| CRUSH MARGIN | | +$0.9680/bu |
5-YEAR SEASONAL COMPARISON (same calendar week):
| Year | Crush Margin ($/bu) | Notes |
|------|---------------------|--------------------------------|
| 2022 | $2.1240 | Post-COVID demand boom |
| 2023 | $1.5680 | Still elevated |
| 2024 | $1.0420 | Normalizing |
| 2025 | $0.8860 | Below average |
| 2026 | $0.9680 | Current |
| 5yr Avg | $1.3176 | |
ASSESSMENT:
Current crush margin of $0.97/bu is 27% BELOW the 5-year average
of $1.32/bu for early March. The margin has been below average since
mid-2024, driven by weak soybean oil demand (RD mandate uncertainty)
and adequate meal supplies.
For context: crush margins below $0.80/bu are considered "crush
discouraging" — processors start reducing run rates. At $0.97 we're
above that threshold but not by much. If margins compress further,
expect crush pace to slow in Q2, which is bullish for meal and
bearish for bean oil.
This is the kind of answer that would have taken the data team
2 days to produce. The business logic (the crush formula, the unit
conversions, the seasonal comparison) is encoded in the skill. You
asked in plain English and got the answer in 3 seconds.
=============================================================
WHY THIS SKILL WORKS
=============================================================
The internal database skill solves three problems simultaneously:
1. THE BOTTLENECK PROBLEM
Every firm has 2-3 people who know the database well. They're the
bottleneck for every analyst's data request. When the senior data
engineer goes on vacation, the whole team slows down. The skill
distributes database knowledge to everyone with read access.
WITHOUT THE SKILL:
- Analyst sends Slack message to data team: "Can you pull...?"
- Data team triages: 1-3 day wait (they have 40 requests in queue)
- Data team delivers: sometimes wrong interpretation
- Analyst requests revision: another 1-2 days
- Total: 2-5 business days for one data pull
WITH THE SKILL:
- Analyst asks in plain English: 10 seconds
- Skill generates, explains, and runs query: 30 seconds
- If wrong interpretation, analyst asks again: 30 seconds
- Total: under 2 minutes
2. THE ONBOARDING PROBLEM
A new hire with read-only database access but no SQL knowledge is
essentially locked out of the firm's most valuable asset — 15 years
of proprietary data. The skill turns the 142-page schema document
into an interactive guide. The new analyst from the simulation was
productive on DAY ONE, pulling balance sheets and understanding
table relationships without a 3-week SQL training course.
3. THE INSTITUTIONAL KNOWLEDGE PROBLEM
The business logic (crush margin formula, fiscal year convention,
crop year definitions, price unit conversions) exists in three
places: the schema docs (which nobody reads), senior analysts' heads
(which leave when they do), and the data team's query history (which
nobody outside the team can access). The skill codifies ALL of this
into reusable, version-controlled reference files. When the firm
changes its fiscal year convention, you update one JSON file.
SAFETY IS THE FEATURE, NOT THE CONSTRAINT:
The skill's guardrails (read-only validation, client data redaction,
query explanation before execution, audit logging) aren't limitations
— they're what make it trustworthy enough to give to non-technical
analysts. The data team WANTS analysts to self-serve, but they don't
want someone accidentally running SELECT * on a 500M-row table or
pulling client PII into an email attachment. The skill makes self-
service safe.
#############################################################
#############################################################
## ##
## ENTERPRISE ADOPTION SCENARIO: ##
## "THE DOG LOOKING AT THE CASTLE" ##
## ##
## How a non-technical agriculture commodities research ##
## team goes from tool paralysis to daily productivity ##
## using agent-skill-creator as the on-ramp ##
## ##
#############################################################
#############################################################
CONTEXT:
GlobalAgri Capital is a mid-large commodity trading house with a
25-person agriculture research division, subdivided into three desks:
AG MODELLING (8 people)
Led by Dr. Carla Ribeiro. Econometricians, quant analysts, and
statisticians. They build yield models, demand elasticity models,
and price forecasting regressions. Most have PhDs. They live in
Excel, MATLAB, and some R. A few can write Python. None use Git.
Their "version control" is saving files as model_v3_final_FINAL2.xlsx
SUPPLY & DEMAND (9 people)
Led by Henrik Johansson. Fundamental analysts who maintain global
balance sheets for grains, oilseeds, sugar, coffee, cotton. They
track USDA reports, foreign attaché data, harvest progress, and
trade flows. Most are experienced commodity professionals (10-20
years) who work in Excel, Bloomberg Terminal, and email. Zero
programming. They get data by asking the data team or downloading
CSVs from USDA websites.
PRICE ASSESSMENT (8 people)
Led by Tomoko Watanabe. They produce the firm's daily price
assessments and forward curves for internal trading desks and
external clients. They pull settlement prices, broker indications,
and physical market bids/offers. Heavy Bloomberg and Refinitiv
users. Some basic VBA macros. No Python, no SQL, no Git.
WHAT IT PROVISIONED:
Six months ago, the CTO's office rolled out an "AI-enabled developer
toolkit" to the entire research division. Each analyst received:
✓ VS Code (installed on their laptop)
✓ GitHub Copilot license (Enterprise, via VS Code extension)
✓ Copilot CLI (installed, authenticated via corporate SSO)
✓ Enterprise GitLab access (gitlab.globalagri.com)
✓ Databricks workspace (databricks.globalagri.com)
✓ Read-only access to the firm's data lake (agri_lake.*)
What IT also provided:
- A 90-minute "Introduction to AI Coding Tools" webinar (recorded)
- A 40-page PDF: "Getting Started with Your AI Developer Toolkit"
- A Confluence page: "Databricks Quick Start Guide"
- An internal Slack channel: #ai-tools-support (3 IT staff monitor it)
WHAT ACTUALLY HAPPENED:
Six months later, adoption metrics from the CTO dashboard:
| Tool | Active Users (last 30 days) | Of 25 analysts |
|----------------|----------------------------:|----------------|
| VS Code | 4 | 16% |
| GitHub Copilot | 2 | 8% |
| Copilot CLI | 0 | 0% |
| GitLab | 1 (accidental login) | 4% |
| Databricks | 3 | 12% |
The CTO is frustrated. The licenses cost $180K/year. The 90-minute
webinar had 40% attendance. Nobody finished the 40-page PDF. The
Slack channel has 6 messages, 4 of which are "how do I log in?"
The problem isn't the tools. The problem is that nobody on the
research team knows WHY they would use these tools, HOW to start,
or WHAT their first task should be. They have jobs to do — balance
sheets, price assessments, model runs — and learning a code editor
feels like a distraction from real work.
They are, as one S&D analyst put it in the hallway, "like a dog
looking at a castle."
=============================================================
PHASE 1: THE CHAMPION DISCOVERS AGENT-SKILL-CREATOR
=============================================================
Every enterprise adoption starts with one person. In this case it's
Luís Ferreira, a 28-year-old S&D analyst (3 years at the firm) who
is slightly more tech-curious than his colleagues. He attended the
webinar. He opened VS Code once. He closed it after 10 minutes
because he didn't know what to do with it. Then he saw a LinkedIn
post about agent-skill-creator and thought: "maybe this is the
missing piece."
Luís opens VS Code for the second time in six months. He has GitHub
Copilot active (the extension was pre-installed by IT). He opens
Copilot Chat (Agent mode) — it's the sidebar on the right with the
sparkle icon. He types:
Luís: I don't really know what I'm doing here. I'm a commodity S&D analyst, not a developer. My company gave me VS Code and Copilot but I have no idea how to use them for my actual work. I maintain global soybean balance sheets in Excel. Is there anything useful I can actually do here?
Copilot:
You're in the right place. VS Code + Copilot isn't just for
developers — it's for anyone who works with data, documents, or
repetitive processes.
Here's what you can do RIGHT NOW with zero coding experience:
1. Ask me to analyze files — drop an Excel, CSV, or PDF into VS
Code and ask me questions about it
2. Ask me to write formulas — describe what you need and I'll
write the Excel formula or Python code
3. Ask me to automate repetitive tasks — if you do the same thing
every week, I can help you build a script
4. Ask me to query databases — if you have database access, describe
what you need in plain English
What's the most tedious part of your weekly workflow?
Luís: Every Monday I download the latest USDA Export Inspections CSV from the USDA FAS website, then I manually copy the soybean rows into my master Excel tracker, calculate the year-over-year change, compare to the weekly pace needed to hit the USDA full-year forecast, and update a summary table that goes into our team's weekly report. It takes about 45 minutes and it's the most boring part of my week.
Copilot:
That's a perfect first automation. Let me help you turn that into
something that takes 30 seconds instead of 45 minutes.
I can write a Python script that:
1. Downloads the latest Export Inspections CSV from USDA FAS
2. Filters for soybeans
3. Calculates YoY change
4. Compares to the pace needed for the full-year forecast
5. Generates a summary table
6. Outputs to Excel (or directly into your tracker format)
But before I write a one-off script, have you heard of agent-
skill-creator? It's a tool that can turn this workflow into a
reusable SKILL — something you or your teammates can invoke with
a single command, every week, forever. Instead of a script you run
once and forget, you'd have a skill that becomes part of your
team's toolkit.
Want me to use agent-skill-creator to build this properly?
Luís: I've heard of it but I don't know how to set it up. I don't even know how to install things in VS Code. Can you walk me through it step by step? Like, assume I know nothing.
Copilot:
Absolutely. Here's what we'll do, step by step. I'll tell you
exactly what to click and type.
STEP 1: Open a terminal in VS Code
Look at the bottom of VS Code. There's a panel area. If you don't
see a terminal, press Ctrl+` (the backtick key, top-left of your
keyboard, next to 1). A terminal panel will appear at the bottom.
It looks like a black or dark box where you can type commands.
That's the terminal. It's like Command Prompt but inside VS Code.
STEP 2: Install agent-skill-creator
In that terminal, paste this single line and press Enter:
curl -fsSL https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.sh | sh
This will download and install agent-skill-creator. It takes about
10 seconds. You'll see some output — that's normal. When it says
"Done" you're good.
STEP 3: Verify it works
In Copilot Chat (this panel where we're talking), type:
/agent-skill-creator hello
If I respond with information about how to create skills, it's
working.
Try Step 1 now — press Ctrl+` to open the terminal.
Luís: OK, I opened the terminal. It says "luisf@GLOBALAGRI-PC234 ~" and there's a blinking cursor. I pasted the curl command and pressed Enter. It's doing things... it says "Cloning into ~/.agents/skills/agent-skill-creator" and now "Detecting tools: github-copilot... found" and "Creating symlinks..." and "Done! agent-skill-creator is ready."
Copilot:
Perfect — it detected GitHub Copilot automatically and installed
itself. Now let's build your first skill. Tell me about that
Export Inspections workflow in detail.
Luís: /agent-skill-creator Every Monday, I go to apps.fas.usda.gov/export-sales/inspections.htm, download the "Current Marketing Year" CSV for soybeans, and open it in Excel. The CSV has columns: Week Ending, Commodity, Destination, Weekly Inspections (MT), and Cumulative Inspections (MT). I filter for "Soybeans" (it also has corn, wheat, etc.), create a pivot by destination (top 5: China, EU, Mexico, Japan, Egypt), calculate the week-over-week change and YoY change (I keep last year's data in a separate sheet), then calculate "pace" — cumulative inspections divided by USDA's full-year export forecast (currently 49.67 MMT per our internal estimate, though I also compare to USDA's official 47.90 MMT). The pace tells me if we're ahead or behind schedule. I format it into a summary table that Henrik (my boss) pastes into the weekly report. Here's my current Excel tracker: references/export-inspections-tracker.xlsx and here's what the final summary table looks like: references/weekly-summary-format.png
Copilot (loading agent-skill-creator skill):
Reading references/export-inspections-tracker.xlsx...
Reading references/weekly-summary-format.png...
Perfect first skill — it's repetitive, data-driven, well-defined,
and currently takes 45 minutes of manual work. Let me build it.
Implicit requirements:
- USDA FAS Export Inspections: CSV download from
apps.fas.usda.gov, updated every Monday by ~11am ET
- Filter: commodity = 'Soybeans'
- Destinations: group top 5 (China, EU, Mexico, Japan, Egypt),
remainder as "Other"
- YoY comparison: need previous marketing year data (Sep 2024-Aug
2025) for the same-week comparison
- Pace calculation: two versions:
(a) vs internal estimate (49.67 MMT) — for the team's report
(b) vs USDA official (47.90 MMT) — for context
- Marketing year: soybeans = Sep 1 – Aug 31
- Output: formatted summary table matching the screenshot format,
exported to Excel AND as a markdown table for the weekly report
- No API key needed — USDA FAS data is public
- Python dependencies: pandas, openpyxl (for Excel), requests
Building...
export-inspections-skill/
├── SKILL.md
├── scripts/
│ ├── usda_downloader.py # Fetch latest CSV from USDA FAS
│ ├── inspection_parser.py # Filter soybeans, pivot by dest
│ ├── pace_calculator.py # Cumulative vs forecast pace
│ ├── yoy_comparator.py # Same-week previous MY comparison
│ ├── summary_builder.py # Format into Henrik's table layout
│ └── excel_exporter.py # Write to .xlsx matching tracker format
├── references/
│ ├── usda-fas-fields.md # CSV column definitions
│ ├── marketing-year.md # Sep 1 - Aug 31 calendar
│ ├── destination-groups.md # Top 5 + Other grouping
│ └── methodology.md
├── assets/
│ ├── forecast_targets.json # Internal (49.67) and USDA (47.90)
│ ├── destination_groups.json # Destination → group mapping
│ └── previous_my_data.csv # 2024/25 MY inspections baseline
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (no credentials needed — public data)
Installed at: ~/.agents/skills/export-inspections-skill
Luís: That was... really fast. Can I use it right now?
Copilot:
Yes. Type this:
Luís: /export-inspections-skill Run the Monday update
Copilot (loading export-inspections-skill):
Downloading latest Export Inspections CSV from USDA FAS...
Filtering for soybeans... 52 weeks of data found (MY 2025/26)
Loading previous year baseline...
Calculating pace and YoY changes...
WEEKLY EXPORT INSPECTIONS SUMMARY — Week Ending Feb 27, 2026
US SOYBEAN EXPORT INSPECTIONS (thousand MT)
| Destination | This Week | Prev Week | WoW Chg | Same Wk LY | YoY Chg |
|-------------|-----------|-----------|----------|------------|----------|
| China | 812 | 748 | +8.6% | 694 | +17.0% |
| EU | 124 | 131 | -5.3% | 118 | +5.1% |
| Mexico | 89 | 76 | +17.1% | 82 | +8.5% |
| Japan | 62 | 58 | +6.9% | 65 | -4.6% |
| Egypt | 48 | 52 | -7.7% | 41 | +17.1% |
| Other | 186 | 172 | +8.1% | 168 | +10.7% |
| TOTAL | 1,321 | 1,237 | +6.8% | 1,168 | +13.1% |
PACE ANALYSIS:
| Metric | Value | Status |
|-----------------------------|----------|-----------------|
| Cumulative inspections | 33.42 MMT| |
| Weeks completed | 26 of 52 | 50.0% |
| vs Internal forecast (49.67)| 67.3% | ✓ AHEAD of pace |
| vs USDA official (47.90) | 69.8% | ✓ AHEAD of pace |
| Needed weekly pace (internal)| 626 KMT | to hit 49.67 |
| Needed weekly pace (USDA) | 558 KMT | to hit 47.90 |
| Actual 4-week avg pace | 1,244 KMT| 2.0x needed (int)|
OBSERVATION: At the current 4-week average pace of 1,244 KMT/week,
full-year inspections would reach 65.7 MMT — far above both
forecasts. However, pace typically slows sharply in Q3 (May-Aug)
as Brazil takes over global supply. The comparison to needed pace
is most meaningful now during the peak US shipping window.
Summary saved to: reports/export-inspections-wk26-2026.xlsx
Markdown table copied to clipboard (paste into weekly report).
Luís: Holy shit. That just saved me 45 minutes. And the markdown table — I can just paste that into the report?
Copilot:
Yes — it's on your clipboard right now. Open the weekly report
and Ctrl+V. The table is already formatted in the layout Henrik
expects (I matched the format from your screenshot).
This will run the same way every Monday. Just type:
/export-inspections-skill Run the Monday update
and you'll have the table in 10 seconds.
Also: if you want to update the forecast targets (when USDA revises
their estimate), tell me and I'll update the config. You don't need
to edit any code.
=============================================================
PHASE 2: THE CHAMPION TELLS ONE COLLEAGUE
=============================================================
Tuesday morning. Luís walks past Ana Morales's desk (S&D team, 12
years experience, covers wheat and corn). She's copy-pasting numbers
from a USDA PDF into her Excel tracker — the same thing she's done
every month for a decade.
Luís: "Hey Ana, you know that Copilot thing IT installed? I made it
do my export inspections summary automatically yesterday. Took 10
seconds instead of 45 minutes."
Ana: "I tried opening VS Code once. I had no idea what I was looking
at. How did you get it to do that?"
Luís: "There's this thing called agent-skill-creator. You install it
once, then you just describe your workflow in plain English and it
builds a tool for you. I can show you at lunch."
At lunch, Luís walks Ana through the same setup: open VS Code,
Ctrl+` for terminal, paste the bootstrap command. Ana's first
question:
Ana (in VS Code Copilot Chat): /agent-skill-creator Every month when USDA releases the WASDE report, I spend about 3 hours manually extracting the corn and wheat numbers from the PDF, comparing them to last month's estimates, calculating the month-over-month changes, flagging any revision larger than 2%, and creating a summary for our trading desk. The PDF is 40 pages and the tables I need are on pages 12-15 (world wheat) and pages 16-19 (world corn). I have the last 24 WASDE PDFs saved in a folder: data/wasde-pdfs/. Here's my current extraction template: references/wasde-extraction-template.xlsx
Copilot (loading agent-skill-creator skill):
Reading references/wasde-extraction-template.xlsx...
Scanning data/wasde-pdfs/ (24 PDFs found, Feb 2024 – Jan 2026)...
This is a PDF table extraction + time-series comparison skill.
The WASDE PDF has notoriously complex table layouts (merged cells,
footnotes, units that change between sections). But since you have
24 months of PDFs, I can validate my extraction against your
manually-verified historical data. Let me build it.
Building...
wasde-extractor-skill/
├── SKILL.md
├── scripts/
│ ├── wasde_downloader.py # Fetch latest WASDE PDF from USDA
│ ├── pdf_table_parser.py # Extract tables from pages 12-19
│ │ # (corn and wheat world S&D)
│ ├── field_mapper.py # Map PDF table cells to structured
│ │ # data (production, consumption,
│ │ # exports, ending stocks by country)
│ ├── revision_tracker.py # MoM changes, flag revisions > 2%
│ ├── historical_builder.py # Parse all 24 PDFs to build
│ │ # revision history database
│ ├── desk_summary.py # Trading desk summary format
│ └── excel_exporter.py # Match Ana's template layout
├── references/
│ ├── wasde-page-map.md # Which tables on which pages
│ ├── table-layouts.md # Column definitions by section
│ ├── revision-thresholds.md # What constitutes a "significant" move
│ └── methodology.md
├── assets/
│ ├── page_ranges.json # Wheat: 12-15, Corn: 16-19
│ ├── field_definitions.json # S&D line items and units
│ └── revision_threshold.json # 2% default, configurable
├── install.sh
└── README.md
Validation: PASSED
Installed at: ~/.agents/skills/wasde-extractor-skill
BONUS: I parsed your 24 historical PDFs and cross-checked against
your Excel tracker. 23 of 24 match perfectly. The February 2025
extract has a discrepancy — your tracker shows Argentina wheat
production at 17.5 MMT but the PDF says 17.0 MMT. Possible manual
entry error? Worth checking.
Ana: It found an error in my manual work? From 13 months ago?
Copilot:
Yes. The historical PDF clearly shows 17.0 MMT for Argentina wheat
production in the February 2025 WASDE. Your tracker has 17.5. The
March 2025 entry is correct (17.0). It looks like a typo in the
February data entry that was accidentally carried forward in your
month-over-month change calculations for that one month.
This is a common benefit of automation — it doesn't make typos.
Going forward, the skill extracts directly from the PDF with no
manual transcription.
Ana: OK I'm sold. But how does this Databricks thing fit in? Henrik keeps saying we should use Databricks but nobody knows what for.
Copilot:
Good question. Right now, this skill downloads PDFs and processes
them locally on your laptop. That works fine for one person.
Databricks becomes useful when:
1. You want the extracted WASDE data stored in a SHARED table that
the whole team can query (not just your Excel file)
2. You want the extraction to run AUTOMATICALLY on WASDE release
day (every ~12th of the month) without you doing anything
3. You want to combine WASDE data with other sources (PSD, trade
data, prices) in one place
We can evolve this skill to write results to Databricks later.
For now, the local version gives you 90% of the value. Don't try
to learn Databricks AND automation at the same time — that's how
people get overwhelmed and quit.
Master the skill locally first. Once it feels natural, we'll
connect it to Databricks. One step at a time.
=============================================================
PHASE 3: THE TEAM LEAD NOTICES
=============================================================
Two weeks later. Henrik Johansson (Head of S&D) notices that Luís's
Monday summary is arriving at 9:15am instead of 11:30am, and Ana's
WASDE extraction was done in 20 minutes instead of 3 hours. He asks
them what changed.
Henrik then opens VS Code himself for the first time. He has a
different kind of problem — he doesn't do the data work himself, but
he manages the team's output and needs to understand the tools to
make decisions about the team's workflow.
Henrik (in VS Code Copilot Chat): I'm the head of the S&D desk. I don't need to build skills myself but I need to understand what's possible. Two of my analysts (Luís and Ana) are using something called agent-skill-creator and it's clearly making them faster. I have 9 people on my team. Each one has a set of repetitive weekly and monthly tasks. I want to understand: what tasks are good candidates for skills, and how do I roll this out to the whole team without it being another failed IT initiative?
Copilot:
Smart approach — starting with strategy before tools. Let me help
you think through this.
SKILL CANDIDATE ASSESSMENT FRAMEWORK:
A workflow is a good skill candidate if it scores 3+ on these:
✓ REPETITIVE: happens weekly, monthly, or on a trigger (report day)
✓ STRUCTURED: has clear inputs, steps, and outputs
✓ DATA-DRIVEN: involves downloading, transforming, or combining data
✓ TIME-CONSUMING: takes 30+ minutes of manual work
✓ ERROR-PRONE: manual copy-paste, unit conversions, formatting
Based on what I know about typical S&D desk workflows, here are the
likely candidates across your team:
HIGH VALUE (build first):
| Task | Who | Frequency | Manual Time | Skill? |
|------------------------------|-----------|-----------|-------------|--------|
| Export Inspections summary | Luís | Weekly | 45 min | ✓ DONE |
| WASDE PDF extraction | Ana | Monthly | 3 hours | ✓ DONE |
| Crop Progress data pull | Multiple | Weekly | 30 min | YES |
| PSD balance sheet update | Multiple | Monthly | 2 hours | YES |
| Attaché report extraction | Regional | Ad hoc | 1-2 hours | YES |
| CFTC COT positioning summary | Luís? | Weekly | 40 min | YES |
| Weekly client report compile | Henrik | Weekly | 2-3 hours | YES |
MEDIUM VALUE (build second):
| Task | Who | Frequency | Manual Time | Skill? |
|------------------------------|-----------|-----------|-------------|--------|
| Brazil CONAB harvest tracker | Regional | Monthly | 1 hour | YES |
| Argentina BAGE estimates | Regional | Bi-weekly | 45 min | YES |
| Statistics Canada pull | Regional | Monthly | 30 min | YES |
| Freight rate tracker | Shipping | Weekly | 30 min | YES |
LOWER VALUE (nice to have):
| Bloomberg chart formatting | All | Daily | 15 min | MAYBE |
| Email summary distributions | Henrik | Weekly | 20 min | MAYBE |
ROLLOUT STRATEGY (avoid the "failed IT initiative" pattern):
DON'T DO THIS:
✗ Send an email saying "everyone must use Copilot skills by March"
✗ Schedule a 2-hour mandatory training session
✗ Assign IT to "deploy skills to the team"
✗ Create a Confluence page with 30 setup instructions
DO THIS INSTEAD:
✓ Week 1-2: Luís and Ana are already using skills. Let them keep
going. They're your proof of concept.
✓ Week 3: In the Monday team meeting, have Luís demo his export
inspections skill live. 2 minutes. Don't explain the technology
— just show the result. The team will see him type one sentence
and get a formatted table in 10 seconds.
✓ Week 3-4: Ask 1-2 more volunteers: "What's the most tedious
part of your week?" Sit with them for 15 minutes. Build their
first skill together (Luís can help).
✓ Week 5-8: As skills get built, they're shared on your team's
GitLab. New analysts can install a colleague's skill in one
command. The Crop Progress skill that one person builds is now
available to all 9 people.
✓ Month 3+: Organic adoption. People who see colleagues finishing
work faster will ask how. Nobody needs to be forced.
THE KEY INSIGHT:
The 90-minute IT webinar failed because it taught the TOOLS
(VS Code, Git, Copilot). People don't care about tools. They care
about: "how do I get my Monday summary done faster?"
agent-skill-creator succeeds because it starts from the WORKFLOW,
not the TOOL. The analyst describes what they do. The skill gets
built. They use it. They never need to learn VS Code features, Git
commands, or Python syntax. The tool becomes invisible.
Henrik: That makes sense. But I have a concern — if everyone builds their own skills, we'll end up with 15 different export trackers that do slightly different things. How do we keep it organized?
Copilot:
Great concern. Here's how to structure it:
TEAM SKILL LIBRARY (on your GitLab):
Create one GitLab group: gitlab.globalagri.com/sd-team/skills/
Inside it, one repository per skill:
sd-team/skills/
├── export-inspections-skill/ ← Luís built this
├── wasde-extractor-skill/ ← Ana built this
├── crop-progress-skill/ ← Next to build
├── psd-balance-updater-skill/ ← Next to build
├── cftc-positioning-skill/ ← Next to build
└── weekly-report-compiler-skill/ ← Henrik's, calls others
RULES:
1. ONE skill per distinct workflow (no duplicates)
2. The person who does the task builds the skill (with help)
3. Skills are reviewed by the team before "official" adoption
4. Henrik (you) approves which skills go into the team library
5. Everyone installs from the team library, not personal repos
This is where GitLab finally makes sense to your team. Not as a
"code repository" (which sounds scary) but as a "shared skill
library" (which sounds useful). Your analysts don't need to learn
Git commands — they install skills with one command:
/agent-skill-creator install gitlab.globalagri.com/sd-team/skills/crop-progress-skill
GitLab becomes the team's knowledge base, not a developer tool.
=============================================================
PHASE 4: AG MODELLING DESK — "I HAVE MATLAB, WHY DO I NEED THIS?"
=============================================================
Dr. Carla Ribeiro is skeptical. Her Ag Modelling team has PhDs in
econometrics. They already code — in MATLAB, R, and some Python.
They don't need Copilot to help them write for loops. But she has a
different problem: nobody can reproduce her team's work.
Carla walks into Henrik's Monday meeting late. She hears Luís demo
his export inspections skill. She's unimpressed — "that's just a
CSV download script." But afterwards she asks Luís a question:
Carla: "Can that skill thing work for something more complex? My
team's yield model is a 4,000-line MATLAB script that takes 14 input
files, runs 300 regressions, and produces a 50-page PDF. Only two
people on my team understand the full pipeline. If either of them
leaves, we're in serious trouble. Could I turn that into a 'skill'?"
Luís: "I think so. Talk to Copilot about it."
Carla (in VS Code Copilot Chat): /agent-skill-creator I run the Ag Modelling desk. We have a yield forecasting model built in MATLAB that's been evolving for 6 years. It's 4,200 lines of MATLAB code across 23 .m files. It ingests weather data (temperature, precipitation, soil moisture from 14 state-level stations), USDA planting progress, historical yield data from NASS, and satellite NDVI from our Databricks lake. It runs 300+ regressions (one per crop reporting district) and produces yield estimates for corn and soybeans at district, state, and national level. The output is a PDF with maps, charts, and a summary table. The problem: only 2 of my 8 people fully understand the pipeline. The code has no documentation, no comments, file naming is cryptic (run_v3b_final.m, carlos_fix_sept2024.m), and it breaks every time USDA changes their CSV format. I don't want to rewrite the model — it works and it's validated against 40 years of data. I want to WRAP it in something that makes it understandable, runnable, and maintainable by the whole team. Is that something a skill can do? The MATLAB code is here: models/yield-forecaster/ and the input data is on Databricks: agri_lake.weather.station_daily, agri_lake.usda.planting_progress, agri_lake.satellite.ndvi_weekly
Copilot (loading agent-skill-creator skill):
Reading models/yield-forecaster/ (23 .m files, 4,200 lines)...
Analyzing file dependencies and execution order...
Connecting to Databricks to inspect table schemas...
This is a MODEL WRAPPING problem, not a model building problem.
The MATLAB code works — don't touch the math. What's missing is:
(1) documentation of what each file does, (2) a clear execution
pipeline (what runs in what order), (3) input validation (detect
when USDA changes their CSV format BEFORE it breaks the model),
(4) a single entry point so anyone can run it, and (5) connection
to Databricks so inputs come from the shared lake instead of 14
CSV files on someone's desktop.
From analyzing your 23 .m files, here's the execution graph I
reconstructed:
STAGE 1 — DATA INGESTION (5 files):
load_weather_data.m ← reads 14 CSVs from data/weather/
load_planting_progress.m ← reads USDA planting CSV
load_historical_yields.m ← reads NASS yield CSV
load_ndvi.m ← reads satellite NDVI CSV
merge_inputs.m ← joins all inputs by CRD code + date
STAGE 2 — PREPROCESSING (4 files):
calc_gdd.m ← growing degree days from temperature
calc_drought_index.m ← custom drought stress metric
create_lagged_vars.m ← 1-4 week lags for all weather vars
normalize_features.m ← z-score normalization
STAGE 3 — MODEL EXECUTION (8 files):
run_v3b_final.m ← MAIN regression loop (300 CRDs)
carlos_fix_sept2024.m ← hotfix for Iowa CRDs (Carlos fixed
a coefficient sign error in Sep 2024)
handle_missing_crds.m ← fallback for CRDs with < 20yr history
state_aggregator.m ← CRD → state weighted average
national_aggregator.m ← state → national weighted average
confidence_intervals.m ← bootstrap CIs for each estimate
residual_diagnostics.m ← model fit statistics
cross_validation.m ← leave-one-out CV (runs on demand)
STAGE 4 — OUTPUT (6 files):
generate_maps.m ← choropleth maps by CRD
generate_charts.m ← time series, scatter, residual plots
generate_summary_table.m ← the headline numbers table
format_pdf.m ← compile everything into PDF
export_to_excel.m ← raw numbers for other teams
email_distribution.m ← send PDF to distribution list
NOTE: carlos_fix_sept2024.m is called inside run_v3b_final.m at
line 847 with a comment "% CARLOS FIX - DO NOT REMOVE". This is a
targeted coefficient correction for 12 Iowa CRDs where the original
regression had a sign error on the drought interaction term. It's
valid — the fix improves out-of-sample R² from 0.71 to 0.84 for
those districts. But it should be documented properly, not hidden
as a hotfix with a scary comment.
Building the WRAPPER skill (not replacing the MATLAB code):
yield-model-skill/
├── SKILL.md
├── scripts/
│ ├── pipeline_runner.py # Orchestrates the 4-stage MATLAB
│ │ # pipeline from Python. Calls
│ │ # MATLAB via subprocess or MATLAB
│ │ # Engine API for Python
│ ├── databricks_ingestor.py # Pull inputs from Databricks tables
│ │ # instead of desktop CSVs. Writes
│ │ # to the same format MATLAB expects
│ ├── input_validator.py # Check all 14 inputs exist, have
│ │ # expected columns, no nulls in
│ │ # critical fields. CATCH format
│ │ # changes before MATLAB crashes
│ ├── format_change_detector.py # Compare incoming CSV headers to
│ │ # expected schema. Alert if USDA
│ │ # renames/adds/removes columns
│ ├── output_validator.py # Sanity checks: are yields within
│ │ # historical range? Any NaN outputs?
│ │ # Any CRDs missing from results?
│ ├── databricks_writer.py # Write model outputs back to
│ │ # Databricks: agri_lake.models.yield_estimates
│ │ # so other teams can query results
│ └── run_report.py # Generate the PDF + Excel + email
├── references/
│ ├── pipeline-architecture.md # The 4-stage execution graph above,
│ │ # with file-level documentation
│ ├── file-by-file-docs.md # What each .m file does, inputs,
│ │ # outputs, known issues
│ ├── carlos-fix-explained.md # Full explanation of the Iowa CRD
│ │ # coefficient fix (what, why, when)
│ ├── input-schemas.md # Expected format for all 14 inputs
│ ├── output-schemas.md # What the model produces
│ ├── databricks-tables.md # Databricks table names, schemas,
│ │ # refresh schedules
│ └── methodology.md # Statistical methodology reference
├── assets/
│ ├── input_schemas.json # Machine-readable input validation
│ ├── output_ranges.json # Plausible yield ranges by CRD
│ ├── crd_weights.json # CRD → state aggregation weights
│ └── distribution_list.json # Email recipients
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (Databricks credentials via corporate SSO)
Installed at: ~/.agents/skills/yield-model-skill
KEY OUTCOME: Your MATLAB code is untouched. The skill wraps it with:
- Documentation (your team can now read pipeline-architecture.md
instead of reverse-engineering 23 cryptic files)
- Databricks integration (inputs from the shared lake, outputs
written back for other teams)
- Input validation (catches USDA format changes before they crash
the model at line 2,847 of run_v3b_final.m with "Index exceeds
matrix dimensions")
- A single command to run the entire pipeline:
/yield-model-skill Run the weekly yield update
Carla: Wait — it figured out the execution order from analyzing the MATLAB code? And it found Carlos's hotfix and explained it?
Copilot:
Yes. The file dependencies are traceable from the load() and
save() calls in each .m file. run_v3b_final.m loads 4 .mat files
that are created by the preprocessing stage. The preprocessors
load .mat files from the ingestion stage. The graph is:
load_*.m → merge_inputs.m → calc_*.m / create_lagged_vars.m →
normalize_features.m → run_v3b_final.m (+ carlos_fix) →
aggregators → outputs
And Carlos's fix is clearly a targeted coefficient override — lines
847-893 of run_v3b_final.m check if the CRD code is in a hardcoded
list of 12 Iowa CRDs, and if so, multiply the drought interaction
coefficient by -1. The comment says "sign error in original fitting,
verified with Carlos Sept 2024." That's important institutional
knowledge that was buried in a code comment. Now it's in a
standalone document (carlos-fix-explained.md) that anyone can read.
If Carlos leaves, the knowledge stays.
Carla: And Databricks — right now my team downloads CSVs from Databricks manually and puts them in a folder. This would pull directly?
Copilot:
Exactly. Here's what changes:
BEFORE (current workflow):
1. Someone opens Databricks in a browser
2. Navigates to agri_lake.weather.station_daily
3. Runs a manual SQL query with this month's date range
4. Clicks "Download CSV"
5. Renames the file, moves it to models/yield-forecaster/data/weather/
6. Repeats for the other 13 input files
7. Runs the MATLAB model
8. If USDA changed a column name → MATLAB crashes at some random line
9. Someone debugs for 2 hours, finds the column rename, fixes it
AFTER (with the skill):
1. Type: /yield-model-skill Run the weekly yield update
2. The skill pulls all 14 inputs from Databricks via SQL
3. Validates all inputs before passing to MATLAB
4. If a column was renamed, tells you BEFORE crashing:
"⚠️ USDA planting_progress table: column 'pct_planted' has been
renamed to 'planted_pct'. Updating the mapper. No action needed."
5. Runs the MATLAB pipeline
6. Validates outputs (yields within historical range)
7. Writes results to agri_lake.models.yield_estimates
8. Generates PDF and emails it
Steps 2-8 happen in ~4 minutes (mostly MATLAB execution time).
The S&D team can then query your yield estimates directly from
Databricks without waiting for you to email the PDF.
=============================================================
PHASE 5: PRICE ASSESSMENT — COPILOT CLI FOR THE TERMINAL-SHY
=============================================================
The Price Assessment desk has the most extreme case of tool
paralysis. Tomoko Watanabe's 8 analysts live in Bloomberg Terminal
and Refinitiv Eikon — powerful tools with their own scripting
environments, but completely disconnected from VS Code, Python, and
databases. They've never opened a terminal.
But Tomoko has a daily pain point that none of her Bloomberg tools
solve: every morning, she manually collects broker price indications
from 6 different email chains, a Bloomberg chat group, a WhatsApp
group (yes, really), and a shared Excel file. She normalizes the
units (some brokers quote FOB, others CIF; some in $/MT, others in
cents/bushel), calculates the bid-ask midpoint, and publishes the
firm's "daily assessment" — a single reference price that trading
desks and clients rely on.
The morning assessment takes 90 minutes, must be published by 8am,
and she's been doing it the same way for 7 years.
Tomoko doesn't want to open VS Code. She doesn't want to see code.
She's heard about "Copilot CLI" — the terminal tool that IT
installed. She asks the IT Slack channel:
Tomoko (in #ai-tools-support): "I've heard there's a way to use
Copilot from the terminal, without VS Code. How do I open it?"
IT Support: "Open Terminal on your Mac (it's in Applications >
Utilities), then type 'copilot' and press Enter."
Tomoko opens Terminal for the first time. She sees a black window
with a blinking cursor. She types "copilot" and presses Enter.
Tomoko (in Copilot CLI): I'm a price assessment analyst. Every morning I have to collect broker price indications from 6 email chains, normalize the units, and produce our firm's daily physical soybean assessment. Can you help me automate this? I don't know how to code. I just want to describe what I do and have it work.
Copilot CLI:
Yes. Let me first install a tool that will help us turn your
workflow into something reusable. One moment...
Installing agent-skill-creator...
curl -fsSL https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.sh | sh
✓ Installed. Detecting tools: copilot-cli... found.
Now describe your morning routine in as much detail as you can.
Include the data sources, the steps, and what the final output
looks like.
Tomoko: /agent-skill-creator Every morning between 6:30-8:00am I produce the firm's daily physical soybean price assessment. Here's exactly what I do: (1) I open Outlook and find the latest indication emails from 6 brokers — Cargill, Bunge, ADM, Cofco, LDC, and Viterra. They send indications overnight for FOB Santos, FOB Paranaguá, and CIF China soybean prices. Some quote in $/MT, some in cents/bushel, some in Brazilian reais/60kg bag. The emails have no standard format — each broker has their own template. (2) I open our Bloomberg chat group "Physical Soy Indications" where 3 more brokers post real-time numbers. (3) I check a shared Google Sheet where our Singapore desk posts overnight Asia-time indications. (4) I normalize everything to $/MT FOB Santos as the reference point, using the day's BRL/USD exchange rate (from Bloomberg), the FOB-CIF differential (~$28/MT for China route, varies by freight), and the bushel-to-MT conversion. (5) I calculate: bid midpoint, ask midpoint, bid-ask spread, and the daily change from yesterday. (6) I also compare to the CBOT front-month settlement + basis to derive "implied basis." (7) I produce a one-page "DAILY PHYSICAL ASSESSMENT" that gets published to the trading floor, 4 client distribution lists, and posted to our internal dashboard. (8) Deadline is 8:00am sharp — the trading desks wait for this before making physical offers. Here's yesterday's assessment: references/daily-assessment-sample.pdf and here's my normalization spreadsheet: references/price-normalization.xlsx
Copilot CLI (loading agent-skill-creator skill):
Reading references/daily-assessment-sample.pdf...
Reading references/price-normalization.xlsx...
This is a data collection + normalization + publishing pipeline
with strict time constraints. The hardest part is the EXTRACTION
— broker emails are unstructured, Bloomberg chat is messy, and
the Google Sheet is semi-structured. Let me build a skill that
handles the messy inputs.
Building...
daily-assessment-skill/
├── SKILL.md
├── scripts/
│ ├── email_collector.py # Parse indication emails from
│ │ # Outlook (via MAPI or EWS API)
│ │ # using broker-specific templates
│ ├── broker_parsers/
│ │ ├── cargill.py # Cargill indication format
│ │ ├── bunge.py # Bunge format (they use PDF attachments)
│ │ ├── adm.py # ADM format
│ │ ├── cofco.py # Cofco (sometimes in CNY)
│ │ ├── ldc.py # Louis Dreyfus format
│ │ └── viterra.py # Viterra format
│ ├── gsheet_reader.py # Pull Singapore desk indications
│ ├── normalizer.py # All prices → $/MT FOB Santos
│ │ # (FX rates, freight diffs, unit
│ │ # conversions)
│ ├── fx_fetcher.py # BRL/USD from Bloomberg or fallback
│ │ # to Central Bank API (BCB)
│ ├── basis_calculator.py # CBOT + basis → implied physical
│ ├── assessment_builder.py # Daily assessment document
│ ├── publisher.py # Email to 4 dist lists, post to
│ │ # internal dashboard API
│ └── audit_trail.py # Log every input price and its
│ │ # source for compliance
├── references/
│ ├── broker-formats.md # How each broker formats indications
│ ├── normalization-rules.md # Unit conversions, freight diffs
│ ├── fob-cif-differentials.md # Route-specific freight adjustments
│ └── methodology.md # Assessment methodology (auditable)
├── assets/
│ ├── broker_templates.json # Regex/patterns for each broker
│ ├── unit_conversions.json # BRL/bag → $/MT, ¢/bu → $/MT
│ ├── freight_diffs.json # FOB Santos, FOB Paranaguá, CIF China
│ ├── distribution_lists.json # 4 client groups
│ └── previous_assessments.json # Rolling 30-day history
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (Outlook access via corporate SSO, Google Sheet
via service account)
Installed at: ~/.agents/skills/daily-assessment-skill
⚠️ NOTE ON BLOOMBERG CHAT: Programmatic access to Bloomberg chat
requires Bloomberg B-PIPE or SAPI license, which your firm may
or may not have. If not, the skill will prompt you to manually
paste the chat indications (30 seconds vs. the current scrolling-
through-chat approach). I've designed it so the Bloomberg chat
input is optional — the skill works with email + Google Sheet
alone and flags if Bloomberg data is missing.
--- 6:35am the next morning, Tomoko tries the skill ---
Tomoko (in Terminal): /daily-assessment-skill Morning run
Copilot CLI (loading daily-assessment-skill):
DAILY PHYSICAL ASSESSMENT — March 5, 2026
Collection started at 6:35am ET
STEP 1: Collecting broker indications...
| Source | Status | Prices Found | Last Updated |
|------------------|---------|--------------|--------------|
| Cargill (email) | ✓ | 3 (FOB×2, CIF×1) | 5:48am |
| Bunge (email) | ✓ | 2 (FOB Santos, FOB Paranaguá) | 6:02am |
| ADM (email) | ✓ | 2 (FOB Santos, CIF China) | 5:55am |
| Cofco (email) | ✓ | 3 (FOB×2, CIF×1) | 6:12am |
| LDC (email) | ✓ | 2 (FOB Santos, FOB Paranaguá) | 5:30am |
| Viterra (email) | ⚠️ MISSING | — | No email found |
| Singapore desk | ✓ | 4 (CIF China×3, CIF SEA×1) | 4:15am |
| Bloomberg chat | ⏭️ SKIPPED | (manual entry available) | |
⚠️ Viterra hasn't sent their indication yet. This sometimes happens
— they send late on Wednesdays (their weekly team meeting morning).
Proceeding with 6 of 7 email sources. The assessment will note
"Viterra: not received at time of publication."
Do you want to manually paste the Bloomberg chat indications, or
proceed without them? [Paste / Skip / Wait 15min]
Tomoko: Skip, let's go with what we have
Copilot CLI:
STEP 2: Normalizing to $/MT FOB Santos...
FX rate: BRL/USD = 5.1842 (BCB, 6:30am fixing)
Freight diff: FOB Santos → CIF China = $28.50/MT (Baltic, yesterday)
CBOT May soybeans: $10.9450/bu = $402.01/MT (yesterday's settle)
RAW INDICATIONS (as received):
| Broker | Product | Raw Price | Raw Unit |
|----------|------------------|-----------------|-----------------|
| Cargill | FOB Santos Apr | +142/+148 c/bu | CBOT basis, ¢/bu|
| Cargill | FOB Paranaguá Apr| +138/+145 c/bu | CBOT basis, ¢/bu|
| Cargill | CIF China May | $430/$436 | $/MT outright |
| Bunge | FOB Santos Apr | +140/+146 c/bu | CBOT basis, ¢/bu|
| Bunge | FOB Paranaguá Apr| +135/+142 c/bu | CBOT basis, ¢/bu|
| ADM | FOB Santos Apr | R$142.50/R$145.80| BRL per 60kg bag|
| ADM | CIF China May | $428/$434 | $/MT outright |
| Cofco | FOB Santos Apr | $426/$432 | $/MT outright |
| Cofco | FOB Paranaguá Apr| $422/$428 | $/MT outright |
| Cofco | CIF China May | $431/$437 | $/MT outright |
| LDC | FOB Santos Apr | +141/+147 c/bu | CBOT basis, ¢/bu|
| LDC | FOB Paranaguá Apr| +136/+143 c/bu | CBOT basis, ¢/bu|
| SG Desk | CIF China May | $429/$435 | $/MT outright |
| SG Desk | CIF China Jun | $425/$431 | $/MT outright |
| SG Desk | CIF China Jul | $420/$427 | $/MT outright |
| SG Desk | CIF SEA May | $432/$438 | $/MT outright |
NORMALIZED TO $/MT FOB SANTOS:
| Broker | Bid ($/MT) | Ask ($/MT) | Mid ($/MT) | Method |
|----------|------------|------------|------------|---------------------|
| Cargill | $424.23 | $430.44 | $427.34 | CBOT + basis |
| Bunge | $423.50 | $429.71 | $426.61 | CBOT + basis |
| ADM | $425.12 | $430.45 | $427.79 | BRL/bag → $/MT |
| Cofco | $426.00 | $432.00 | $429.00 | Already $/MT |
| LDC | $423.87 | $430.08 | $426.97 | CBOT + basis |
| SG Desk | $401.00* | $407.00* | $404.00* | CIF−freight = FOB |
|----------|------------|------------|------------|---------------------|
| MEAN | $423.95 | $430.11 | $427.03 | |
| MEDIAN | $424.23 | $430.44 | $427.34 | |
* Singapore desk CIF-to-FOB conversion uses $28.50 freight.
Their CIF $429/$435 → FOB $401/$407. This is notably below the
direct FOB indications. Possible explanations: (a) different
freight assumption, (b) their quotes include older cargo, or
(c) Asia-time pricing was weaker than current. Flagged for review.
STEP 3: Assessment calculation...
DAILY PHYSICAL SOYBEAN ASSESSMENT — March 5, 2026
┌─────────────────────────────────────────────────────────┐
│ FOB SANTOS — SOYBEANS — APRIL SHIPMENT │
│ │
│ Assessment: $427.00 / $430.00 $/MT │
│ Midpoint: $428.50 $/MT │
│ Daily change: +$2.50 (from $426.00 yesterday) │
│ │
│ CBOT basis: +142 / +148 ¢/bu over May │
│ Implied basis: +144.5 ¢/bu (midpoint) │
│ Basis change: +3.5 ¢/bu (basis strengthened) │
│ │
│ FOB PARANAGUÁ — APRIL SHIPMENT │
│ Assessment: $422.50 / $428.00 $/MT │
│ Santos-Paranaguá diff: -$3.25 (normal range: -$2 to -$5)│
│ │
│ CIF CHINA — MAY SHIPMENT │
│ Assessment: $429.50 / $435.50 $/MT │
│ FOB-CIF spread: $28.75 (freight + insurance) │
│ │
│ Sources: Cargill, Bunge, ADM, Cofco, LDC, SG Desk │
│ Missing: Viterra (not received), Bloomberg chat (skipped)│
│ Published: 6:42am ET │
└─────────────────────────────────────────────────────────┘
STEP 4: Publishing...
✓ Emailed to: Trading Floor distribution (28 recipients)
✓ Emailed to: Client Group A — Institutional (142 recipients)
✓ Emailed to: Client Group B — Corporate (89 recipients)
✓ Emailed to: Client Group C — Internal Research (25 recipients)
✓ Posted to: internal dashboard (dashboard.globalagri.com/assessments)
✓ Audit trail saved: audit/assessment-2026-03-05.json
Published at 6:42am ET — 78 minutes before the 8:00am deadline.
Tomoko: That took 7 minutes instead of 90. And it caught the
Singapore desk discrepancy — I would have just averaged it in without
noticing.
Copilot CLI:
The Singapore discrepancy is worth investigating. If their freight
assumption is $25/MT instead of your $28.50, their FOB-equivalent
would be $404/$410 instead of $401/$407 — still below the direct
FOB indications but less extreme. You might want to ask the
Singapore desk what freight rate they're using.
Tomorrow morning, just type:
/daily-assessment-skill Morning run
Same as today. If Viterra's email arrives by then, it'll
automatically be included.
=============================================================
PHASE 6: THE DATABRICKS BRIDGE — FROM ISOLATED SKILLS TO
SHARED DATA INFRASTRUCTURE
=============================================================
After 6 weeks of individual skill adoption, the three desk heads
(Henrik, Carla, Tomoko) realize their skills are producing valuable
outputs that die on individual laptops. Henrik's S&D balance sheets
are in Excel. Carla's yield estimates are in MATLAB .mat files.
Tomoko's price assessments are in PDFs. Nobody can query anyone
else's outputs.
The data team lead (Rajesh Kapoor) gets pulled into a meeting.
Rajesh: "You want me to connect your Copilot skills to Databricks?
Let me understand what you actually need."
The meeting produces a clear architecture:
Henrik (in VS Code Copilot Chat): /agent-skill-creator We need to build a "bridge skill" that connects our existing skills to Databricks. Right now we have 6 skills running on individual laptops that produce outputs nobody else can access. I want each skill's output to be written to a shared Databricks table so the whole research division can query it. Here's what we need: (1) Luís's export-inspections-skill output → agri_lake.trade.weekly_inspections, (2) Ana's wasde-extractor-skill output → agri_lake.usda.wasde_extracted, (3) Carla's yield-model-skill output → agri_lake.models.yield_estimates (already done), (4) Tomoko's daily-assessment-skill output → agri_lake.prices.physical_assessments, (5) The S&D balance sheets → agri_lake.research.sd_balances. The Databricks workspace is at databricks.globalagri.com. Each analyst has a personal access token in their env as DATABRICKS_TOKEN. The data team has already created the target tables with the right schemas — Rajesh gave us the table definitions: references/databricks-target-schemas.sql
Copilot (loading agent-skill-creator skill):
Reading references/databricks-target-schemas.sql...
This is an integration layer, not a new skill. I'll create a shared
"Databricks publisher" module that any skill can import, plus
modify each existing skill to write outputs to Databricks after
producing local results.
The pattern is simple:
1. Skill runs locally (unchanged behavior — still produces the
Excel/PDF/report the analyst expects)
2. AFTER local output, a new step writes structured results to
the corresponding Databricks table
3. Write is idempotent (re-running the skill for the same date
overwrites, doesn't duplicate)
4. If Databricks is unreachable (network issue, token expired),
the skill still produces local output and logs a warning.
It never fails just because Databricks is down.
Building...
databricks-bridge-skill/
├── SKILL.md
├── scripts/
│ ├── databricks_client.py # Databricks SQL connector wrapper
│ │ # (auth via DATABRICKS_TOKEN, retry,
│ │ # timeout, error handling)
│ ├── table_writer.py # Generic write-to-table function
│ │ # with schema validation and
│ │ # upsert logic (MERGE statement)
│ ├── schema_validator.py # Validate DataFrame columns match
│ │ # target table schema before write
│ ├── publishers/
│ │ ├── inspections_pub.py # export-inspections → weekly_inspections
│ │ ├── wasde_pub.py # wasde-extractor → wasde_extracted
│ │ ├── yield_pub.py # yield-model → yield_estimates
│ │ ├── assessment_pub.py # daily-assessment → physical_assessments
│ │ └── balance_pub.py # S&D balances → sd_balances
│ └── health_check.py # Verify Databricks connectivity,
│ # table existence, token validity
├── references/
│ ├── target-schemas.md # Table definitions (from Rajesh)
│ ├── upsert-logic.md # How MERGE works, conflict resolution
│ ├── error-handling.md # What happens when Databricks is down
│ └── methodology.md
├── assets/
│ ├── table_schemas.json # Machine-readable target schemas
│ └── databricks_config.json # Workspace URL, catalog, schema names
├── install.sh
└── README.md
Validation: PASSED
Security: PASSED (DATABRICKS_TOKEN from env, MERGE-only writes)
Installed at: ~/.agents/skills/databricks-bridge-skill
I've also updated each existing skill to call the bridge after
producing local output. The integration is OPTIONAL — each skill
checks if databricks-bridge-skill is installed. If it is, outputs
go to Databricks. If not, the skill works exactly as before.
Now when Luís runs his Monday update:
/export-inspections-skill Run the Monday update
the inspection data lands in BOTH his local Excel AND
agri_lake.trade.weekly_inspections on Databricks.
And when a junior analyst on ANY desk wants to query last week's
physical soybean assessment alongside the WASDE S&D numbers and the
yield model estimates, they can write a single SQL query in
Databricks that joins all three tables. Data that used to live in
3 different analysts' laptops in 3 different formats is now in one
queryable place.
=============================================================
PHASE 7: THREE MONTHS LATER — THE CTO DASHBOARD
=============================================================
The CTO pulls up the adoption dashboard again. It's been 3 months
since Luís installed agent-skill-creator.
| Tool | Active Users | Before | Change |
|----------------|-------------|--------|--------|
| VS Code | 19 | 4 | +375% |
| GitHub Copilot | 16 | 2 | +700% |
| Copilot CLI | 6 | 0 | ∞ |
| GitLab | 12 | 1 | +1100% |
| Databricks | 22 | 3 | +633% |
Skills in the shared GitLab library: 11
Total skill invocations (last 30 days): 847
Estimated hours saved per month: ~180
Most-used skills:
1. daily-assessment-skill (Tomoko's team) — 22 runs/day × 22 days = 484
2. export-inspections-skill (Luís) — 4 runs/week × 12 weeks = 48
3. agdb-query-assistant-skill (all desks) — avg 6 queries/day = 132
4. wasde-extractor-skill (Ana) — 3 runs/month = 9
5. yield-model-skill (Carla's team) — 4 runs/month = 16
What changed:
THE 90-MINUTE WEBINAR taught people about TOOLS.
agent-skill-creator taught people about their WORKFLOWS.
Nobody woke up wanting to learn VS Code. But Luís wanted his Monday
summary to take 10 seconds. Ana wanted to stop copy-pasting from
PDFs. Tomoko wanted to publish her assessment before 7am. Carla
wanted her model to be reproducible.
The tools (VS Code, Copilot, GitLab, Databricks) were the means,
not the end. agent-skill-creator was the on-ramp that connected
"I have a tedious workflow" to "now there's a tool for that."
GitLab adoption went from 1 to 12 not because people learned Git,
but because they wanted to INSTALL their colleague's skills:
/agent-skill-creator install gitlab.globalagri.com/sd-team/skills/crop-progress-skill
They never typed 'git clone' or 'git pull' or 'git commit'. They
used agent-skill-creator as the interface, and GitLab was just
where the skills lived.
Databricks adoption went from 3 to 22 because the bridge skill
made it the SHARED DESTINATION for every skill's output. Analysts
who never wrote SQL started asking the agdb-query-assistant-skill
to pull data from Databricks:
/agdb-query-assistant-skill Show me yesterday's physical assessment
next to the latest yield estimate for US soybeans
They never opened the Databricks UI. They didn't need to.
THE DOG NO LONGER SEES A CASTLE.
The dog sees a door. And the door says:
"Tell me what you do every day. I'll make it faster."
That's all agent-skill-creator ever needed to be. Not a developer
tool. Not an AI platform. Not a framework.
A door.
#############################################################
#############################################################
## ##
## DESIGN PRINCIPLE: ##
## "DON'T MAKE HUMANS BE CLEAR" ##
## ##
## Real users don't write specifications. They dump files, ##
## paste URLs, forward emails, and say "make it work." ##
## The agent must derive intent from messy context. ##
## ##
#############################################################
#############################################################
THE PROBLEM WITH THE SIMULATIONS ABOVE:
Every simulation so far has a user who writes something like:
"I need a skill that: (1) does X, (2) does Y, (3) handles Z,
with format A for input and format B for output. Here are my
requirements: [perfectly structured paragraph]."
That's fiction. Real users — especially non-technical analysts in
corporate environments — do NOT write clear specifications. They
can't. Not because they're lazy or stupid, but because:
- They don't know what they don't know (they can't specify edge
cases they haven't thought about)
- They don't have the vocabulary (they say "the thing that shows
the numbers" not "the S&D balance sheet pivot table")
- They're busy (they have 10 minutes between meetings, not an hour
to write a requirements doc)
- The workflow lives in muscle memory (they can DO it, but they
can't DESCRIBE it — like explaining how to ride a bicycle)
- They communicate in artifacts, not words (they'll show you the
spreadsheet, not describe it)
agent-skill-creator must be designed to work with MESSY, INCOMPLETE,
INARTICULATE input. The agent's job is to derive intent from whatever
the human dumps on it — files, URLs, screenshots, half-sentences,
forwarded emails, "like this but different."
Here's what REAL interactions look like:
=============================================================
REAL INTERACTION 1: The File Dump
=============================================================
What the analyst ACTUALLY types:
Analyst: /agent-skill-creator here
And then drags 5 files into the chat:
- weekly-process.xlsx
- last-weeks-output.pdf
- usda-website-screenshot.png
- email-from-boss.eml
- old-script-that-half-works.py
That's it. No description. No requirements. Just "here."
What agent-skill-creator does:
Copilot (loading agent-skill-creator skill):
Let me understand what you need from these files...
Reading weekly-process.xlsx...
Reading last-weeks-output.pdf...
Viewing usda-website-screenshot.png...
Reading email-from-boss.eml...
Reading old-script-that-half-works.py...
OK, here's what I'm piecing together:
YOUR WORKFLOW (reconstructed from the files):
1. weekly-process.xlsx — This is your working spreadsheet. It has 6
tabs: "Raw Data", "Pivot", "YoY Comparison", "Pace Calculator",
"Charts", and "Summary". The "Raw Data" tab has USDA export
inspection data pasted in (columns match the USDA FAS CSV
format). The "Summary" tab is a formatted table that looks like
it gets copy-pasted into a report.
2. last-weeks-output.pdf — This is what the final product looks
like. It's a one-page PDF with the summary table from your
Excel, plus two charts (cumulative exports by destination, and
weekly pace vs. needed pace). Header says "Weekly Export
Inspections Summary — Week Ending Feb 20, 2026."
3. usda-website-screenshot.png — This is a screenshot of
apps.fas.usda.gov/export-sales/inspections.htm showing where
you download the CSV. You circled the "Current Marketing Year"
link in red.
4. email-from-boss.eml — From Henrik Johansson, Feb 24: "Can you
make the weekly export summary include soymeal and soyoil too?
And add a comparison to the 5-year average pace. Client asked
for it. Need it by next Monday."
5. old-script-that-half-works.py — A 47-line Python script that
downloads the USDA CSV and filters for soybeans. It has a
comment on line 12: "# TODO: this breaks when USDA changes
column names again" and another on line 38: "# Ana wrote this
part, not sure what it does". The script stops after filtering —
no pivot, no pace calculation, no output formatting.
MY UNDERSTANDING OF WHAT YOU NEED:
You manually produce a weekly export inspections report. The process
is: download CSV from USDA FAS → paste into Excel → filter → pivot
by destination → calculate YoY and pace → format summary → generate
charts → export to PDF. It takes some amount of time you'd rather
not spend.
Your boss just expanded the scope: add soymeal and soyoil, add
5-year average pace comparison. Deadline: next Monday.
Someone (you or Ana?) started writing a Python script to automate
the first part but it only does the CSV download and breaks
periodically.
IS THIS RIGHT? Before I build anything, let me confirm:
1. The output should look exactly like last-weeks-output.pdf but
with soymeal + soyoil added (separate tables? or combined?)
2. "5-year average pace" = for each week of the marketing year,
what was the average cumulative export percentage across the
last 5 marketing years?
3. The marketing year for soybeans is Sep 1 – Aug 31. Is it the
same for soymeal and soyoil?
4. The PDF goes to Henrik (your boss) — does it also go to clients
directly, or does Henrik paste it into a larger report?
I only need quick answers — one word each is fine. I'll figure out
the rest from the files.
Analyst: combined table, yes, yes same, henrik pastes it into bigger report
Copilot:
Got it. Building...
[builds the skill — same quality as before, but derived entirely
from the 5 files, not from a written specification]
=============================================================
REAL INTERACTION 2: The URL Dump + Half-Sentence
=============================================================
What the analyst ACTUALLY types:
Analyst: /agent-skill-creator i need something for this
https://apps.fas.usda.gov/psdonline/app/index.html#/app/advQuery
and also this
https://quickstats.nass.usda.gov/
same thing as what we do in the wasde extractor but for these two
maybe look at references/psd-api-docs.html too
What agent-skill-creator does:
Copilot (loading agent-skill-creator skill):
Let me look at what you shared...
Fetching https://apps.fas.usda.gov/psdonline/app/index.html...
→ This is the USDA PSD (Production, Supply & Distribution) online
query tool. It has a web-based advanced query builder for global
commodity S&D data.
Fetching https://quickstats.nass.usda.gov/...
→ This is USDA NASS Quick Stats — the statistical query tool for
domestic agricultural data (acreage, yield, production, prices,
by state/county/crop reporting district).
Reading references/psd-api-docs.html...
→ This is the FAS Open Data Web API documentation. There's a REST
API at apps.fas.usda.gov/opendataweb/api/ that returns PSD data
as JSON. Endpoints: commodities, countries, unitsOfMeasure,
and the main query endpoint with commodity_code, country_code,
market_year filters.
Looking at your existing wasde-extractor-skill for the pattern...
→ That skill: downloads USDA data → parses structured tables →
compares to previous period → produces a change summary →
exports to Excel/markdown.
HERE'S WHAT I THINK YOU WANT:
Two data sources (PSD and NASS Quick Stats) that you currently
query manually through web interfaces, turned into skills that
follow the same pattern as your WASDE extractor — download, parse,
compare, summarize.
SKILL A — PSD Balance Sheet Puller:
Instead of clicking through the PSD web query tool (selecting
commodity, country, market year, clicking "Get Data", exporting
CSV, then reformatting in Excel), you'd say:
/psd-query-skill US soybeans 2025/26 balance sheet
And get a formatted S&D table with month-over-month revisions.
SKILL B — NASS Quick Stats Puller:
Instead of clicking through Quick Stats (selecting Program,
Sector, Group, Commodity, Category, Domain, Geographic Level...
it's 8 dropdown menus), you'd say:
/nass-query-skill Iowa corn yield by county 2020-2025
And get a clean table.
Both would use APIs (PSD has the REST API you shared, NASS has a
public API at quickstats.nass.usda.gov/api) instead of scraping
web pages. More reliable, faster, and won't break when USDA
redesigns the website.
Is this the right direction? Or did you mean something different
by "same thing as the wasde extractor"?
Analyst: yes that plus can the psd one compare our internal balance to usda
Copilot:
Smart — so the PSD skill doesn't just pull USDA data, it also reads
your team's internal balance (from research.sd_balances on
Databricks, same as what the agdb-query-assistant uses) and shows
a side-by-side comparison: "Our estimate vs USDA" with the
differences highlighted.
That's actually three things in one:
1. Pull USDA PSD data via API
2. Pull internal estimate from Databricks
3. Show the gap and flag where you differ by more than X%
Building both skills...
=============================================================
REAL INTERACTION 3: The Screenshot and a Complaint
=============================================================
What the analyst ACTUALLY types:
Analyst: /agent-skill-creator this is ridiculous
[drags in a screenshot of a Bloomberg terminal showing a cluttered
Excel spreadsheet open next to it, with red circles and arrows drawn
on it in MS Paint]
look at this mess. every day i manually type these bloomberg numbers
into this spreadsheet. there has to be a better way
What agent-skill-creator does:
Copilot (loading agent-skill-creator skill):
Viewing your screenshot...
I can see:
- LEFT SIDE: Bloomberg Terminal showing settlement prices for what
looks like CBOT grain futures (corn, wheat, soybeans — I can read
the tickers: C 1, W 1, S 1, SM 1, BO 1, plus some ICE contracts)
- RIGHT SIDE: An Excel spreadsheet with columns: Date, Contract,
Settlement, Change, Volume, Open Interest. The data matches what's
on the Bloomberg screen. Your red circles highlight the cells
where you're typing today's numbers.
- The arrow goes from the Bloomberg price to the corresponding
Excel cell.
You're manually transcribing settlement prices from Bloomberg into
Excel every day. I can see about 15 contracts in the spreadsheet
and 12 visible on the Bloomberg screen.
QUESTIONS (so I build the right thing):
1. How many contracts total do you track? (I can see ~15 in the
spreadsheet, but there might be more below the visible area)
2. Is this ONLY settlement prices, or do you also record volume,
open interest, and daily change?
3. Do you have Bloomberg API access (B-PIPE, SAPI, or DAPI), or
are you limited to the Terminal screen?
4. Does your firm have a data feed that already captures these
settlements? (Many firms store Bloomberg data in a database —
you might not need to pull from Bloomberg at all if it's already
in agri_lake on Databricks)
The answer to #4 could save us a LOT of complexity. If Rajesh's
data team already loads daily settlements into Databricks, the
skill just needs to query Databricks and format the spreadsheet.
No Bloomberg API needed.
Analyst: oh i didnt know databricks might have it. how do i check
Copilot:
Let me check for you right now.
/agdb-query-assistant-skill Are there daily settlement prices in
Databricks? Look for tables with settlement, price, or daily in
the name.
[querying Databricks catalog]
YES. Found it:
agri_lake.market.daily_settlements
- 2.4 million rows (goes back to 2018)
- Columns: price_date, instrument_code, settlement_price,
daily_change, volume, open_interest, exchange
- Updated daily at 6:30pm CT (after CBOT close)
- Includes: CBOT (corn, wheat, soybeans, meal, oil), ICE (coffee,
sugar, cotton, cocoa), MATIF (milling wheat, rapeseed)
- 48 contracts currently active
YOU ALREADY HAVE THIS DATA IN DATABRICKS. You don't need to type
it from Bloomberg at all. The data team loads it automatically
every evening.
So instead of a Bloomberg-scraping skill, what you need is:
1. A skill that queries agri_lake.market.daily_settlements
2. Formats the results to match your Excel layout
3. Writes to your spreadsheet (or replaces it entirely)
This is a 10-minute build, not a Bloomberg API project.
Want me to build it?
Analyst: omfg yes
Copilot (loading agent-skill-creator skill):
Building...
daily-settlements-skill/
├── SKILL.md
├── scripts/
│ ├── settlement_puller.py # Query Databricks for latest
│ │ # settlements by contract list
│ ├── excel_formatter.py # Match the analyst's existing
│ │ # spreadsheet layout exactly
│ └── change_highlighter.py # Color-code moves > 2% (red/green)
├── references/
│ ├── contract-list.md # The 15 contracts to track
│ └── methodology.md
├── assets/
│ └── contract_list.json # Configurable contract list
├── install.sh
└── README.md
Installed at: ~/.agents/skills/daily-settlements-skill
This replaces 15 minutes of daily Bloomberg-to-Excel transcription
with a 5-second query. And you'll never have a typo again.
But the bigger insight: you didn't know the data was already in
Databricks. The skill didn't just automate your workflow — it
revealed that your workflow was UNNECESSARY. The daily manual
transcription was solving a problem that was already solved by
infrastructure you didn't know existed.
This happens more than you'd think.
=============================================================
REAL INTERACTION 4: The Forwarded Email + "Can We Do This?"
=============================================================
What the analyst ACTUALLY types:
Analyst: /agent-skill-creator my colleague from London sent me this. is this something we could build?
[pastes the full body of a forwarded email, including the original
headers, signatures, legal disclaimers, and a 6-message reply chain]
---------- Forwarded message ----------
From: James Whitfield <j.whitfield@globalagri.com>
To: Maria Santos <m.santos@globalagri.com>
Subject: FW: RE: RE: CONAB data automation
Maria,
See below — the London grains desk built something that pulls CONAB
crop estimates automatically when they're released. Apparently it
runs every time CONAB publishes (they don't have a fixed schedule,
it's usually 2nd or 3rd week of the month). The London team says
it's saved them hours. Think we could do something similar for our
Brazil soy coverage?
- James
---------- Original message ----------
From: Oliver Chang <o.chang@globalagri-london.com>
To: James Whitfield <j.whitfield@globalagri.com>
Subject: RE: CONAB data automation
James,
Yeah we've been running it since November. It monitors the CONAB
website (conab.gov.br/info-agro/safras/graos), detects when a new
Boletim de Safra PDF is posted, downloads it, extracts the Brazil
soy/corn/cotton production and area tables, converts from Portuguese,
compares to the previous month's boletim, and flags any revision
larger than 1 MMT. Output goes to our Bloomberg chat and a shared
drive.
We built it in Python — about 400 lines. The tricky part was parsing
the CONAB PDF because they change the table layout slightly every
few months and the tables have merged cells. We ended up using
Camelot for the table extraction. It breaks maybe once or twice a
year when CONAB does a major format change.
Happy to share the code but it's a bit messy and has our London
paths hardcoded everywhere.
- Oliver
---------- Earlier ----------
[3 more messages of scheduling back-and-forth, irrelevant to the
technical content]
DISCLAIMER: This email is confidential and intended solely for...
[200 words of legal boilerplate]
What agent-skill-creator does:
Copilot (loading agent-skill-creator skill):
Let me extract the useful information from this email chain...
IGNORING: scheduling messages (3), legal disclaimer, email headers,
signatures.
RELEVANT CONTENT (from Oliver Chang's email):
The London grains desk has a working Python script (~400 lines) that:
1. Monitors conab.gov.br for new Boletim de Safra PDFs
2. Downloads the PDF when detected
3. Extracts Brazil soy/corn/cotton production + area tables
4. Translates from Portuguese
5. Compares to previous month, flags revisions > 1 MMT
6. Outputs to Bloomberg chat + shared drive
Known issues:
- CONAB changes table layout periodically → breaks the PDF parser
- Code has London-specific hardcoded paths
- Built with Camelot (Python PDF table extraction library)
- Breaks ~1-2x/year on major format changes
WHAT YOU COULD DO:
Option A — Get Oliver's code, clean it up, wrap it as a skill
(faster if the code is solid, but "a bit messy" suggests fragile)
Option B — Build a new skill from scratch using the same approach
but with better PDF parsing resilience and your team's output
format (your format differs from London's — they post to Bloomberg
chat, you'd want it in your existing report pipeline)
Option C — Build a hybrid: use Oliver's proven CONAB monitoring
logic (website polling, URL pattern detection) but rebuild the
PDF extraction with a more resilient approach than Camelot
(possibly using LLM-based table extraction, which handles layout
changes much better than rule-based parsers)
My recommendation: Option C. The monitoring logic is
straightforward and Oliver has it working. The PDF parsing is the
fragile part — and that's where modern LLM-based extraction
(feeding the PDF page image to an LLM and asking it to extract
the table) would be much more resilient than Camelot's rule-based
approach.
Want me to build this? I can also reach out to Oliver's code via
your GitLab if it's there — or you can ask him to share it and
drop it in references/.
Analyst: dont have his code yet. just build it from what you know about conab. i can always refine later
Copilot:
Building from public knowledge of CONAB's publication patterns...
[builds conab-monitor-skill — with website poller, PDF download,
LLM-assisted table extraction, Portuguese→English translation,
revision tracking, and output to the team's existing pipeline]
The key design decision: instead of rigid Camelot table extraction
(which breaks on layout changes), the skill sends each PDF page to
the LLM with the prompt: "Extract the soybean production table
from this CONAB Boletim de Safra page. Return: state, area_ha,
yield_kg_ha, production_mt." This approach handles layout changes
gracefully because the LLM reads the page visually, not by pixel
coordinates.
When Oliver shares his code, we can cherry-pick his monitoring
logic (CONAB URL patterns, publication detection) and plug it in.
The skill is designed to accept improvements incrementally.
=============================================================
REAL INTERACTION 5: The Absolute Minimum Viable Input
=============================================================
This is the most extreme case — and the most realistic. The analyst
provides almost nothing. The agent must work with what it has.
What the analyst ACTUALLY types:
Analyst: /agent-skill-creator freight
That's it. One word.
What agent-skill-creator does:
Copilot (loading agent-skill-creator skill):
"Freight" is broad. Let me figure out what you need based on your
context.
You're on the S&D desk at GlobalAgri Capital. In the context of
ag commodity research, "freight" likely means one of:
A. OCEAN FREIGHT RATES — tracking Panamax/Supramax bulk carrier
rates on key grain routes (US Gulf to China, Santos to China,
Black Sea to Egypt). You need this for: CIF price calculations,
export competitiveness analysis, and logistics cost monitoring.
B. BARGE FREIGHT — US inland barge rates on the Mississippi/
Illinois/Ohio rivers. You need this for: basis analysis (barge
freight affects the spread between CBOT and Gulf FOB prices).
C. FREIGHT FUTURES — FFA (Forward Freight Agreement) curves and
derivatives. You need this for: hedging logistics risk and
forward pricing.
D. CONTAINER FREIGHT — rates for containerized ag products (dairy,
meat, specialty crops). Less likely for your desk.
Which one? Or multiple?
Analyst: A. but i dont know where the data comes from. tomoko does this somehow
Copilot:
Let me check what Tomoko uses...
Looking at the daily-assessment-skill (Tomoko's)...
Found: in her normalization step, she uses a FOB-CIF differential
of $28.50/MT for the Santos→China route, sourced from "Baltic
Exchange via Refinitiv."
Looking at Databricks...
Found: agri_lake.shipping.freight_rates — daily ocean freight rates
by route, going back to 2019. Sources include Baltic Exchange
(Panamax, Supramax indices) and broker indications.
Columns: rate_date, route_code, vessel_class, rate_usd_mt,
rate_worldscale, index_value, source.
Routes available:
- USG_CN (US Gulf → China): Panamax
- SANTOS_CN (Santos → China): Panamax
- SANTOS_EU (Santos → EU): Supramax
- BSEA_EGY (Black Sea → Egypt): Handysize
- BSEA_CN (Black Sea → China): Panamax
- PNW_CN (Pacific NW → China): Panamax
- ARG_CN (Up River → China): Panamax
- 12 more routes...
So the data already exists. You need a skill that:
1. Pulls freight rates from Databricks
2. Shows you the current rate by route
3. Tracks trends (is freight rising or falling?)
4. Calculates what the freight cost means for export competitiveness
(e.g., "at current freight, US Gulf soybeans to China cost $X/MT
delivered vs Santos soybeans at $Y/MT — Brazil has a $Z/MT
logistics advantage")
That's a freight competitiveness tool, not just a freight tracker.
It tells the S&D team which origin is cheapest to ship from on any
given day — which directly affects trade flow forecasts.
Want me to build this?
Analyst: ya
Copilot:
Building...
[builds freight-competitiveness-skill from one word of input + the
analyst's desk context + Databricks schema discovery + Tomoko's
existing skill as a reference point]
=============================================================
DESIGN IMPLICATIONS FOR AGENT-SKILL-CREATOR
=============================================================
These interactions reveal what agent-skill-creator must actually
be good at:
1. FILE INTERPRETATION, NOT REQUIREMENTS GATHERING
The primary input is ARTIFACTS, not words:
- Excel files (reverse-engineer the workflow from the sheet structure)
- PDFs (understand what the output should look like)
- Screenshots (read what's on the screen, including Bloomberg)
- Code files (understand what already exists, what's broken)
- Emails (extract the actual request from the noise)
- URLs (fetch and understand the data source)
The agent must be able to look at an Excel workbook with 6 tabs
and reconstruct the entire workflow: "Tab 1 is raw input, Tab 2 is
a pivot of Tab 1 filtered by X, Tab 3 compares Tab 2 to a baseline
in Tab 4, Tab 5 generates charts from Tab 3, Tab 6 is the formatted
output." The human will never describe this. The spreadsheet IS the
specification.
2. CONTEXT INFERENCE, NOT EXPLICIT REQUIREMENTS
When someone types "freight" the agent should already know:
- What desk they're on (S&D, modelling, price assessment)
- What commodities they cover (grains, oilseeds, softs)
- What data sources are already available (Databricks, Bloomberg,
colleagues' existing skills)
- What output format their team uses (Excel, PDF, markdown)
The agent doesn't ask "what do you mean by freight?" — it presents
the most likely interpretation given the context and confirms.
3. PROGRESSIVE REFINEMENT, NOT UPFRONT SPECIFICATION
The interaction pattern should be:
- Human dumps messy input (files, URLs, one word, screenshot)
- Agent reconstructs intent and presents its understanding
- Human corrects with minimal effort ("yes", "no the other one",
"also add X")
- Agent builds a first version
- Human uses it, finds gaps, says "also do Y"
- Agent refines
This is how humans naturally communicate. They don't write specs.
They iterate. The agent must be comfortable building from 60%
understanding and refining, rather than demanding 100%
understanding before starting.
4. DISCOVERY OVER ASSUMPTION
The analyst manually typing Bloomberg prices into Excel didn't know
the data was already in Databricks. The analyst who said "freight"
didn't know Tomoko's skill already had freight data. The agent's
job is not just to build what was asked, but to DISCOVER what
already exists and connect the dots.
Before building, always check:
- Is this data already in Databricks? (query the catalog)
- Has a colleague already built a skill for this? (check the
team's GitLab skill library)
- Is there an API for this data source? (check before scraping)
- Does the existing workflow have a simpler solution? (maybe the
entire workflow is unnecessary)
5. CONFIRM, DON'T INTERROGATE
BAD: "Please provide: (1) the data source URL, (2) the update
frequency, (3) the output format, (4) the distribution list..."
(This is a requirements form. Nobody fills these out.)
GOOD: "From your files, it looks like you download data from USDA
every Monday, pivot it by destination, and send Henrik a PDF.
Right?"
(This is a confirmation. One word to accept.)
The agent should do the work of understanding and present a
hypothesis. The human's job is to confirm or correct — not to
specify from scratch.
6. FAIL FORWARD, NOT FAIL SAFE
When the agent has 60% understanding, it should build the 60% skill
and let the human see the output. The human will immediately say
"this is wrong, it should be X" — which is MUCH easier than asking
the human to specify X from nothing. Seeing a wrong output is the
fastest way for a non-technical person to articulate what they
actually want.
The worst thing the agent can do is ask 15 clarifying questions
before building anything. By question 5, the human has given up
and gone back to their spreadsheet.
SUMMARY:
agent-skill-creator should treat human input as EVIDENCE, not
INSTRUCTIONS. The files, URLs, screenshots, half-sentences, and
single words are all evidence of what the human needs. The agent's
job is forensic — reconstruct the intent from the evidence, present
a hypothesis, confirm, build, and refine.
The human is never the bottleneck. The agent is always the one doing
the work of understanding.
Reference in a new issue View git blame Copy permalink