<essential_principles>
The CFTC Commitments of Traders report is the core data for tracking hedge fund agricultural positions:
- As-of date: Close every Tuesday
- Release date: Every Friday at 3:30 PM ET
- Trader classification: Non-commercial (speculative/fund), commercial (hedging), non-reportable
Fund flow = this week's net position - last week's net position (in contracts)
Use CFTC native groups (commodity_subgroup_name):
| Group | CFTC group name | Included commodities |
|---|---|---|
| Grains | GRAINS | Corn, Wheat (SRW/HRW/HRS), Oats |
| Oilseeds | OILSEED and PRODUCTS | Soybeans, Soybean Oil/Meal, Canola |
| Meats | LIVESTOCK/MEAT PRODUCTS | Live Cattle, Lean Hogs, Feeder |
| Softs | FOODSTUFFS/SOFTS | Coffee, Sugar, Cocoa, OJ |
| Fiber | FIBER | Cotton |
| Dairy | DAIRY PRODUCTS | Milk, Butter, Cheese |
Total Flow = Grains + Oilseeds + Meats + Softs + Fiber + Dairy
Measure whether funds still have room to add:
net_pos_percentile = rank(current_net_pos, past_N_weeks)
firepower = 1 - net_pos_percentile
- High firepower (>0.6): Positions are at historical lows, still ample room to buy
- Low firepower (<0.3): Positions are already near historical highs, crowding risk is high
Integrate three risk appetite indicators:
| Indicator | Signal interpretation |
|---|---|
| US Dollar (DXY) | Weakening (negative return) = bullish for commodities |
| Crude Oil (WTI) | Strengthening (positive return) = rising risk appetite |
| Metals | Strengthening (positive return) = optimistic cyclical demand |
macro_tailwind_score = (DXY weak + WTI strong + Metals strong) / 3
COT only goes through Tuesday; Wednesday to Friday requires proxy evidence:
- Price momentum: Cumulative return of agricultural products/proxy indices from Wed to Fri
- Open interest change: OI expansion = new positions (not pure turnover)
- Macro resonance: Simultaneity with USD down, oil price up, metals up
</essential_principles>
- Obtain data: COT weekly report, macro indicators (DXY/WTI/metals), fundamental triggers (exports/USDA)
- Calculate flows: Weekly change in net positions, grouped aggregation (Grains/Oilseeds/Meats/Softs/Total)
- Quantify firepower: Use historical percentiles to estimate funds' room to add
- Integrate signals: Determine 'funds coming back to buy' + 'macro tailwind' + 'fundamental support'
- Produce narrative: Turn chart annotations (such as Strong Corn Demand) into repeatable rules
Output: weekly flow time series, latest status, firepower score, macro score, tradable annotations.
<quick_start>
Quick start: analyze the latest COT data
cd .claude/skills/track-agri-hedge-fund-positioning/scripts
pip install pandas numpy requests yfinance pyarrow # 首次使用
python analyze_positioning.py --start 2023-01-01
Output example (real data):
{
"skill": "track-agri-hedge-fund-positioning",
"as_of": "2026-01-20",
"data_source": "CFTC Socrata API (real data)",
"summary": {
"call": "Funds continue selling",
"all_signals": ["Funds continue selling", "Extreme short - watch for reversal", "Macro mood bullish"],
"confidence": 0.90
},
"latest_metrics": {
"flow_total_contracts": -24559,
"flow_by_group_contracts": {"grains": -31279, "oilseeds": 11517, "meats": 18972, "softs": -23887, "fiber": 1607, "dairy": -1489},
"buying_firepower": {"total": 0.86, "grains": 0.58, "oilseeds": 0.62, "meats": 0.31, "softs": 0.99, "fiber": 0.58, "dairy": 0.99},
"macro_tailwind_score": 0.67
}
}
Visualization charts：
python visualize_flows.py --weeks 52
# 輸出：output/agri_fund_positioning_YYYY-MM-DD.png
</quick_start>
- Quick check - View the latest week's fund position changes and status
- Full analysis - Fund flow analysis and backtesting for a specified date range
- Visualization charts - Generate grouped bar charts and firepower time series charts
- Monitoring mode - Set weekly updates and signal alerts
- Methodology learning - Understand COT analysis and firepower calculation logic
Please select or directly provide analysis parameters.
All scripts use the CFTC Socrata API to obtain real data, with no simulated data.
<reference_index>
Reference Documents (references/)
| Document | Content |
|---|---|
| methodology.md | COT analysis methodology, firepower calculation, signal logic |
| data-sources.md | CFTC COT, FRED, Yahoo Finance data sources |
| input-schema.md | Complete input parameter definitions |
| contracts-map.md | Futures contract and commodity group mapping table |
| macro-indicators.md | Macro indicator definitions and proxy series |
| </reference_index> |
<workflows_index>
| Workflow | Purpose | When to Use |
|---|---|---|
| analyze.md | Complete capital flow analysis | When in-depth analysis is needed |
| visualize.md | Generate visualization charts | When news charts need to be recreated |
| monitor.md | Weekly monitoring and alerts | After each Friday's COT update |
| cross-check.md | Macro and fundamental cross-validation | When verifying narrative consistency |
| </workflows_index> |
<templates_index>
| Template | Purpose |
|---|---|
| output-json.md | JSON output structure definition |
| output-markdown.md | Markdown report template |
| annotations.md | Chart annotation rule mapping table |
| </templates_index> |
<scripts_index>
| Script | Command | Purpose |
|---|---|---|
| fetch_cot_data.py | --start 2023-01-01 --summary |
Fetch COT from CFTC Socrata API |
| fetch_macro_data.py | --start 2025-01-01 --summary |
Fetch macro indicators (Yahoo/FRED) |
| analyze_positioning.py | --start 2023-01-01 |
Main analysis script (auto-fetch + calculation) |
| visualize_flows.py | --weeks 52 |
Generate Bloomberg-style visualization charts |
| </scripts_index> |
<input_schema_summary>
Required Parameters
| Parameter | Type | Description |
|---|---|---|
| date_start | string | Start date (YYYY-MM-DD) |
| date_end | string | End date (YYYY-MM-DD) |
| cot_report | string | COT type (legacy/disaggregated) |
| trader_group | string | Trader category (noncommercial) |
| contracts_map | object | Contract→group mapping table |
Optional Parameters
| Parameter | Type | Default Value | Description |
|---|---|---|---|
| position_metric | string | net | Position measure (net/long/short) |
| lookback_weeks_firepower | int | 156 | Firepower calculation window (weeks) |
| macro_indicators | object | {...} | Macro indicator settings |
| fundamental_inputs | object | {...} | Fundamental data settings |
| event_window_days | int | 3 | Wed-Fri event window |
| output_mode | string | both | Output format (markdown/json) |
For complete parameter definitions see references/input-schema.md。
</input_schema_summary>
<output_schema_summary>
{
"skill": "track-agri-hedge-fund-positioning",
"as_of": "2026-01-21",
"summary": {
"call": "Funds back & buying",
"confidence": 0.72,
"why": ["COT 週部位由負轉正", "分組同步改善", "宏觀順風"],
"risks": ["COT 只到週二", "USDA 報告可能反轉"]
},
"latest_metrics": {
"cot_week_end": "2026-01-21",
"flow_total_contracts": 58,
"flow_by_group_contracts": {
"grains": 35, "oilseeds": 25, "meats": 5, "softs": 0
},
"buying_firepower": {
"total": 0.63, "grains": 0.58, "oilseeds": 0.67
},
"macro_tailwind_score": 0.67
},
"annotations": [
{"label": "macro_mood_bullish", "rule_hit": true, "evidence": ["USD down", "crude up"]}
]
}
For complete output structure see templates/output-json.md。
</output_schema_summary>
<success_criteria> Successful execution should produce:
- Weekly flow time series (Grains/Oilseeds/Meats/Softs/Fiber/Dairy/Total)
- Latest week's flow and net position
- Firepower score for each group (buying_firepower)
- Macro tailwind score (macro_tailwind_score)
- Tradable calls and confidence levels
- Chart annotations and rule triggers
- Risk warnings and next-step recommendations
- Bloomberg-style visualization charts (output/agri_fund_positioning_YYYY-MM-DD.png) </success_criteria>