faostat-skills 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "faostat-skills",
+  "description": "Analysis skills for UN FAOSTAT food and agriculture data. Country profiles, commodity briefings, trade analysis, climate assessments, and data visualizations. Works with any AI assistant that supports the SKILL.md format.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Griffiths Obli-Laryea"
+  },
+  "homepage": "https://github.com/berba-q/faostat-skills",
+  "repository": "https://github.com/berba-q/faostat-skills",
+  "license": "MIT",
+  "keywords": [
+    "faostat",
+    "agriculture",
+    "food-security",
+    "trade",
+    "emissions",
+    "climate",
+    "commodities",
+    "analysis",
+    "visualization"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Griffiths Obli-Laryea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# FAOSTAT Skills
+
+[![npm version](https://img.shields.io/npm/v/faostat-skills)](https://www.npmjs.com/package/faostat-skills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-blueviolet)](https://claude.com/claude-code)
+[![Codex](https://img.shields.io/badge/Codex-compatible-green)](https://openai.com)
+
+AI-powered analysis skills for the [UN FAOSTAT](https://www.fao.org/faostat/en/#data) database — the world's most comprehensive source of food and agriculture statistics. These platform-agnostic skills guide your AI assistant through multi-step analytical workflows: country food security profiles, trade dependency analysis, commodity deep dives, agrifood climate assessments, and data-driven storytelling.
+
+**Works with:** Claude Code, OpenAI Codex, and any AI assistant that supports the `SKILL.md` format.
+
+### Quick Start
+
+```bash
+# Claude Code
+claude plugin install faostat-skills
+
+# Then ask:
+# "Give me a food security profile for Kenya"
+# "Compare wheat yields in France, USA, and India"
+# "How dependent is Egypt on wheat imports?"
+```
+
+## Prerequisites
+
+The [FAOSTAT MCP Server](https://github.com/berba-q/faostat-mcp) must be installed and configured before using these skills.
+
+```bash
+pip install faostat-mcp
+```
+
+Then configure your credentials (one-time setup) by asking your AI assistant:
+> "Set up FAOSTAT with my credentials"
+
+## Installation
+
+### Claude Code
+
+```bash
+claude plugin install faostat-skills
+```
+
+Or install directly from GitHub:
+
+```bash
+claude plugin install berba-q/faostat-skills
+```
+
+### OpenAI Codex
+
+Clone this repo into your Codex skills directory:
+
+```bash
+git clone https://github.com/berba-q/faostat-skills.git ~/.agents/skills/faostat-skills
+```
+
+Or symlink the skills directory:
+
+```bash
+ln -s /path/to/faostat-skills/skills ~/.agents/skills/faostat
+```
+
+### Other AI Assistants
+
+Copy the `skills/` directory to wherever your AI tool discovers skill files. Each skill is a self-contained `SKILL.md` with YAML frontmatter and markdown instructions.
+
+## Available Skills
+
+### Tier 1: Core Analysis
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **Country Food Security Profile** | `/faostat-country-profile` | Comprehensive food security assessment — production, trade, nutrition, and risk indicators for any country |
+| **Comparative Agricultural Analysis** | `/faostat-compare` | Side-by-side comparison of agricultural metrics across countries, commodities, or regions |
+| **Commodity Deep Dive** | `/faostat-commodity` | Complete global briefing for any commodity — production rankings, yield trends, trade flows |
+
+### Tier 2: Specialized
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **Agrifood Climate Analyzer** | `/faostat-climate` | Climate-agriculture nexus analysis — emissions profiles, temperature trends, land use, inputs-emissions links |
+| **Trade Dependency Analyzer** | `/faostat-trade` | Import dependence assessment with self-sufficiency ratios and supply chain risk indicators |
+| **Data Visualizer** | `/faostat-viz` | Generate interactive Chart.js HTML charts from FAOSTAT data |
+
+### Tier 3: Creative
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **Agricultural Trend Monitor** | `/faostat-trends` | Identify biggest changes and anomalies in agricultural data over a time window |
+| **Data Storyteller** | `/faostat-story` | Build data-driven narratives with embedded charts for journalism and research |
+| **FAOSTAT Explorer** | `/faostat-explore` | Guided discovery of FAOSTAT's data catalog with sample data and explanations |
+
+## Examples
+
+```
+> Give me a food security profile for Kenya
+
+> Compare wheat yields in France, USA, and India over the last 10 years
+
+> Tell me everything about global rice production and trade
+
+> What are the agrifood emissions for Brazil? How do they compare per capita?
+
+> How dependent is Egypt on wheat imports?
+
+> Chart the top 10 maize producers over the last 20 years
+
+> What's changed most in African agriculture over the last 5 years?
+
+> Help me write a data story about the global avocado boom
+
+> What data does FAOSTAT have about fertilizers?
+```
+
+## FAOSTAT Domain Reference
+
+Key domains used by these skills:
+
+| Domain | Content |
+|--------|---------|
+| **QCL** | Crops and Livestock Products (production, area, yield) |
+| **TM** | Trade Matrix (import/export by partner) |
+| **FBS** | Food Balance Sheets (supply/demand for 360+ foods) |
+| **FS** | Food Security indicators |
+| **GT** | Emissions Totals — agrifood systems (broadest scope) |
+| **GCE** | Emissions from crops only |
+| **GF** | Forest emissions/removals — sinks, net conversion |
+| **EI** | Emissions Intensities |
+| **EM** | Emissions Indicators (shares, per capita, per value) |
+| **ET** | Temperature Change |
+| **RL** | Land Use |
+| **RFN/RFM/RFB** | Fertilizers |
+| **RP/RT** | Pesticides use and trade |
+
+## Architecture
+
+```
+FAOSTAT Skills (this repo)          FAOSTAT MCP Server (separate)
+┌────────────────────────┐          ┌────────────────────────┐
+│ 9 platform-agnostic    │  uses    │ 21 MCP tools           │
+│ SKILL.md workflows     │────────→ │ Published on PyPI      │
+│                        │          │ v1.2.2 · stable        │
+└────────────────────────┘          └────────────────────────┘
+```
+
+Skills orchestrate the MCP server's tools into multi-step analysis workflows. They encode FAOSTAT domain expertise so users can easily interact with the FAOSTAT data.
+
+## Project Structure
+
+```
+faostat-skills/
+├── skills/                     ← Core: platform-agnostic SKILL.md files
+│   ├── country-profile/
+│   ├── compare/
+│   ├── commodity/
+│   ├── trade/
+│   ├── trends/
+│   ├── climate/
+│   ├── viz/
+│   ├── story/
+│   └── explore/
+├── .claude-plugin/             ← Claude Code packaging
+├── .agents/skills/             ← OpenAI Codex packaging (symlink)
+├── commands/                   ← Claude Code slash commands
+├── README.md
+└── LICENSE
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-skill`)
+3. Follow the existing SKILL.md format (YAML frontmatter + markdown instructions)
+4. Test the skill with a real FAOSTAT MCP server connection
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related
+
+- [FAOSTAT MCP Server](https://github.com/berba-q/faostat-mcp) — The MCP server these skills are built on
+- [FAOSTAT](https://www.fao.org/faostat/en/#data) — The UN FAO FAOSTAT database

package/commands/faostat-climate.md

@@ -0,0 +1,6 @@
+---
+description: Analyze agrifood emissions, climate impact, deforestation, land use, and the agriculture-climate nexus using FAOSTAT data
+argument-hint: <country or topic, e.g. "Brazil emissions profile" or "deforestation in Indonesia">
+---
+
+Invoke the `faostat-climate` skill to handle this request. The skill supports five sub-workflows: country emissions profiles, emissions comparisons, crop emissions analysis, forest & land use, and inputs-emissions links. Detect the appropriate sub-workflow from the user's input, or present the options.

package/commands/faostat-commodity.md

@@ -0,0 +1,6 @@
+---
+description: Generate a global briefing for an agricultural commodity
+argument-hint: <commodity name>
+---
+
+Invoke the `commodity` skill to produce a comprehensive global briefing for the specified commodity. If no commodity is provided in the argument, ask the user which commodity they would like analyzed.

package/commands/faostat-compare.md

@@ -0,0 +1,6 @@
+---
+description: Compare countries or commodities on agricultural metrics
+argument-hint: <entity1> vs <entity2> [metric]
+---
+
+Invoke the `compare` skill to produce a structured side-by-side comparison. If no entities or metric are provided in the argument, ask the user what they would like to compare and on which metric.

package/commands/faostat-country-profile.md

@@ -0,0 +1,6 @@
+---
+description: Generate a food security and agricultural profile for a country
+argument-hint: <country name>
+---
+
+Invoke the `country-profile` skill to generate a comprehensive food security profile for the specified country. If no country is provided in the argument, ask the user which country they would like profiled.

package/commands/faostat-explore.md

@@ -0,0 +1,6 @@
+---
+description: Guided discovery of FAOSTAT data catalog — browse domains, see samples, understand what's available
+argument-hint: [topic of interest]
+---
+
+Invoke the `faostat-explore` skill to run the FAOSTAT Explorer. Pass along any topic of interest or question the user specified.

package/commands/faostat-story.md

@@ -0,0 +1,6 @@
+---
+description: Build a data-driven narrative with embedded charts from FAOSTAT data
+argument-hint: <research question or story angle>
+---
+
+Invoke the `faostat-story` skill to run the Data Storyteller. Pass along any research question, story angle, or topic the user specified.

package/commands/faostat-trade.md

@@ -0,0 +1,6 @@
+---
+description: Assess food import dependence, self-sufficiency ratios, and supply chain risk for a country and commodity
+argument-hint: <country and commodity, e.g. "Egypt wheat" or "Japan rice">
+---
+
+Invoke the `faostat-trade` skill to handle this request. The skill calculates self-sufficiency ratios, identifies top trading partners and concentration risk, and tracks dependency trends over time.

package/commands/faostat-trends.md

@@ -0,0 +1,6 @@
+---
+description: Identify biggest changes, fastest growers/decliners, and anomalies in agricultural data
+argument-hint: <region or countries> [time window]
+---
+
+Invoke the `faostat-trends` skill to run the Agricultural Trend Monitor. Pass along any region, countries, time window, or commodity focus the user specified.

package/commands/faostat-viz.md

@@ -0,0 +1,6 @@
+---
+description: Generate interactive HTML charts from FAOSTAT data (line, bar, scatter, stacked bar)
+argument-hint: <what to visualize, e.g. "wheat production trends for top 5 producers">
+---
+
+Invoke the `faostat-viz` skill to handle this request. The skill queries FAOSTAT data (or uses data already in conversation context), selects the appropriate chart type, and generates a standalone interactive HTML chart with Chart.js.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "faostat-skills",
+  "version": "0.1.0",
+  "description": "Analysis skills for UN FAOSTAT food and agriculture data. Country profiles, commodity briefings, trade analysis, climate assessments, and data visualizations.",
+  "author": "Griffiths Obli-Laryea",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/berba-q/faostat-skills.git"
+  },
+  "homepage": "https://github.com/berba-q/faostat-skills",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "faostat",
+    "agriculture",
+    "food-security",
+    "trade",
+    "emissions",
+    "climate",
+    "commodities",
+    "analysis",
+    "mcp",
+    "ai-skills"
+  ],
+  "files": [
+    "skills/",
+    "commands/",
+    ".claude-plugin/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/climate/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: faostat-climate
+description: Use when the user asks about agricultural emissions, climate impact of farming, agrifood carbon footprint, greenhouse gases from agriculture, deforestation, forest carbon sinks, temperature change, fertilizer emissions, N2O, land use change, emissions intensity, or the climate-agriculture nexus. Keywords: emissions, climate, carbon, greenhouse gas, GHG, deforestation, forest, temperature, warming, N2O, fertilizer emissions, land use, agrifood, emissions intensity, carbon sink
+---
+
+# Agrifood Climate Analyzer
+
+Analyze the climate-agriculture nexus using FAOSTAT emissions, temperature, land use, and agricultural inputs data. This skill has five sub-workflows. Detect the appropriate one from the user's question, or present the options and ask.
+
+## Prerequisites
+
+Before starting, verify that the FAOSTAT MCP tools are available: `faostat_search_codes`, `faostat_get_data`, `faostat_get_rankings`. If they are not available, inform the user they need the FAOSTAT MCP server configured and stop.
+
+## Domain Reference (CRITICAL -- use exactly these codes)
+
+| Domain | Code | Content |
+|--------|------|---------|
+| Emissions Totals | **GT** | Agrifood systems emissions -- broadest scope, full agrifood chain |
+| Crop Emissions | **GCE** | Emissions from crops only (narrower than GT) |
+| Forest Emissions/Removals | **GF** | Forest sinks, net forest conversion (deforestation proxy) |
+| Emissions Intensities | **EI** | Emissions per unit of output |
+| Emissions Indicators | **EM** | Shares, per capita, per value of agricultural production |
+| Temperature Change | **ET** | Country-level warming trends |
+| Land Use | **RL** | Agricultural and forest land use |
+| Fertilizers (use & trade) | **RFN**, **RFM**, **RFB** | Nitrogen, manufactured, bulk fertilizers |
+| Pesticides Use | **RP** | Pesticide application data |
+| Pesticides Trade | **RT** | Pesticide import/export data |
+
+## Sub-workflow Detection
+
+Read the user's question and select the most appropriate sub-workflow:
+
+- **Country emissions profile** -- questions about a single country's agrifood emissions footprint, climate impact, or warming trend. Use Sub-workflow A.
+- **Emissions comparison** -- questions comparing emissions across countries or regions, "who emits the most," rankings. Use Sub-workflow B.
+- **Crop emissions / efficiency** -- questions about emissions from specific crops, which countries produce most efficiently, emissions intensity. Use Sub-workflow C.
+- **Deforestation / forest / land use** -- questions about forest loss, carbon sinks, agricultural expansion, land use change. Use Sub-workflow D.
+- **Fertilizer-emissions link** -- questions about fertilizer use and emissions, N2O, pesticide trends, input intensity. Use Sub-workflow E.
+
+If the question does not clearly match one sub-workflow, present the five options with a one-line description of each and ask the user to choose.
+
+## Sub-workflow A: Country Emissions Profile
+
+1. Ask for the country if not already specified.
+2. Resolve the country name to an area code using `faostat_search_codes(domain_code='GT', dimension_id='area', query='<country>')`.
+   - If `requires_confirmation` is true in the response, present the matching options and ask the user to choose. Do NOT proceed until the user confirms.
+3. Pull agrifood systems emissions totals from the **GT** domain:
+   `faostat_get_data(domain_code='GT', area='<area_code>', response_format='compact')`
+   Focus on the most recent 10 years. Identify total agrifood emissions and breakdown by source category (farm gate, land use, pre/post production).
+4. Pull emissions indicators from the **EM** domain:
+   `faostat_get_data(domain_code='EM', area='<area_code>', response_format='compact')`
+   Extract per capita emissions, share of national total, emissions per value of agricultural production.
+5. Pull temperature change data from the **ET** domain:
+   `faostat_get_data(domain_code='ET', area='<area_code>', response_format='compact')`
+   Identify the warming trend over the available period.
+6. Synthesize into a structured profile:
+   - **Agrifood Emissions Overview** -- total emissions, trend (rising/falling/stable), breakdown by source
+   - **Normalized Metrics** -- per capita, share of national emissions, per dollar of agricultural output
+   - **Temperature Trend** -- warming trajectory for this country
+   - **Key Findings** -- 2-3 headline insights connecting the data
+7. Attribute: "Source: FAOSTAT (FAO), accessed [current date]"
+
+## Sub-workflow B: Emissions Comparison
+
+1. Ask for the countries or region to compare (minimum 2, maximum 10). Accept country names, region names, or a mix.
+2. Resolve each entity to area codes using `faostat_search_codes(domain_code='GT', dimension_id='area', query='<name>')`.
+   - Handle `requires_confirmation` for each entity separately. Do NOT proceed until all codes are confirmed.
+3. Pull emissions totals from the **GT** domain for all entities:
+   `faostat_get_data(domain_code='GT', area='<code1>,<code2>,...', response_format='compact')`
+4. Pull emissions indicators from the **EM** domain for all entities:
+   `faostat_get_data(domain_code='EM', area='<code1>,<code2>,...', response_format='compact')`
+   Extract per capita and share metrics for normalization.
+5. Present comparison:
+   - **Absolute emissions** -- rank by total agrifood emissions (latest year)
+   - **Per capita emissions** -- re-rank by per capita to show a different picture
+   - **Per value of output** -- emissions efficiency ranking
+   - **Trend comparison** -- who is reducing, who is increasing?
+   - **Key insights** -- highlight surprising reversals or contrasts between absolute and normalized rankings
+6. Attribute: "Source: FAOSTAT (FAO), accessed [current date]"
+
+## Sub-workflow C: Crop Emissions Analysis
+
+1. Ask for the crop and optionally a set of countries. If no countries specified, use global top producers.
+2. Resolve the crop to an item code using `faostat_search_codes(domain_code='GCE', dimension_id='item', query='<crop>')`.
+   - Handle `requires_confirmation` as always.
+3. If countries were specified, resolve their area codes. If not, use `faostat_get_rankings` to identify top 10 producers for context.
+4. Pull crop-specific emissions from the **GCE** domain:
+   `faostat_get_data(domain_code='GCE', item='<item_code>', area='<codes>', response_format='compact')`
+5. Pull emissions intensities from the **EI** domain:
+   `faostat_get_data(domain_code='EI', item='<item_code>', area='<codes>', response_format='compact')`
+6. Rank countries by emissions intensity (lowest = most efficient).
+7. Present analysis:
+   - **Total crop emissions** -- who emits the most growing this crop?
+   - **Emissions intensity ranking** -- who produces most efficiently per unit of output?
+   - **Efficiency trends** -- is intensity improving or worsening over time?
+   - **Key insight** -- highlight the gap between the most and least efficient producers
+8. Attribute: "Source: FAOSTAT (FAO), accessed [current date]"
+
+## Sub-workflow D: Forest & Land Use
+
+1. Ask for the country or region if not specified.
+2. Resolve area codes using `faostat_search_codes(domain_code='GF', dimension_id='area', query='<name>')`.
+   - Handle `requires_confirmation`.
+3. Pull forest emissions and removals from the **GF** domain:
+   `faostat_get_data(domain_code='GF', area='<area_code>', response_format='compact')`
+   Look for: net forest conversion (deforestation proxy), forest land emissions, forest land removals (carbon sinks).
+4. Pull land use data from the **RL** domain:
+   `faostat_get_data(domain_code='RL', area='<area_code>', response_format='compact')`
+   Look for: agricultural land area, forest area, changes over time.
+5. Analyze the relationship:
+   - **Forest carbon balance** -- are removals (sinks) offsetting emissions? What is the net?
+   - **Net forest conversion** -- proxy for deforestation rate and trend
+   - **Land use shift** -- is agricultural land expanding at the expense of forest?
+   - **Timeline** -- when did the biggest changes occur?
+6. Present findings:
+   - **Forest Emissions & Sinks** -- net balance, trend
+   - **Deforestation Proxy** -- net forest conversion figures and direction
+   - **Land Use Dynamics** -- agricultural vs. forest area over time
+   - **Key Finding** -- is agriculture driving deforestation here? How do sinks compare to emissions?
+7. Attribute: "Source: FAOSTAT (FAO), accessed [current date]"
+
+## Sub-workflow E: Inputs-Emissions Link
+
+1. Ask for the country or set of countries if not specified.
+2. Resolve area codes using `faostat_search_codes(domain_code='GT', dimension_id='area', query='<name>')`.
+   - Handle `requires_confirmation`.
+3. Pull fertilizer use data from the **RFN** domain (nitrogen fertilizers are the primary N2O driver):
+   `faostat_get_data(domain_code='RFN', area='<area_code>', response_format='compact')`
+4. Optionally pull from **RFM** (manufactured) and **RFB** (bulk) for a fuller picture.
+5. Pull pesticide use from the **RP** domain:
+   `faostat_get_data(domain_code='RP', area='<area_code>', response_format='compact')`
+6. Pull agrifood emissions from the **GT** domain:
+   `faostat_get_data(domain_code='GT', area='<area_code>', response_format='compact')`
+   Focus on N2O emissions components if available.
+7. Analyze the correlation:
+   - **Fertilizer use trend** -- is nitrogen fertilizer use increasing or decreasing?
+   - **Emissions trend** -- do N2O / total agrifood emissions track fertilizer use?
+   - **Pesticide trend** -- increasing or decreasing? Any policy-driven shifts?
+   - **Correlation assessment** -- does higher fertilizer use correspond to higher emissions in this country/set?
+8. Present findings:
+   - **Fertilizer Use** -- volumes, trends, nitrogen share
+   - **Pesticide Use** -- volumes, trends
+   - **Emissions Correlation** -- how closely do inputs track emissions?
+   - **Policy Implications** -- what does this suggest for emissions reduction strategies?
+9. Attribute: "Source: FAOSTAT (FAO), accessed [current date]"
+
+## Important Rules
+
+- Always use `faostat_search_codes` before `faostat_get_data` to resolve codes. Never guess domain-specific codes.
+- When `requires_confirmation` is true in a search result, always present options to the user and wait for their choice.
+- Use `response_format='compact'` when querying multiple entities or large time ranges.
+- For rankings, use DISPLAY element codes (e.g., '5510' for production). For data filtering, use FILTER codes (e.g., '2510' for production).
+- Always include the source attribution line at the end of any output.

package/skills/commodity/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: faostat-commodity
+description: Use when the user asks about a specific crop or commodity — global production, top producers, yield trends, trade flows, or a commodity briefing. Keywords: commodity, crop, wheat, rice, maize, coffee, cocoa, soybean, production rankings, top producers, yield, trade, global supply
+---
+
+# Commodity Deep Dive
+
+Generate a comprehensive global briefing for a specific agricultural commodity using FAOSTAT data.
+
+## Prerequisites
+
+Verify that the following FAOSTAT MCP tools are available before proceeding:
+- `faostat_search_codes`
+- `faostat_get_data`
+- `faostat_get_rankings`
+
+If any tool is missing, inform the user: "This skill requires the FAOSTAT MCP server to be connected. Please ensure it is running and try again."
+
+## Workflow
+
+### Step 1: Identify the Commodity
+
+Extract the commodity name from the user's message, or ask if not specified. Accept common names (e.g., "wheat", "coffee", "palm oil").
+
+### Step 2: Resolve Commodity Code
+
+Call `faostat_search_codes(domain_code='QCL', dimension_id='item', query='<commodity_name>')`.
+
+**CRITICAL:** If the response contains `requires_confirmation: true`, present ALL matching options to the user and ask them to select the correct one. This is common for items like "rice" (paddy vs. milled), "oil" (multiple types), or "beans" (multiple varieties). Do NOT proceed until the user confirms.
+
+Store the confirmed `item` code.
+
+### Step 3: Pull Global Production Rankings
+
+Call `faostat_get_rankings` with:
+- `domain_code='QCL'`
+- `element_code='5510'` (Production — NOTE: this is the DISPLAY code, which `faostat_get_rankings` requires, NOT the filter code '2510')
+- `item_code='<resolved_item_code>'`
+- `year='<most_recent_year>'` (try current year minus 2; if no data, try minus 3)
+- `limit=10`
+- `response_format='objects'`
+
+Record the top 10 producers and their production volumes.
+
+### Step 4: Pull Yield and Area Trends for Top Producers
+
+For the **top 5 producers** from Step 3, pull multi-year data.
+
+Call `faostat_get_data` for each metric:
+
+**Production trends:**
+- `domain_code='QCL'`
+- `area='<top5_area_codes>'` (comma-separated)
+- `item='<item_code>'`
+- `element='2510'` (Production — FILTER code for `faostat_get_data`)
+- `year='<10_year_range>'` (e.g., `'2014:2023'`)
+- `response_format='compact'`
+- `limit=100`
+- `show_unit=True`
+
+**Area harvested trends:**
+- Same parameters but `element='2312'` (Area harvested — FILTER code)
+
+**Yield trends:**
+- Same parameters but `element='2413'` (Yield — FILTER code)
+
+**IMPORTANT DISTINCTION:** `faostat_get_rankings` uses DISPLAY element codes (e.g., `'5510'`). `faostat_get_data` uses FILTER element codes (e.g., `'2510'`). These are different code systems — do not mix them.
+
+### Step 5: Pull Global Trade Data
+
+Call `faostat_get_data` with:
+- `domain_code='TM'`
+- `item='<item_code>'` (search for the item in the TM domain first if the QCL item code does not work)
+- `response_format='compact'`
+- `limit=50`
+
+Extract:
+- Top exporters and importers by value or quantity
+- Total global trade volume if available
+- Trade flow direction (which regions export, which import)
+
+If the QCL item code does not return trade data, call `faostat_search_codes(domain_code='TM', dimension_id='item', query='<commodity_name>')` to find the correct TM item code.
+
+### Step 6: Compose the Briefing
+
+Structure the output as follows:
+
+**Title:** Commodity Briefing: [Commodity Name]
+
+1. **Global Production Overview**
+   - Total global production (if available) and the year of data
+   - Top 10 producers ranked by volume, with percentage share of global total
+   - Concentration: how much the top 3 and top 5 producers control
+
+2. **Yield Trajectories**
+   - Yield trends for top 5 producers over the past decade
+   - Which countries are improving yields fastest
+   - Current yield levels and gaps between leaders and laggards
+   - Area harvested trends — is growth coming from expansion or intensification?
+
+3. **Trade Flows**
+   - Major exporters and importers
+   - Net trade position of top producers (do they consume domestically or export?)
+   - Any notable trade dependencies
+
+4. **Historical Context & Outlook**
+   - How has production shifted over the past decade?
+   - Emerging producers (countries with fastest growth)
+   - Key risks: concentration risk, climate vulnerability, trade dependency
+   - Brief note on the commodity's global significance (food staple, cash crop, animal feed, biofuel feedstock, etc.)
+
+End with:
+
+> Source: FAOSTAT (FAO), accessed [current date]. Production rankings and trade data may reflect reporting lags of 1-3 years.
+
+## Error Handling
+
+- If trade data is unavailable for the commodity, note this and complete the briefing with production data only.
+- If yield data is missing for some countries, compute trends only for countries with sufficient data.
+- If the most recent year returns no data, step back one year at a time (up to 3 attempts).
+
+## Output Format
+
+Lead with the production rankings table for immediate impact. Follow with narrative sections. Use tables for ranked data and inline numbers for trend descriptions. Keep the analysis concise but substantive — aim for a briefing that gives the reader a complete picture in under 2 minutes of reading.