From pnge-economics
Query and analyze international trade data for critical minerals, petroleum, and energy commodities from the UN Comtrade database. Use this skill whenever the user asks about lithium trade flows, magnesium imports or exports, barite trade, petroleum trade between countries, critical mineral supply chains, global commodity trade volumes, import/export statistics by country, HS code lookups, or any question about which countries trade minerals and energy products. Trigger phrases: "lithium imports by country", "who exports magnesium to the US", "petroleum trade flows", "critical mineral supply chain", "trade data for barite", "UN Comtrade", "HS code trade data", "commodity imports from China", "nickel trade statistics", "uranium trade". Produces trade flow tables with value and quantity breakdowns by partner country, plus narrative analysis of supply chain concentration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pnge-economics:comtrade-mineralsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Fetches and analyzes international commodity trade data from the UN Comtrade
Fetches and analyzes international commodity trade data from the UN Comtrade API. Covers 200+ reporter countries, HS commodity codes at 2/4/6-digit granularity, annual and monthly frequencies.
The Comtrade API has two tiers:
Resolution order (stop at first success):
~/.config/comtrade/credentials (default) -- parse
subscription_key=<value> from this fileCOMTRADE_API_KEY env var -- fallback if credentials file is absent~/.config/comtrade/credentials as subscription_key=YOUR_KEY
(chmod 600)."Never hardcode or log the key. Pass it via the subscription-key query
parameter (authenticated endpoint) or omit it (public preview).
Reading the credentials file (bash):
KEY=$(grep '^subscription_key=' ~/.config/comtrade/credentials 2>/dev/null | cut -d= -f2)
[ -z "$KEY" ] && KEY="${COMTRADE_API_KEY}"
Reading the credentials file (Go):
func resolveSubscriptionKey() (string, error) {
home, _ := os.UserHomeDir()
creds := filepath.Join(home, ".config", "comtrade", "credentials")
if data, err := os.ReadFile(creds); err == nil {
for _, line := range strings.Split(string(data), "\n") {
line = strings.TrimSpace(line)
if strings.HasPrefix(line, "subscription_key=") {
return strings.TrimPrefix(line, "subscription_key="), nil
}
}
}
if key := os.Getenv("COMTRADE_API_KEY"); key != "" {
return key, nil
}
return "", fmt.Errorf("no Comtrade subscription key found")
}
Two endpoints depending on authentication state:
| Endpoint | Auth | Limits |
|---|---|---|
https://comtradeapi.un.org/public/v1/preview/C/{freq}/HS | None | 500 req/day, 1 period, no descriptions |
https://comtradeapi.un.org/data/v1/get/C/{freq}/HS | subscription-key param | Higher limits, multi-period, full metadata |
The legacy endpoint https://comtrade.un.org/api/get redirects and is no
longer functional. Always use the v1 API.
URL path structure:
/C/{freq}/HS
| | |
| | +-- classification (HS = Harmonized System)
| +-------- frequency: A = annual, M = monthly
+------------ type: C = commodities, S = services
Key query parameters:
| Parameter | Example | Notes |
|---|---|---|
reporterCode | 842 | ISO numeric country code of reporting country |
partnerCode | 156 | Trade partner (0 = World aggregate) |
cmdCode | 2825 | HS commodity code (2/4/6 digit) |
flowCode | M | M = imports, X = exports, RX = re-exports, RM = re-imports |
period | 2023 | Year (annual) or YYYYMM (monthly); comma-separated for multi (auth only) |
subscription-key | YOUR_KEY | Required for authenticated endpoint only |
See references/api_reference.md for full tables. Priority codes:
| HS Code | Description |
|---|---|
| 2825 | Hydrazine, hydroxylamine; lithium oxide and hydroxide |
| 283691 | Lithium carbonate |
| HS Code | Description |
|---|---|
| 2519 | Natural magnesium carbonate (magnesite) |
| 8104 | Magnesium and articles thereof |
| HS Code | Description |
|---|---|
| 2709 | Crude petroleum oils |
| 2710 | Petroleum oils, not crude (refined products) |
| 2711 | Petroleum gases (LNG, LPG, natural gas) |
| HS Code | Description |
|---|---|
| 2511 | Natural barium sulfate (barite) -- used in drilling muds |
| 2606 | Aluminium ores and concentrates |
| 2844 | Radioactive chemical elements (uranium) |
| 7501-7508 | Nickel and nickel articles |
| 2529 | Feldspar, fluorspar |
| Code | Country | Relevance |
|---|---|---|
| 0 | World (aggregate) | Total trade |
| 842 | United States | Reporter for US trade analysis |
| 156 | China | Major Li/Mg producer and exporter |
| 152 | Chile | Top lithium producer (brines) |
| 36 | Australia | Top lithium producer (spodumene) |
| 32 | Argentina | Lithium brine triangle |
| 76 | Brazil | Lithium, Mg, barite |
| 124 | Canada | Nickel, petroleum, critical minerals |
| 643 | Russia | Nickel, petroleum, uranium |
| 710 | South Africa | Manganese, chromium |
| 392 | Japan | Major Li consumer (batteries) |
| 410 | Republic of Korea | Major Li consumer (batteries) |
| 276 | Germany | Industrial chemicals |
| 826 | United Kingdom | Trade hub |
| 68 | Bolivia | Lithium brine resources |
Map the user's question to parameters:
references/api_reference.md for code lookups.KEY=$(grep '^subscription_key=' ~/.config/comtrade/credentials 2>/dev/null | cut -d= -f2)
[ -z "$KEY" ] && KEY="${COMTRADE_API_KEY}"
if [ -n "$KEY" ]; then
BASE="https://comtradeapi.un.org/data/v1/get/C/A/HS"
AUTH="&subscription-key=$KEY"
else
BASE="https://comtradeapi.un.org/public/v1/preview/C/A/HS"
AUTH=""
fi
Build the URL with appropriate filters:
# Example: US imports of lithium carbonate from all partners, 2023
curl -s "${BASE}?reporterCode=842&period=2023&cmdCode=283691&flowCode=M${AUTH}"
For public preview endpoint, one period at a time. Loop over years if the user needs a time series:
for YEAR in 2021 2022 2023; do
curl -s "${BASE}?reporterCode=842&period=${YEAR}&cmdCode=283691&flowCode=M"
sleep 1 # be respectful of rate limits
done
Response structure (JSON):
{
"elapsedTime": "0.14 secs",
"count": 14,
"data": [
{
"typeCode": "C",
"freqCode": "A",
"refYear": 2023,
"period": "2023",
"reporterCode": 842,
"flowCode": "M",
"partnerCode": 156,
"cmdCode": "283691",
"qtyUnitCode": 8,
"qty": 5267952.0,
"netWgt": 5267952.0,
"cifvalue": 250584381.0,
"fobvalue": 242860584.0,
"primaryValue": 250584381.0,
"isQtyEstimated": false,
"isReported": false,
"isAggregate": true
}
],
"error": ""
}
Key response fields:
| Field | Meaning |
|---|---|
partnerCode | Trade partner (0 = World total) |
qty | Quantity in units specified by qtyUnitCode |
netWgt | Net weight in kilograms |
cifvalue | CIF value in USD (cost + insurance + freight) -- import side |
fobvalue | FOB value in USD (free on board) -- export side |
primaryValue | CIF for imports, FOB for exports (the "natural" valuation) |
qtyUnitCode | 8 = kg, 1 = no quantity, others vary |
isQtyEstimated | Whether quantity was estimated (data quality flag) |
isReported | Whether this was directly reported vs mirror/estimated |
Important: The public preview endpoint returns null for
reporterISO, reporterDesc, partnerDesc, flowDesc, cmdDesc,
qtyUnitAbbr. You must map codes to names locally. See the country and HS
code tables in references/api_reference.md.
Format: Raw Data Table + Narrative
Present a markdown table of trade flows sorted by value (descending), then a narrative summary covering:
Example output structure:
## US Imports of Lithium Carbonate (HS 283691), 2023
| Partner | Value (USD) | Net Weight (kg) | $/kg | Share |
|---------------|----------------|-----------------|-------|-------|
| World Total | 250,584,381 | 16,189,607 | 15.48 | 100% |
| Chile | 216,996,017 | 5,267,952 | 41.19 | 86.6% |
| China | 12,443,422 | 381,004 | 32.66 | 5.0% |
| Argentina | 11,643,717 | 1,180,000 | 9.87 | 4.6% |
| ... | ... | ... | ... | ... |
**Summary:** The US imported $250.6M of lithium carbonate in 2023 (16,190
metric tons net weight). Chile dominates supply at 86.6% of import value,
reflecting the country's Atacama brine operations. The top-3 concentration
(Chile + China + Argentina) accounts for 96.2% of value, indicating high
supply chain concentration risk. Implied $/kg varies significantly by
origin, suggesting different product grades or contract pricing structures.
Data is from customs declarations aggregated by the UN Statistics Division;
some partner breakdowns may be estimated.
The public preview endpoint caps results (typically 500 rows). For the
authenticated endpoint, check count in the response -- if it equals the
maximum, there may be more data. Use the offset parameter (authenticated
only) to paginate if needed. In practice, single-country single-commodity
queries rarely exceed 50-100 rows.
| HTTP Code | Meaning | Action |
|---|---|---|
200 + error field non-empty | API-level error | Read error message; common: "Maximum number of periods is 1" on preview endpoint |
200 + count = 0 | No data | Widen filters (try broader HS code or different year) |
200 + count = -1 | Query error | Check parameters; usually malformed codes |
| 401 | Missing/invalid subscription key | Fall back to public preview or prompt user for key |
| 403 | Access denied | Rate limit exceeded; wait and retry or use preview endpoint |
| 404 | Endpoint not found | Verify URL path structure |
| 429 | Too many requests | Back off; respect rate limits (500/day preview, more with key) |
| 5xx | Server error | Retry after delay; Comtrade has occasional downtime |
isReported flag indicates this.qtyUnitCode = 8). Some codes use supplementary units. Always check units.bash_tool with curl + jq for API callsreferences/python_example.py
(ComtradeClient, fetch_trade_data, format_trade_table)references/api_reference.md; the preview endpoint does not return
country namesnpx claudepluginhub jpfielding/claude.pnge --plugin pnge-economicsProvides expertise on customs documentation, HS tariff classification using GRI rules, duty optimization, restricted party screening, and regulatory compliance across US, EU, UK, Asia-Pacific jurisdictions.
Codified expertise for customs documentation, tariff classification, duty optimization, restricted party screening, and regulatory compliance across jurisdictions.
Provides guidance on customs documentation, HS/HTS tariff classification, duty optimization, restricted party screening, and regulatory compliance across US, EU, UK, Asia-Pacific jurisdictions. Useful for import/export clearance and audits.