faostat-skills 0.1.0

package/skills/trends/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: faostat-trends
+description: Use when the user wants to identify biggest changes, fastest-growing or declining agricultural productions, or anomalies in FAOSTAT data over a time window for a region or set of countries. Keywords: trends, growth, decline, anomaly, change, biggest movers, acceleration, deceleration, monitoring, shift, surge, drop, spike
+---
+
+# Agricultural Trend Monitor
+
+Identify the biggest changes and anomalies in agricultural production data over a specified time window and geography.
+
+## Prerequisites
+
+Before starting, confirm the FAOSTAT MCP tools are available by checking that tools `faostat_get_data`, `faostat_search_codes`, and `faostat_get_rankings` are accessible. If they are not, inform the user that this skill requires the FAOSTAT MCP server to be connected and stop.
+
+## Workflow
+
+### Step 1 — Gather Parameters
+
+Ask the user for:
+- **Region or countries** — one or more countries, a continent, or a region (e.g., "Africa", "Brazil and Argentina", "Southeast Asia")
+- **Time window** — default to the last 5 years if not specified
+- **Focus** (optional) — specific commodity groups to monitor, or leave broad for all major groups
+
+If the user provides these in their initial message, proceed without re-asking.
+
+### Step 2 — Resolve Area Codes
+
+Use `faostat_search_codes` with `domain_code='QCL'` and `dimension_id='area'` to resolve each country or region name to its FAOSTAT area code.
+
+**CRITICAL:** If `requires_confirmation` is `true` in the response (multiple matches), present the options to the user and ask them to choose before proceeding. Do NOT guess.
+
+### Step 3 — Pull Production Data for Major Commodity Groups
+
+Query the **QCL** (Crops and Livestock Products) domain using `faostat_get_data`. Pull production quantity data (element filter code `'5510'`) across major commodity groups.
+
+For broad monitoring, query across these key items:
+- Cereals (wheat, rice, maize, barley, sorghum, millet)
+- Oilcrops (soybeans, palm fruit, sunflower seed, rapeseed)
+- Roots and tubers (cassava, potatoes, yams, sweet potatoes)
+- Fruits (bananas, citrus, mangoes, avocados)
+- Vegetables (tomatoes, onions)
+- Livestock products (milk, meat — cattle, chicken, pig, sheep)
+
+Use `faostat_search_codes` with `domain_code='QCL'` and `dimension_id='item'` to resolve each item name to its item code.
+
+For each query, use `response_format='compact'` when pulling data for multiple entities to keep payloads efficient. Set `limit` appropriately to cover the full time window.
+
+**Important:** Element FILTER codes differ from DISPLAY codes. When calling `faostat_get_data`, use the filter code for the `element` parameter. Production quantity filter code is `'5510'`. If you need to look up the correct filter code, use `faostat_search_codes` with `dimension_id='element'`.
+
+### Step 4 — Calculate Period-over-Period Changes
+
+For each country-commodity pair:
+1. Identify the **baseline value** (first year or average of first 2 years in the window)
+2. Identify the **latest value** (most recent year or average of last 2 years)
+3. Calculate:
+   - **Absolute change** = latest - baseline
+   - **Percentage change** = ((latest - baseline) / baseline) * 100
+   - **Annualized growth rate** = ((latest / baseline)^(1/years) - 1) * 100
+
+Exclude any country-commodity pairs where baseline data is zero or missing.
+
+### Step 5 — Rank by Magnitude
+
+Sort all country-commodity pairs by:
+- **Percentage change** (descending) for top growers
+- **Percentage change** (ascending) for top decliners
+
+Select:
+- **Top 5 fastest-growing** productions (highest positive percentage change)
+- **Top 5 largest declines** (most negative percentage change)
+
+### Step 6 — Flag Anomalies
+
+For each country-commodity time series:
+1. Calculate the mean and standard deviation of annual values across the time window
+2. Flag any year where the value deviates by more than 2 standard deviations from the mean
+3. Note the direction (spike up or drop down) and the year
+
+An anomaly could indicate a drought, bumper harvest, policy change, conflict, or data issue.
+
+### Step 7 — Compile the Trend Report
+
+Present the results in a structured format:
+
+**Top 5 Growing Productions**
+For each entry: country, commodity, baseline value, latest value, percentage change, annualized growth rate. Add a brief note on possible drivers if context is evident.
+
+**Top 5 Declining Productions**
+Same format as above. Flag any that may indicate food security concerns.
+
+**Anomaly Flags**
+For each anomaly: country, commodity, year, actual value vs. expected range, direction (spike/drop). Note if additional investigation is warranted.
+
+**Trend Directions Summary**
+A concise table showing all analyzed country-commodity pairs with trend direction indicators:
+- Strong growth (>20% over period)
+- Moderate growth (5-20%)
+- Stable (-5% to +5%)
+- Moderate decline (-5% to -20%)
+- Sharp decline (>20% decline)
+
+### Step 8 — Attribution
+
+End the report with:
+
+> Source: FAOSTAT (FAO), accessed [current date]. Domain: QCL (Crops and Livestock Products).
+
+Replace `[current date]` with today's date.
+
+### Step 9 — Offer Next Steps
+
+Suggest to the user:
+- "Would you like me to visualize any of these trends as charts?" (invokes the visualization skill)
+- "Want a deeper dive into any specific commodity or country?" (invokes the commodity or country-profile skill)
+- "Should I check the trade data for any of the anomalies?" (invokes the trade skill)

