faostat-skills 0.2.2 → 0.2.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "source": {
         "source": "npm",
         "package": "faostat-skills",
-        "version": "^0.2.0"
+        "version": "0.2.4"
       },
       "description": "AI skills for analyzing UN FAOSTAT food & agriculture data — country profiles, trade analysis, climate assessments, commodity briefings, maps, infographics, and more."
     }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.2.4",
   "author": {
     "name": "Griffiths Obli-Laryea"
   },

package/README.md

@@ -17,7 +17,10 @@ AI-powered analysis skills for the [UN FAOSTAT](https://www.fao.org/faostat/en/#
 /plugin marketplace add berba-q/faostat-skills
 
 # 2. Install
-claude plugin install faostat-skills@faostat
+/plugin install faostat-skills@faostat
+
+# 3. Activate
+/reload-plugins
 ```
 
 **OpenAI Codex**
@@ -61,10 +64,7 @@ Claude Code uses a marketplace model. Add this repo as a marketplace source once
 claude plugin install faostat-skills@faostat
 ```
 
-To update to a new version later:
-```bash
-claude plugin update faostat-skills@faostat
-```
+Updates are automatic — Claude Code checks for new versions at startup and updates in the background. Run `/reload-plugins` to activate the latest version in your current session.
 
 ### OpenAI Codex
 
@@ -168,30 +168,38 @@ Key domains used by these skills:
 ```
 FAOSTAT Skills (this repo)          FAOSTAT MCP Server (separate)
 ┌────────────────────────┐          ┌────────────────────────┐
-│ 9 platform-agnostic    │  uses    │ 21 MCP tools           │
+│ 14 platform-agnostic   │  uses    │ 21 MCP tools           │
 │ SKILL.md workflows     │────────→ │ Published on PyPI      │
-│                        │          │ v1.2.2 · stable        │
+│                        │          │ faostat-mcp · stable   │
 └────────────────────────┘          └────────────────────────┘
 ```
 
+**Two distribution channels — keep both in sync:**
+- **Claude Code**: served from GitHub (`berba-q/faostat-skills`) via the marketplace. Push to GitHub → users get the update automatically at next startup.
+- **npm / Codex**: served from npm (`faostat-skills`). Run `npm publish` → Codex users update with `npm install -g faostat-skills@latest`.
+
 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/
+├── skills/                     ← Core: 14 platform-agnostic SKILL.md files
+│   ├── country-profile/        ← Tier 1: analysis
 │   ├── compare/
 │   ├── commodity/
 │   ├── trade/
 │   ├── trends/
 │   ├── climate/
-│   ├── viz/
+│   ├── explore/
+│   ├── viz/                    ← Tier 2: outputs
+│   ├── map/
+│   ├── infographic/
 │   ├── story/
-│   └── explore/
+│   ├── analytical-brief/
+│   ├── scientific-paper/
+│   └── export-dataset/         ← Tier 3: utilities
 ├── .claude-plugin/             ← Claude Code packaging
-├── .agents/skills/             ← OpenAI Codex packaging (symlink)
 ├── commands/                   ← Claude Code slash commands
 ├── README.md
 └── LICENSE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faostat-skills",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",
@@ -30,5 +30,8 @@
     ".claude-plugin/",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "scripts": {
+    "version": "node scripts/sync-version.mjs && git add .claude-plugin/plugin.json marketplace.json .claude-plugin/marketplace.json"
+  }
 }

package/skills/analytical-brief/SKILL.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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