faostat-skills 0.2.1 → 0.2.3

package/README.md

@@ -22,10 +22,12 @@ claude plugin install faostat-skills@faostat
 
 **OpenAI Codex**
 ```bash
-git clone https://github.com/berba-q/faostat-skills.git ~/.agents/skills/faostat-skills
+# Clone, then copy each skill folder directly into your skills directory
+git clone https://github.com/berba-q/faostat-skills.git /tmp/faostat-skills
+cp -r /tmp/faostat-skills/skills/* ~/.codex/skills/
 ```
 
-**Other AI assistants** — copy the `skills/` directory to wherever your tool discovers skill files. Consult your provider's documentation for the correct skills directory path.
+**Other AI assistants** — copy the contents of the `skills/` directory to wherever your tool discovers skill files. Consult your provider's documentation for the correct skills directory path.
 
 Once installed, try asking:
 ```
@@ -66,18 +68,24 @@ claude plugin update faostat-skills@faostat
 
 ### OpenAI Codex
 
-Clone this repo into your Codex skills directory:
+Each skill folder must sit directly inside your Codex skills directory — not nested inside a parent folder. Clone and copy:
 
 ```bash
-git clone https://github.com/berba-q/faostat-skills.git ~/.agents/skills/faostat-skills
+git clone https://github.com/berba-q/faostat-skills.git /tmp/faostat-skills
+cp -r /tmp/faostat-skills/skills/* ~/.codex/skills/
 ```
 
-Or symlink the skills directory:
+Or keep the repo for easy updates via `git pull`:
 
 ```bash
-ln -s /path/to/faostat-skills/skills ~/.agents/skills/faostat
+git clone https://github.com/berba-q/faostat-skills.git ~/faostat-skills
+for dir in ~/faostat-skills/skills/*/; do
+  ln -s "$dir" ~/.codex/skills/"$(basename "$dir")"
+done
 ```
 
+> Consult the [Codex documentation](https://platform.openai.com/docs/codex) for the exact skills directory path on your system.
+
 ### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faostat-skills",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",
@@ -28,7 +28,6 @@
     "skills/",
     "commands/",
     ".claude-plugin/",
-    "marketplace.json",
     "README.md",
     "LICENSE"
   ]

package/skills/analytical-brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: faostat-analytical-brief
-description: Use when the user wants a short, FAOSTAT-style analytical brief — a multi-page PDF policy document in the FAOSTAT house visual style, with a HIGHLIGHTS box, global/regional/country sections, numbered figures with source lines, explanatory notes, and a data appendix. Use when the user asks for "an analytical brief on X", "a FAOSTAT-style brief", "a policy brief", "a FAO-style write-up", or a short policymaker-facing report. Keywords: analytical brief, policy brief, FAOSTAT brief, FAO-style, brief, briefing (policy), policymakers, short report (policy). Do NOT use for journalistic long-reads (use `faostat-story`), academic papers (forthcoming `faostat-scientific-paper`), or single-page visual summaries (forthcoming `faostat-infographic`).
+description: Use when the user wants a short, FAOSTAT-style analytical brief — a multi-page PDF policy document in the FAOSTAT house visual style, with a HIGHLIGHTS box, global/regional/country sections, numbered figures with source lines, explanatory notes, and a data appendix. Use when the user asks for "an analytical brief on X", "a FAOSTAT-style brief", "a policy brief", "a FAO-style write-up", or a short policymaker-facing report. Keywords — analytical brief, policy brief, FAOSTAT brief, FAO-style, brief, briefing (policy), policymakers, short report (policy). Do NOT use for journalistic long-reads (use `faostat-story`), academic papers (forthcoming `faostat-scientific-paper`), or single-page visual summaries (forthcoming `faostat-infographic`).
 ---
 
 # FAOSTAT Analytical Brief
@@ -30,6 +30,7 @@ All 6 invariants from the FAOSTAT skill suite apply unchanged:
 4. **TCL for national trade aggregates, TM only for partner breakdowns.** Never sum TM rows to reconstruct national totals.
 5. **China composite default (user preference, Apr 2026).** Default to composite `China` (area 351) for country rankings, top-N lists and country-level analysis. Offer `China, mainland` (41) as an opt-in — do not substitute 41 unless the user asks for 41 explicitly. Flag the choice in the Methodology sheet, and include the caveat whenever a China number is quoted: FAOSTAT's own publications default to 41, so a brief using 351 will show a marginally larger "China" value than the FAO data-portal default. (Map figures inside the brief are an exception: they use the disaggregation path — area 41 on the CHN polygon with HKG / MAC / TWN rendered separately — because choropleths cannot sensibly render 351. See the map skill.)
 6. **`faostat_get_rankings` HTTP-500 fallback.** Reconstruct rankings from `faostat_get_data` + client-side sort; document fallback in the Methodology sheet.
+7. **Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
 
 ## Workflow
 
@@ -64,7 +65,7 @@ For each figure and table, plan a specific `faostat_get_data` call. Log every ca
 - Use comma-separated year lists.
 - Use `response_format='compact'`.
 - Pass `show_unit=True`.
-- For trade aggregates, use **TCL** elements (2610 import quantity, 2910 export quantity, 2612 import value, 2912 export value) — not TM sums.
+- For trade aggregates, use **TCL** elements — not TM sums. Resolve element codes at runtime: e.g. `faostat_search_codes(domain_code='TCL', dimension_id='element', query='import quantity')` → e.g. 2610; similarly for export quantity (~2910), import value (~2612), export value (~2912). Treat any numeric code here as a verified hint to validate against, not a value to pass directly.
 - For region figures, pull the 6 continental area codes (Africa 5100, Americas 5200, Asia 5300, Europe 5400, Oceania 5500, World 5000) directly — don't compute them client-side.
 - For top-N country figures, **don't** rely on `faostat_get_rankings`; pull `faostat_get_data` for the domain and element (no area filter) and sort client-side, so an HTTP-500 from `get_rankings` doesn't block the brief.
 - For China in country rankings and country-level analysis, keep composite `China` (area 351) and drop 41 (mainland), unless the user opted into 41 explicitly. (Map figures inside the brief use the disaggregation path — area 41 + HKG 96 + MAC 128 + TWN 214 — because a choropleth cannot render 351 sensibly.)

package/skills/climate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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. Do NOT use for a full country food security profile → `faostat-country-profile`. Do NOT use for trend ranking across commodities or countries → `faostat-trends`.
+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. Do NOT use for a full country food security profile → `faostat-country-profile`. Do NOT use for trend ranking across commodities or countries → `faostat-trends`.
 ---
 
 # Agrifood Climate Analyzer
@@ -28,13 +28,13 @@ Before starting, verify that the FAOSTAT MCP tools are available: `faostat_searc
 
 ## Element Filter Reference
 