package/skills/viz/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: faostat-viz
+description: Use when the user asks to visualize, chart, graph, or plot FAOSTAT data, or when they want a visual representation of agricultural statistics. Also use when another skill needs to produce a chart. Keywords: chart, graph, plot, visualize, visualization, bar chart, line chart, scatter plot, stacked bar, HTML, interactive, Chart.js, trend chart, comparison chart
+---
+
+# FAOSTAT Data Visualizer
+
+Generate interactive, standalone HTML charts from FAOSTAT data. Charts use Chart.js via CDN and are designed to be self-contained, responsive, accessible, and properly attributed.
+
+## Prerequisites
+
+Before starting, verify that the FAOSTAT MCP tools are available: `faostat_search_codes`, `faostat_get_data`. If they are not available and the user has not provided data in the conversation context, inform the user they need the FAOSTAT MCP server configured and stop.
+
+If data is already available in the conversation context (e.g., from a previous query or another skill), skip directly to chart generation.
+
+## Chart Type Selection
+
+Choose the chart type based on the data relationship. If the user does not specify a chart type, select the most appropriate one:
+
+| Data Relationship | Chart Type | When to Use |
+|-------------------|------------|-------------|
+| Values over time | **Line chart** | Trends, time series, historical data |
+| Values across categories | **Bar chart** | Comparing countries, commodities, or regions |
+| Composition breakdown | **Stacked bar chart** | Shares of a total (e.g., emissions by source, trade by partner) |
+| Two-variable relationship | **Scatter plot** | Correlations (e.g., fertilizer use vs. emissions) |
+
+Do NOT use pie charts. They are difficult to read with more than 3-4 categories and do not convey FAOSTAT data well.
+
+## Workflow
+
+### Step 1: Determine data source
+
+Check if usable data already exists in the conversation context:
+- If YES: extract the relevant data points (values, labels, years, units) and proceed to Step 4.
+- If NO: proceed to Step 2 to query FAOSTAT.
+
+### Step 2: Query data (if needed)
+
+1. Ask the user what they want to visualize if not clear from context:
+   - What metric? (production, yield, trade volume, emissions, etc.)
+   - Which entities? (countries, commodities, regions)
+   - What time range?
+
+2. Resolve all codes using `faostat_search_codes`:
+   - Resolve area codes: `faostat_search_codes(domain_code='<domain>', dimension_id='area', query='<name>')`
+   - Resolve item codes: `faostat_search_codes(domain_code='<domain>', dimension_id='item', query='<name>')`
+   - Handle `requires_confirmation` for every search -- present options and wait for user choice.
+
+3. Pull data using `faostat_get_data`:
+   ```
+   faostat_get_data(
+     domain_code='<domain>',
+     area='<codes>',
+     item='<codes>',
+     element='<filter_code>',
+     response_format='compact'
+   )
+   ```
+
+### Step 3: Prepare data
+
+Extract from the query results:
+- **Labels**: years (for time series) or entity names (for comparisons)
+- **Datasets**: one dataset per series (e.g., one per country in a multi-country comparison)
+- **Values**: numeric data points
+- **Units**: the unit of measurement (tonnes, hectares, gigagrams CO2eq, etc.)
+- **Title elements**: what is being shown, for whom, over what period
+
+### Step 4: Generate the HTML chart
+
+Create a standalone HTML file with the following structure and requirements:
+
+**Color Palette (colorblind-friendly -- use these in order):**
+```
+#2196F3 (blue)
+#FF9800 (orange)
+#4CAF50 (green)
+#E91E63 (pink)
+#9C27B0 (purple)
+#00BCD4 (cyan)
+#FF5722 (deep orange)
+#795548 (brown)
+#607D8B (blue-grey)
+#CDDC39 (lime)
+```
+
+**HTML Template Requirements:**
+- DOCTYPE html with UTF-8 charset and viewport meta tag
+- Chart.js loaded from CDN: `https://cdn.jsdelivr.net/npm/chart.js`
+- A single `<canvas>` element for the chart
+- Responsive: chart container should be `max-width: 900px; margin: 0 auto;`
+- Chart must fill its container with `responsive: true` and `maintainAspectRatio: false`
+- Chart container height: at least 500px
+- Clean background: white or very light grey (#fafafa)
+
+**Chart Configuration Requirements:**
+- **Title**: descriptive, includes what is measured, for whom, and the time period. Use Chart.js plugin title: `plugins: { title: { display: true, text: '<title>', font: { size: 16 } } }`
+- **Axes**: both axes must be labeled. Y-axis label must include the unit of measurement (e.g., "Production (tonnes)", "Emissions (Gg CO2eq)"). Use `scales: { x: { title: { display: true, text: '...' } }, y: { title: { display: true, text: '...' } } }`
+- **Legend**: display with `plugins: { legend: { display: true, position: 'top' } }`
+- **Tooltips**: enabled by default in Chart.js, ensure they show the value with appropriate precision
+- **Data labels**: for bar charts with few bars (< 6), consider adding value labels
+
+**Source Attribution (REQUIRED):**
+Add a footer below the chart canvas:
+```html
+<p style="text-align: center; color: #666; font-size: 12px; margin-top: 10px;">
+  Source: FAOSTAT (FAO), accessed [current date]
+</p>
+```
+
+**Line Chart Specifics:**
+- Use `tension: 0.3` for slightly smoothed lines
+- Use `pointRadius: 3` for visible but not overwhelming data points
+- Set `fill: false` unless showing area comparison
+
+**Bar Chart Specifics:**
+- Use `borderWidth: 1` with a slightly darker border color
+- For grouped bars (multiple datasets), ensure `barPercentage` and `categoryPercentage` provide adequate spacing
+- For horizontal bars, swap x and y axis configurations with `indexAxis: 'y'`
+
+**Stacked Bar Specifics:**
+- Set `scales: { x: { stacked: true }, y: { stacked: true } }`
+- Use distinct colors from the palette for each stack segment
+
+**Scatter Plot Specifics:**
+- Use `pointRadius: 5` for visibility
+- Add axis labels that clearly identify the two variables
+- Consider adding a trend line if correlation is being demonstrated
+
+### Step 5: Save and offer to open
+
+1. Save the HTML file to a meaningful filename:
+   - Format: `faostat-<subject>-<chart-type>.html`
+   - Examples: `faostat-wheat-production-trends-line.html`, `faostat-emissions-comparison-bar.html`
+   - Save in the current working directory unless the user specifies otherwise.
+
+2. Tell the user the file path and offer to open it in their default browser:
+   - On macOS: `open <filepath>`
+   - On Linux: `xdg-open <filepath>`
+   - On Windows: `start <filepath>`
+
+### Step 6: Describe the chart
+
+Provide a brief text description of what the chart shows:
+- The main trend or comparison visible
+- Any notable outliers or patterns
+- What conclusions can be drawn
+
+This ensures the insight is captured even if the user cannot view the chart immediately.
+
+## Important Rules
+
+- Always use `faostat_search_codes` before `faostat_get_data` to resolve codes. Never guess or hardcode codes.
+- When `requires_confirmation` is true in a search result, always present options and wait for the user to choose.
+- Use `response_format='compact'` for queries with multiple entities or time ranges.
+- For `faostat_get_data`, use FILTER element codes (e.g., '2510'). For `faostat_get_rankings`, use DISPLAY element codes (e.g., '5510').
+- Every chart MUST include source attribution: "Source: FAOSTAT (FAO), accessed [current date]"
+- Use the colorblind-friendly palette defined above. Do not use default Chart.js colors.
+- The HTML file must be fully standalone -- no external dependencies except the Chart.js CDN.
+- Always include the source attribution line at the end of any text output as well.