-Every `faostat_get_data` call below specifies an `element` filter. Without one, emissions domains return dozens of sub-elements per year and the payload explodes. If an element code is unfamiliar, resolve via `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='...')`.
+Every `faostat_get_data` call below specifies an `element` filter. Without one, emissions domains return dozens of sub-elements per year and the payload explodes.
+
+**Rule:** For GT, GF, ET, RL, RFN, RP — the codes below are stable and may be used directly. For **EM domain elements, always resolve at runtime** via `faostat_search_codes(domain_code='EM', dimension_id='element', query='<metric>')` — never hardcode them. The verified codes shown are reference hints only.
 
 | Metric | Domain | Filter code |
 |--------|--------|-------------|
 | Emissions (CO2eq) | GT | `724313` |
-| Share in total emissions (%) | EM | `7231` |
-| Emissions per capita (kg CO2eq/person) | EM | `723112` |
 | Temperature change (°C) | ET | `7271` |
 | Net forest conversion (area, ha) | GF | `6646` |
 | Forest land emissions (CO2eq) | GF | `724313` |
@@ -43,6 +43,23 @@ Every `faostat_get_data` call below specifies an `element` filter. Without one,
 | N fertilizer use (tonnes) | RFN | `5157` |
 | Pesticide use (tonnes) | RP | `5157` |
 
+**EM domain — resolve at runtime (hints only):**
+
+| Metric | Element query | Verified code |
+|--------|--------------|---------------|
+| Emissions per capita | `query='per capita'` | `7279` |
+| Share of agrifood in national total (CO2eq AR5) | `query='share CO2eq'` | `726313` |
+| Emissions per value of agricultural production | `query='per value'` | `72791` |
+
+**EM domain item codes (for filtering the agrifood breakdown):**
+
+| Item | Code |
+|------|------|
+| Agrifood systems (broadest total) | `6518` |
+| Farm gate | `6996` |
+| Land-use change | `6516` |
+| Pre- and post-production | `6517` |
+
 Year-range syntax: use explicit comma-separated lists (`year='2014,2015,...,2023'`). Colon ranges (`'2014:2023'`) have returned empty in practice.
 
 ## Sub-workflow Detection
@@ -74,12 +91,18 @@ If the question does not clearly match one sub-workflow, present the five option
    )
    ```
    Identify total agrifood emissions trend and the breakdown by source category (farm gate, land use, pre/post production — these come through as different `item` codes within GT).
-4. Pull emissions indicators from the **EM** domain:
+4. Resolve EM element codes at runtime (do not hardcode):
+   ```
+   faostat_search_codes(domain_code='EM', dimension_id='element', query='per capita')
+   faostat_search_codes(domain_code='EM', dimension_id='element', query='share CO2eq')
+   ```
+   Use the returned codes (e.g. `7279` for per capita, `726313` for share) in the data call:
    ```
    faostat_get_data(
      domain_code='EM',
      area='<area_code>',
-     element='7231,723112',                # Share in total (%), per capita (kg CO2eq)
+     item='6518',                          # Agrifood systems total
+     element='<per_capita_code>,<share_code>',
      year='2019,2020,2021,2022,2023',
      response_format='compact'
    )
@@ -119,12 +142,17 @@ If the question does not clearly match one sub-workflow, present the five option
      response_format='compact'
    )
    ```
-4. Pull emissions indicators from the **EM** domain for all entities:
+4. Resolve EM element codes at runtime, then pull indicators for all entities:
+   ```
+   faostat_search_codes(domain_code='EM', dimension_id='element', query='per capita')
+   faostat_search_codes(domain_code='EM', dimension_id='element', query='share CO2eq')
+   ```
    ```
    faostat_get_data(
      domain_code='EM',
      area='<code1>,<code2>,...',
-     element='7231,723112',
+     item='6518',                          # Agrifood systems total
+     element='<per_capita_code>,<share_code>',
      year='2019,2020,2021,2022,2023',
      response_format='compact'
    )
@@ -213,6 +241,7 @@ If the question does not clearly match one sub-workflow, present the five option
 - **Always pass an `element` filter to `faostat_get_data`.** Emissions domains return dozens of sub-elements per year and the payload explodes without one.
 - **Always pass an explicit comma-separated `year` list.** Colon ranges like `'2014:2023'` have returned empty in practice.
 - Always include the source attribution line at the end of any output.
+- **Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
 
 ## Error Handling and Reliability Notes
 

package/skills/commodity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, sugar, cotton, palm oil, production rankings, top producers, yield, trade, global supply, briefing, deep dive. Do NOT use for side-by-side entity comparison → `faostat-compare`. Do NOT use for a country food security profile → `faostat-country-profile`. Do NOT use for trend ranking across commodities → `faostat-trends`.
+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, sugar, cotton, palm oil, production rankings, top producers, yield, trade, global supply, briefing, deep dive. Do NOT use for side-by-side entity comparison → `faostat-compare`. Do NOT use for a country food security profile → `faostat-country-profile`. Do NOT use for trend ranking across commodities → `faostat-trends`.
 ---
 
 # Commodity Deep Dive
@@ -75,10 +75,11 @@ faostat_get_rankings(
 **If `faostat_get_rankings` returns an HTTP 500 or other error** (this happens — the endpoint is intermittently unreliable), fall back to pulling all countries via `faostat_get_data` and sorting client-side:
 
 ```
+# Resolve element at runtime: faostat_search_codes(domain_code='QCL', dimension_id='element', query='production') → e.g. 2510
 faostat_get_data(
   domain_code='QCL',
   item='<item_code>',
-  element='2510',           # FILTER code for Production
+  element='<resolved_production_code>',
   year='<recent_year>',
   response_format='compact',
   limit=300,                # cover all reporter countries
@@ -92,6 +93,8 @@ Then sort the returned rows by value descending and take the top 10. Exclude reg
 
 **Important code-system note:** `faostat_get_rankings` uses DISPLAY element codes (Production = `5510`). `faostat_get_data` uses FILTER element codes (Production = `2510`, Area harvested = `2312`, Yield = `2413`). These are different code systems — don't mix them.
 
+> Element codes above are verified hints. Resolve at runtime via `faostat_search_codes` before use.
+
 ### Step 4: Pull annual yield, production, and area series for the top 5
 
 For each of the top 5 producers from Step 3, pull a full 10-year annual series rather than just endpoints. This is worth the extra rows because year-to-year volatility (droughts, disease outbreaks, policy shocks) is part of the story and a 2-point comparison can hide it.
@@ -99,19 +102,24 @@ For each of the top 5 producers from Step 3, pull a full 10-year annual series r
 Three calls, each for the top-5 area codes as a comma-separated list:
 
 ```
+# Resolve elements at runtime:
+# faostat_search_codes(domain_code='QCL', dimension_id='element', query='production') → e.g. 2510
+# faostat_search_codes(domain_code='QCL', dimension_id='element', query='area harvested') → e.g. 2312
+# faostat_search_codes(domain_code='QCL', dimension_id='element', query='yield') → e.g. 2413
+
 # Production
 faostat_get_data(domain_code='QCL', area='<top5_area_codes>', item='<item_code>',
-                 element='2510', year='2014:2023', response_format='compact',
+                 element='<resolved_production_code>', year='2014:2023', response_format='compact',
                  limit=100, show_unit=True)
 
 # Area harvested
 faostat_get_data(domain_code='QCL', area='<top5_area_codes>', item='<item_code>',
-                 element='2312', year='2014:2023', response_format='compact',
+                 element='<resolved_area_harvested_code>', year='2014:2023', response_format='compact',
                  limit=100, show_unit=True)
 
 # Yield
 faostat_get_data(domain_code='QCL', area='<top5_area_codes>', item='<item_code>',
-                 element='2413', year='2014:2023', response_format='compact',
+                 element='<resolved_yield_code>', year='2014:2023', response_format='compact',
                  limit=100, show_unit=True)
 ```
 
@@ -122,15 +130,19 @@ Update the year window if you used a different reference year in Step 3 (aim for
 **Use the `TCL` domain** (Trade — Crops and Livestock Products) for aggregate country-level import and export totals. TCL gives you each country's total exports and total imports of the commodity as single rows — which is what you need for a top-exporters and top-importers table.
 
 ```
-# Top exporters by value (or switch to quantity element 5910)
+# Resolve elements at runtime:
+# faostat_search_codes(domain_code='TCL', dimension_id='element', query='export value') → e.g. 5922
+# faostat_search_codes(domain_code='TCL', dimension_id='element', query='import value') → e.g. 5622
+
+# Top exporters by value (or switch to quantity element resolved via faostat_search_codes)
 faostat_get_data(domain_code='TCL', item='<item_code>',
-                 element='5922',      # Export Value (USD 1000)
+                 element='<resolved_export_value_code>',
                  year='<recent_year>', response_format='compact',
                  limit=200, show_unit=True)
 
 # Top importers
 faostat_get_data(domain_code='TCL', item='<item_code>',
-                 element='5622',      # Import Value (USD 1000)
+                 element='<resolved_import_value_code>',
                  year='<recent_year>', response_format='compact',
                  limit=200, show_unit=True)
 ```
@@ -148,8 +160,9 @@ Based on the classification from Step 2, pull one additional dataset:
 **Food staple — Consumption & Food Security:** pull Food Balance Sheet data via the `FBS` domain. Look for food supply (kg/capita/yr), calories (kcal/capita/day), and protein (g/capita/day) at the world level plus the top 5 producer/consumer countries.
 
 ```
+# Resolve element at runtime: faostat_search_codes(domain_code='FBS', dimension_id='element', query='food supply') → e.g. 645 / 664 / 674
 faostat_get_data(domain_code='FBS', item='<fbs_item_code>',
-                 element='<645 or 664 or 674>', year='<recent_year>',
+                 element='<resolved_food_supply_code>', year='<recent_year>',
                  response_format='compact', limit=50, show_unit=True)
 ```
 
@@ -158,8 +171,9 @@ You'll need to resolve the FBS item code separately via `faostat_search_codes(do
 **Cash crop — Price Dynamics:** pull producer-price series via the `PP` domain for the top 5 producers over the last 5 years. Report year-over-year changes and note any recent shocks.
 
 ```
+# Resolve element at runtime: faostat_search_codes(domain_code='PP', dimension_id='element', query='producer price') → e.g. 5532
 faostat_get_data(domain_code='PP', area='<top5_area_codes>', item='<item_code>',
-                 element='5532',           # Producer Price, USD/tonne
+                 element='<resolved_producer_price_code>',
                  year='<5yr_range>', response_format='compact',
                  limit=100, show_unit=True)
 ```
@@ -217,6 +231,10 @@ End the briefing with a methodology footer and source line:
 
 Do not omit the source line — it's how users verify figures and know when the data was pulled.
 
+## Important Rules
+
+**Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
+
 ## Error handling and reliability notes
 
 - **`faostat_get_rankings` returns HTTP 500 intermittently.** This is the most common failure you'll hit. The Step 3 fallback (pull all countries with `faostat_get_data` and sort client-side) is the documented workaround. Don't spend many retries on the rankings endpoint — try once, fall back, and move on.

package/skills/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: faostat-compare
-description: Use ONLY when the user explicitly asks to compare two or more specific named entities (countries, commodities, or regions) side by side. Keywords: compare, comparison, versus, vs, benchmark, countries, crops, production, yield, area harvested, trade, growth rate. Do NOT use for a global commodity briefing → `faostat-commodity`. Do NOT use for a country food security profile → `faostat-country-profile`. Do NOT use for trend ranking (fastest growing/declining) → `faostat-trends`. Do NOT use for import dependency or supply chain risk → `faostat-trade`.
+description: Use ONLY when the user explicitly asks to compare two or more specific named entities (countries, commodities, or regions) side by side. Keywords — compare, comparison, versus, vs, benchmark, countries, crops, production, yield, area harvested, trade, growth rate. Do NOT use for a global commodity briefing → `faostat-commodity`. Do NOT use for a country food security profile → `faostat-country-profile`. Do NOT use for trend ranking (fastest growing/declining) → `faostat-trends`. Do NOT use for import dependency or supply chain risk → `faostat-trade`.
 ---
 
 # Comparative Agricultural Analysis
@@ -34,6 +34,9 @@ Determine from the user's message (or ask if unclear):
    - Agrifood emissions: **GT**; temperature change: **ET**; land use: **RL**
 
 Map the metric to the correct FAOSTAT element FILTER codes:
+
+> Element codes below are verified hints. Resolve at runtime via `faostat_search_codes` before use.
+
 - Production (QCL): `'2510'`
 - Yield (QCL): `'2413'`
 - Area harvested (QCL): `'2312'`
@@ -60,7 +63,7 @@ For each entity combination, call `faostat_get_data` with:
 - `domain_code='<domain>'`
 - `area='<area_code>'` (or comma-separated codes if comparing multiple countries for one item)
 - `item='<item_code>'` (or comma-separated codes if comparing multiple items)
-- `element='<element_filter_code>'`
+- `element='<element_filter_code>'` — resolve first: `faostat_search_codes(domain_code='<domain>', dimension_id='element', query='<metric name>')` → use the returned FILTER code; reference hints in Step 1 to validate
 - `year='2014,2015,2016,2017,2018,2019,2020,2021,2022,2023'` — use an **explicit comma-separated year list**. Colon ranges like `'2014:2023'` have returned empty in practice; avoid them.
 - `response_format='compact'` (saves tokens for multi-entity queries)
 - `limit=200` (increase limit for multi-year, multi-entity queries)
@@ -103,6 +106,10 @@ End with:
 
 > Source: FAOSTAT (FAO), accessed [current date].
 
+## Important Rules
+
+**Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
+
 ## Error Handling
 
 - If data is missing for some years for an entity, note the gap and compute metrics on available data only.

package/skills/country-profile/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: faostat-country-profile
-description: Use when the user asks for a food security profile, country agricultural overview, country hunger or nutrition assessment, or food system summary for a specific country. Keywords: country profile, food security, undernourishment, production, trade, nutrition, calorie supply, dietary energy. Do NOT use for import dependence and supply chain risk → `faostat-trade`. Do NOT use for a global commodity briefing → `faostat-commodity`. Do NOT use for side-by-side country comparison → `faostat-compare`.
+description: Use when the user asks for a food security profile, country agricultural overview, country hunger or nutrition assessment, or food system summary for a specific country. Keywords — country profile, food security, undernourishment, production, trade, nutrition, calorie supply, dietary energy. Do NOT use for import dependence and supply chain risk → `faostat-trade`. Do NOT use for a global commodity briefing → `faostat-commodity`. Do NOT use for side-by-side country comparison → `faostat-compare`.
 ---
 
 # Country Food Security Profile
@@ -29,6 +29,8 @@ If any tool is missing, inform the user: "This skill requires the FAOSTAT MCP se
 
 ## Element Code Reference
 
+> Element codes below are verified hints. Resolve at runtime via `faostat_search_codes` before use.
+
 - **Production quantity (QCL)**: filter `2510`, display `5510`
 - **Import quantity (TCL)**: filter `2610`; **Export quantity (TCL)**: filter `2910`
 - **Import value (TCL, USD 1000)**: filter `2612`; **Export value (TCL, USD 1000)**: filter `2912`
@@ -61,7 +63,7 @@ Store the confirmed `area` code for all subsequent queries.
 Call `faostat_get_data` with:
 - `domain_code='QCL'`
 - `area='<resolved_area_code>'`
-- `element='2510'` (Production — this is the FILTER code)
+- `element='<resolved_production_code>'` — resolve at runtime: `faostat_search_codes(domain_code='QCL', dimension_id='element', query='production quantity')` → e.g. `2510` (Production — this is the FILTER code)
 - `year='<most_recent_year>'` (try the current year minus 2; if no data, try minus 3)
 - `response_format='compact'`
 - `limit=20`
@@ -74,7 +76,7 @@ Sort the results by value descending and identify the **top 5 crops by productio
 Call `faostat_get_data` with specific element filters so the payload stays small:
 - `domain_code='FS'`
 - `area='<resolved_area_code>'`
-- `element='210041,210011'` (prevalence of undernourishment, number undernourished). Add other FS element codes if needed — resolve via `faostat_search_codes(domain_code='FS', dimension_id='element', query='...')`.
+- `element='<resolved_fs_codes>'` — resolve at runtime: `faostat_search_codes(domain_code='FS', dimension_id='element', query='undernourishment')` → e.g. `210041,210011` (prevalence of undernourishment, number undernourished). Add other FS element codes if needed — resolve via `faostat_search_codes(domain_code='FS', dimension_id='element', query='...')`.
 - `year='2014,2015,2016,2017,2018,2019,2020,2021,2022,2023'` (use explicit comma list — colon ranges like `'2014:2023'` have returned empty in practice)
 - `response_format='compact'`
 
@@ -91,7 +93,7 @@ If data is sparse, note which indicators are unavailable.
 Call `faostat_get_data` with:
 - `domain_code='FBS'`
 - `area='<resolved_area_code>'`
-- `element='664,674,684,645'` (kcal/cap/day, protein g/cap/day, fat g/cap/day, food kg/cap/yr)
+- `element='<resolved_fbs_codes>'` — resolve at runtime: `faostat_search_codes(domain_code='FBS', dimension_id='element', query='food supply kcal')` and similar queries for protein/fat → e.g. `664,674,684,645` (kcal/cap/day, protein g/cap/day, fat g/cap/day, food kg/cap/yr)
 - `year='<latest 2-3 years available — FBS typically lags QCL by 1 year>'`
 - `item='2901'` (Grand Total for headline metrics); for item-specific breakdown (e.g., wheat contribution) resolve via `faostat_search_codes`
 - `response_format='compact'`
@@ -106,11 +108,16 @@ Extract:
 ### Step 6: Pull Trade Summary (TCL, not TM)
 
 Use **TCL** (country-level aggregate trade) for total imports and exports:
-```
+```python
+# Resolve elements at runtime:
+# faostat_search_codes(domain_code='TCL', dimension_id='element', query='import quantity') → e.g. 2610
+# faostat_search_codes(domain_code='TCL', dimension_id='element', query='export quantity') → e.g. 2910
+# faostat_search_codes(domain_code='TCL', dimension_id='element', query='import value') → e.g. 2612
+# faostat_search_codes(domain_code='TCL', dimension_id='element', query='export value') → e.g. 2912
 faostat_get_data(
   domain_code='TCL',
   area='<resolved_area_code>',
-  element='2610,2910,2612,2912',    # import qty, export qty, import value, export value
+  element='<resolved_import_qty>,<resolved_export_qty>,<resolved_import_val>,<resolved_export_val>',
   year='<latest 3 years>',
   response_format='compact',
   limit=500
@@ -149,6 +156,10 @@ End the report with:
 
 > Source: FAOSTAT (FAO), accessed [current date]. Data may reflect reporting lags of 1-3 years.
 
+## Important Rules
+
+**Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
+
 ## Error Handling
 
 - If a domain returns no data for the country, note it in the report and continue with available data.

package/skills/explore/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: faostat-explore
-description: Use when the user wants to discover what data is available in FAOSTAT, browse domains, understand what a domain contains, or is new to FAOSTAT and wants a guided tour. Use when the user mentions a topic and wants to know what FAOSTAT data covers it. Keywords: explore, discover, browse, what data, available, domains, catalog, tour, overview, what can I find, show me, help me understand, new to FAOSTAT, getting started
+description: Use when the user wants to discover what data is available in FAOSTAT, browse domains, understand what a domain contains, or is new to FAOSTAT and wants a guided tour. Use when the user mentions a topic and wants to know what FAOSTAT data covers it. Keywords — explore, discover, browse, what data, available, domains, catalog, tour, overview, what can I find, show me, help me understand, new to FAOSTAT, getting started
 ---
 
 # FAOSTAT Explorer
@@ -110,6 +110,10 @@ If the user wants to query, use `faostat_search_codes` to resolve any entity nam
 
 **Important:** Element FILTER codes differ from DISPLAY codes. When calling `faostat_get_data`, use the filter code for the `element` parameter. When calling `faostat_get_rankings`, use the DISPLAY code. If unsure, use `faostat_search_codes` with `dimension_id='element'` to find the correct code.
 
+## Important Rules
+
+**Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
+
 ### Step 7 — Attribution
 
 When presenting any data, always include:

package/skills/export-dataset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: faostat-export-dataset
-description: Use when the user wants a clean, documented tabular export of FAOSTAT data — "export FAOSTAT", "download the data", "give me the CSV / xlsx of [indicator]", "I want the raw numbers", "tabular data pull", "export to spreadsheet". The deliverable is a bundle: one multi-sheet .xlsx (README / Data_tidy / Data_wide / Methodology / Sources) + one tidy-long .csv mirror + a data-dictionary .md. No prose, no charts, no narrative — just the data with full provenance. Do NOT use for reports, briefs, papers, infographics, or visualisations — those skills embed their own xlsx appendices. Use this skill when the data itself IS the deliverable.
+description: Use when the user wants a clean, documented tabular export of FAOSTAT data — "export FAOSTAT", "download the data", "give me the CSV / xlsx of [indicator]", "I want the raw numbers", "tabular data pull", "export to spreadsheet". The deliverable is a bundle — one multi-sheet .xlsx (README / Data_tidy / Data_wide / Methodology / Sources) + one tidy-long .csv mirror + a data-dictionary .md. No prose, no charts, no narrative — just the data with full provenance. Do NOT use for reports, briefs, papers, infographics, or visualisations — those skills embed their own xlsx appendices. Use this skill when the data itself IS the deliverable.
 ---
 
 # FAOSTAT Data Export
@@ -24,12 +24,14 @@ Cross-skill invariants (all six — violations are skill bugs):
 5. **China composite default (Apr 2026 user preference).** Default: composite `China` (area 351). `China, mainland` (41) is an opt-in; full disaggregation (41 + 96 + 128 + 214) is also opt-in. Record the choice in the README sheet with the FAOSTAT-default-41 caveat.
 6. **`faostat_get_rankings` HTTP-500 fallback.** On failure, reconstruct by pulling `faostat_get_data` across all reporting countries and sorting client-side. Note the fallback in Methodology.
 
+7. **Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.
+
 Export-specific invariants:
 
-7. **Every value traces to an API call.** The Methodology sheet logs one row per `faostat_get_data` call with domain / area / element / item / year list / timestamp / rows-returned. No value appears in the export that did not come from a documented call.
-8. **FAO-native units kept as-is.** No auto-conversion. Values stay in FAOSTAT's native units (kt CO₂eq, tonnes, USD 1000, etc.). Unit is a column in tidy-long and a header row in wide. If the user explicitly asks for normalised units, add normalised columns **alongside** the native ones — never in place of.
-9. **No FAO branding.** No FAO logo, "Food and Agriculture Organization of the United Nations" masthead, ISSN, "FAO Statistics Division" stamp, or "Required citation: FAO. …" line. CC-BY-4.0 attribution to FAOSTAT (source, licence, access date) IS kept — that's a property of the source data.
-10. **Both shapes in the xlsx.** `Data_tidy` (long) and `Data_wide` (years-as-columns pivot) are both always present. The CSV mirror is tidy-long only. A wide CSV is produced only if the user asks.
+8. **Every value traces to an API call.** The Methodology sheet logs one row per `faostat_get_data` call with domain / area / element / item / year list / timestamp / rows-returned. No value appears in the export that did not come from a documented call.
+9. **FAO-native units kept as-is.** No auto-conversion. Values stay in FAOSTAT's native units (kt CO₂eq, tonnes, USD 1000, etc.). Unit is a column in tidy-long and a header row in wide. If the user explicitly asks for normalised units, add normalised columns **alongside** the native ones — never in place of.
+10. **No FAO branding.** No FAO logo, "Food and Agriculture Organization of the United Nations" masthead, ISSN, "FAO Statistics Division" stamp, or "Required citation: FAO. …" line. CC-BY-4.0 attribution to FAOSTAT (source, licence, access date) IS kept — that's a property of the source data.
+11. **Both shapes in the xlsx.** `Data_tidy` (long) and `Data_wide` (years-as-columns pivot) are both always present. The CSV mirror is tidy-long only. A wide CSV is produced only if the user asks.
 
 ## Workflow
 
@@ -38,7 +40,7 @@ Export-specific invariants:
 Required from the user (prompt via `AskUserQuestion` in Cowork, inline otherwise):
 
 - **Domain** — e.g., GT, QCL, TCL, ET, PP, FBS, FS.
-- **Element(s)** — FILTER code(s).
+- **Element(s)** — FILTER code(s). If the user supplies a name rather than a code, resolve via `faostat_search_codes` (invariant 7) before use.
 - **Year range** — list of years (will be passed comma-separated).
 - **Area scope** — World, specific regions, specific country list, or "all reporting countries". Default if unspecified: all reporting countries plus regional aggregates (5000/5100/5200/5300/5400/5500).
 
@@ -51,7 +53,7 @@ Optional:
 
 ### Step 2 — Resolve codes
 
-If the user gave names rather than codes, call `faostat_search_codes(domain_code=…, dimension_id='item'|'area', query=…)`. Print the resolved codes back in a short confirmation block before the heavy pull so mismatches surface early.
+Always resolve element and item codes at runtime before the data pull (invariant 7). Call `faostat_search_codes(domain_code=…, dimension_id='element'|'item'|'area', query=…)` for every numeric code needed — even when the user supplies a code directly, verify it matches. Print the resolved codes back in a short confirmation block before the heavy pull so mismatches surface early.
 
 ### Step 3 — Pull data