Agent skill

Commodity Analysis Signals

by HKUDS in HKUDS/Vibe-Trading

Analyzes crude oil, gold and copper through supply-demand balance, pricing models, inventory cycles and futures structure, and outputs directional signals suitable for backtesting.

MITAuto-check passedBusiness, Finance & HR

Install Commodity Analysis Signals

skills CLI
$ npx skills add HKUDS/Vibe-Trading --skill commodity-analysis -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install HKUDS/Vibe-Trading commodity-analysis --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .claude/skills && cp -r skills-src/agent/src/skills/commodity-analysis .claude/skills/commodity-analysis && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
commodity-analysis
GitHub stars
35k
Token cost
~2.3k tokens
SKILL.md length
794 words
Files
1
Skills in repo
89
Repo updated
First seen
Licence
MIT

At a glance

Analyzes crude oil, gold and copper through supply-demand balance, pricing models, inventory cycles and futures structure, and outputs directional signals suitable for backtesting.

  • Works in 6 steps: Crude Oil Supply-Demand Balance → Gold Pricing Framework → Dr. Copper as an Economic Predictor → …
  • Judging whether the oil market is tight or loose from supply and demand data
  • SKILL.md covers Overview, Core Concepts, Analysis Framework and Output Format, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The skill examines commodities along four lines: supply-demand balance, a pricing model, the inventory cycle and futures curve structure, and it turns the result into directional signals that can be backtested. It concentrates on crude oil as the global pricing anchor, gold as a safe haven and inflation hedge, and copper as an economic barometer.

For oil it tabulates supply-side variables such as OPEC production, US shale output, rig counts and strategic reserve releases next to demand-side inputs like IEA forecasts, China imports, gasoline demand and global PMI. Gold uses a four-factor model weighted 40% real rates, 25% dollar index, 20% safe-haven demand and 15% central-bank buying, with rules of thumb for TIPS yields, and copper is treated as a leading indicator of industrial production. Seasonality is part of the stated scope.

When your agent uses it

  • Judging whether the oil market is tight or loose from supply and demand data
  • Assessing gold with real rates, the dollar index and safe-haven demand
  • Using copper as a read on industrial activity
  • Generating directional commodity signals for a backtest

Example prompts

  • “Is the crude oil market tight right now? Walk through OPEC output, rig counts and inventories.”
  • “Score gold with the four-factor model using the current 10Y TIPS yield and DXY.”
  • “Use the copper to gold ratio to read where the economic cycle stands.”
  • “Produce a directional oil signal that I can feed into a backtest.”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Crude Oil Supply-Demand Balance
  2. Gold Pricing Framework
  3. Dr. Copper as an Economic Predictor
  4. Inventory Cycle Analysis
  5. Futures Premium / Discount Structure
  6. Seasonality

What it can do on your machine

Read from SKILL.md and the folder at commit 7f6908b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are python).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Commodity Analysis Signals loads about 2.3k tokens when it runs. Until then it costs about 57 tokens; SKILL.md has 794 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~57
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from HKUDS/Vibe-Trading at commit 7f6908b, republished under its MIT licence (© HKUDS). 794 words, ~2,262 tokens.

Download SKILL.mdSave it as .claude/skills/commodity-analysis/SKILL.md (or your agent's skills folder).
name
commodity-analysis
description
Commodity analysis (oil supply-demand balance / gold pricing / copper as an economic predictor / inventory cycles / futures premium-discount structure / seasonality), generating directional commodity signals.
category
analysis

Commodity Analysis

Overview

Analyze commodities from four dimensions — supply-demand balance, pricing model, inventory cycle, and futures structure — and output directional signals suitable for backtesting. Focuses on crude oil (global pricing anchor), gold (safe haven + inflation hedge), and copper (economic barometer).

Core Concepts

1. Crude Oil Supply-Demand Balance

Key supply-side variables:

VariableData SourceFrequencyDirection of Impact
OPEC productionOPEC monthly reportMonthlyProduction cuts → oil price ↑
US shale outputEIA weekly reportWeeklyHigher output → oil price ↓
Rig count (Baker Hughes)Baker HughesWeeklyLeads production by 3-6 months
Strategic Petroleum Reserve (SPR)EIAWeeklySPR release → short-term oil price ↓

Key demand-side variables:

  • IEA global oil demand forecast (quarterly)
  • China crude imports (customs monthly data)
  • US gasoline demand (EIA weekly report, implied demand)
  • Global PMI (leads demand by 1-2 months)

Supply-demand balance signals:

python
# Simplified supply-demand judgment
if opec_compliance > 90% and us_rig_count_declining:
    supply_signal = "tight"  # bullish for oil
elif opec_compliance < 80% and us_production_rising:
    supply_signal = "loose"  # bearish for oil

if global_pmi > 50 and china_import_yoy > 5%:
    demand_signal = "strong"  # bullish for oil
elif global_pmi < 48 and china_import_yoy < 0:
    demand_signal = "weak"    # bearish for oil
2. Gold Pricing Framework

Four-factor model:

FactorWeightLogicIndicator
Real rates40%Real rates ↓ → lower opportunity cost of holding gold → gold ↑10Y TIPS yield
US dollar index25%USD ↓ → gold becomes cheaper in pricing terms → gold ↑DXY
Safe-haven demand20%Risk ↑ → safe-haven buying → gold ↑VIX + geopolitical risk index
Central-bank buying15%Central-bank purchases → structural demand supportWGC quarterly report

Practical rules:

  • 10Y TIPS < 0%: strong support for gold (negative real rates mean negative holding cost)
  • 10Y TIPS > 2%: pressure on gold (positive real rates reduce attractiveness)
  • Correlation between DXY and gold is around -0.6, but not absolute (they both rose in 2022 due to safe-haven demand)
  • Central-bank purchases >1000 tons / year (2022-2023 level): long-term structural bullish support
3. Dr. Copper as an Economic Predictor

Copper as a leading indicator:

  • YoY copper-price change leads industrial production by about 2-3 months
  • Copper / gold ratio is highly positively correlated with the US 10Y Treasury yield (r > 0.7)
  • Copper breakout above the prior high confirms economic recovery

Copper fundamental tracking:

IndicatorData SourceThreshold
LME copper inventoryLME daily report<150k tons = tight
SHFE copper inventorySHFE weekly reportWoW decline >10% = tight
Copper concentrate TC/RCSMMTC < $30/ton = tight mining supply
China copper importsCustoms monthly reportYoY growth >10% = strong demand
4. Inventory Cycle Analysis

Visible inventory vs hidden inventory:

  • Visible inventory: published by exchanges (LME / SHFE / COMEX), transparent and trackable
  • Hidden inventory: bonded areas / trader warehouses, opaque but potentially larger
  • The true turning point in prices is the turning point in total inventory

Four inventory-cycle stages (using copper as example):

Active restocking (price↑ volume↑) -> Passive restocking (price↓ volume↑) -> Active destocking (price↓ volume↓) -> Passive destocking (price↑ volume↓)
      mid bull market                 late bull market                 mid bear market                 late bear / early bull market

Signal mapping:

StageInventory DirectionPrice DirectionTrading Signal
Passive destocking↓↑Long (best buying point)
Active restocking↑↑Keep long positions
Passive restocking↑↓Close longs (warning)
Active destocking↓↓Short or stay neutral
5. Futures Premium / Discount Structure

Contango (futures > spot, normal market):

  • Supply is abundant, and the market prices in carrying costs (storage + funding)
  • Roll yield is negative (roll yield < 0), unfavorable for long holders
  • Deep contango (far month - near month > 5%) = severe oversupply

Backwardation (futures < spot, inverted market):

  • Supply is tight, and spot premium reflects strong immediate demand
  • Roll yield is positive (roll yield > 0), favorable for long holders
  • Deep backwardation (near month - far month > 3%) = squeeze or extreme shortage

Term-structure signal:

python
# Spread ratio = (front month - second month) / front month
spread_ratio = (front_month - second_month) / front_month

if spread_ratio > 0.02:    # backwardation > 2%
    signal = "strongly bullish"  # spot shortage
elif spread_ratio < -0.03: # contango > 3%
    signal = "bearish"           # oversupply
else:
    signal = "neutral"
Show full SKILL.md (288 more words)Show less
6. Seasonality

Oil seasonality:

  • March-May: refinery maintenance ends + summer inventory build → seasonal rise (ahead of the "driving season")
  • September-October: hurricane season (Gulf of Mexico) → supply disruption → higher volatility
  • November-December: heating-oil demand → stronger diesel crack spread

Gold seasonality:

  • January-February: Lunar New Year + Indian wedding-season physical demand → relatively strong
  • July-August: traditional soft season → relatively weak
  • October-November: Diwali + Christmas restocking → relatively strong

Copper seasonality:

  • March-April: China construction season starts → demand recovery
  • June-July: off-season inventory buildup → pressure
  • September-October: "Golden September, Silver October" → demand recovery

Analysis Framework

Five-Step Commodity Analysis
  1. Supply-demand sets direction: is the balance in surplus or shortage? Which way are marginal variables moving?
  2. Inventory sets rhythm: which inventory-cycle stage are we in? Is a turning point close?
  3. Term structure confirms: contango or backwardation? Does it confirm the supply-demand judgment?
  4. Seasonality overlay: is seasonality currently a tailwind or a headwind?
  5. Macro validation: do the dollar / rates / risk appetite support the directional judgment?
Composite Scoring Template
python
commodity_score = {
    "supply_demand": +1,    # supply-demand is tight
    "inventory_cycle": +2,  # passive destocking (best stage)
    "term_structure": +1,   # mild backwardation
    "seasonality": 0,       # neutral seasonality
    "macro_env": -1,        # stronger dollar is a headwind
}
# Total score = +3/5 = +0.6 -> bullish bias, but not a strong signal

Output Format

## Commodity Analysis Report — [Commodity Name]

### Supply-Demand Structure
- Supply side: [surplus / balanced / shortage] — [specific data]
- Demand side: [strong / stable / weak] — [specific data]
- Balance table: [inventory build X tons / drawdown X tons]

### Inventory Cycle
- Current stage: [active restocking / passive restocking / active destocking / passive destocking]
- Visible inventory: [LME X tons, SHFE X tons, WoW change]

### Term Structure
- Front-back spread: [contango X% / backwardation X%]
- Roll yield: [positive / negative]

### Composite Score
| Dimension | Score(-2~+2) | Basis |
|------|------------|------|
| Supply-demand | +1 | OPEC compliance rate 92% |
| Inventory | +2 | LME inventory hit 18-month low |

### Trading Direction
- Direction: [bullish / bearish / neutral]
- Confidence: [high / medium / low]
- Risk points: [specific risks]

Notes

  • Commodity data sources are fragmented (EIA / OPEC / LME / SHFE, etc.). This skill provides the analytical framework; data should be retrieved through web-reader or entered manually
  • Futures prices include roll costs, so direct comparison across different contracts must account for expiry-roll effects
  • Seasonal patterns are statistical averages and may be completely overwhelmed by fundamentals in a given year
  • Gold has both commodity and financial attributes, and the financial side (rates / dollar) usually dominates short-term pricing
  • Copper’s financial characteristics have strengthened since 2020 (copper futures are used as a macro hedge), so pure fundamental analysis may be insufficient
  • Inventory data is lagged (hidden inventories cannot be tracked in real time), so cross-check with price and basis behavior
  • This framework is for research backtesting only and does not constitute investment advice

© HKUDS, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in agent/src/skills/commodity-analysis of HKUDS/Vibe-Trading.

Open the folder on GitHubat commit 7f6908b

Compare with similar skills

Commodity Analysis Signals next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Commodity Analysis Signals compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Commodity Analysis Signals this skillHKUDS/Vibe-Trading35k—~2.3kAutomated safety check: PassMIT
Strategy Performance Reporttradesdontlie/tradingview-mcp6.8k3 repos~591Automated safety check: PassCustom licence
Regimejackson-video-resources/markov-hedge-fund-method483—~1.6kAutomated safety check: PassCustom licence
Quant Buddy Market Data and Backtestingpseudo-longinus/quant-buddy-skills1911 repos~11kAutomated safety check: PassMIT
Alpha Desk Investment ResearchJingHao-Leon/dsh-alpha-desk181—~1.3kAutomated safety check: NotesMIT
Revops Revenue Planningswan-gtm/gtm-skills165—~7.2kAutomated safety check: PassMIT

Similar skills

  • Strategy Performance Report

    tradesdontlie/tradingview-mcp

    Builds a performance report for a backtested Pine Script strategy from TradingView data, covering metrics, trades, the equity curve and improvement ideas.

    6.8k GitHub starsUsed in 3 repos~591 tokens
    Business, Finance & HRAuto-check passed
  • Regime

    jackson-video-resources/markov-hedge-fund-method

    Detect the market regime (Bull / Bear / Sideways) for ANY asset and turn it into a tradeable signal or a risk filter.

    483 GitHub stars~1.6k tokensUpdated 4 mo ago
    Business, Finance & HRAuto-check passed
  • Quant Buddy Market Data and Backtesting

    pseudo-longinus/quant-buddy-skills

    Queries A-share, Hong Kong and US stock quotes, valuation and financial data through the Quant Buddy API, and runs screening, factor calculation and strategy backtests.

    191 GitHub starsUsed in 1 repo~11k tokens
    Business, Finance & HRAuto-check passed
  • Alpha Desk Investment Research

    JingHao-Leon/dsh-alpha-desk

    Runs an AI investment research desk around the aihf hedge-fund CLI, with research cycles, backtests and iFinD data, under a risk gate and a rule against placing real trades.

    181 GitHub stars~1.3k tokensUpdated 14 days ago
    Business, Finance & HRAuto-check: notes
  • Revops Revenue Planning

    swan-gtm/gtm-skills

    Annual and quarterly revenue plan construction, top-down vs bottoms-up reconciliation, plan versioning, stretch goal handling, and FP&A-RevOps collaboration for B2B revenue teams.

    165 GitHub stars~7.2k tokensUpdated 4 days ago
    Business, Finance & HRAuto-check passed
  • FRED Macro Time Series

    kansoku-trade/kansoku

    Looks up US and global macro series from St. Louis Fed FRED, such as CPI, GDP, Fed funds, yields, M2 and the dollar index, and reports them with units and dates.

    326 GitHub stars~1.1k tokensUpdated 11 days ago
    Data & AnalyticsAuto-check: notes

More from HKUDS/Vibe-Trading

All 89 skills in this repo
  • Eastmoney Market Data

    HKUDS/Vibe-Trading

    Index of Eastmoney's free, no-token market data interfaces for China A-shares and Hong Kong stocks: fund flows, dragon-tiger lists, margin trading, reports and news.

    35k GitHub stars~1k tokensUpdated yesterday
    Auto-check passed
  • OKX Market Data

    HKUDS/Vibe-Trading

    Retrieves public OKX cryptocurrency market data such as spot prices, candlesticks, funding rates and open interest through the OKX V5 REST API, with no authentication.

    35k GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed
  • SEC EDGAR Filings Fetcher

    HKUDS/Vibe-Trading

    Fetches U.S. SEC EDGAR data: resolves tickers to CIK numbers, lists recent 10-K, 10-Q and 8-K filings with document URLs, and pulls XBRL financial series.

    35k GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • A-Share ST Risk Screener

    HKUDS/Vibe-Trading

    Predicts whether a mainland China A-share company risks an ST or *ST warning after its next annual report, using financial thresholds and Sina penalty records.

    35k GitHub stars~4.9k tokensUpdated yesterday
    Auto-check passed
  • Breaks a structural trend such as AI infrastructure into its physical supply chain and ranks lesser-known listed companies sitting on each bottleneck.

    35k GitHub stars~2.7k tokensUpdated yesterday
    Auto-check passed
  • Plans and drafts an eight-part, roughly 120k-word investigative series on one company, built around a strict fact-check pass rather than fast drafting.

    35k GitHub stars~2.4k tokensUpdated yesterday
    Auto-check passed

Questions about Commodity Analysis Signals

What does Commodity Analysis Signals do?

Analyzes crude oil, gold and copper through supply-demand balance, pricing models, inventory cycles and futures structure, and outputs directional signals suitable for backtesting. The skill examines commodities along four lines: supply-demand balance, a pricing model, the inventory cycle and futures curve structure, and it turns the result into directional signals that can be backtested. It concentrates on crude oil as the global pricing anchor, gold as a safe haven and inflation hedge, and copper as an economic barometer.

When should I use Commodity Analysis Signals?

Commodity Analysis Signals fits situations like: judging whether the oil market is tight or loose from supply and demand data; assessing gold with real rates, the dollar index and safe-haven demand; using copper as a read on industrial activity; generating directional commodity signals for a backtest.

How do I install Commodity Analysis Signals in Claude Code?

Run `npx skills add HKUDS/Vibe-Trading --skill commodity-analysis -a claude-code`. Or copy the skill folder (agent/src/skills/commodity-analysis in HKUDS/Vibe-Trading) into .claude/skills/commodity-analysis in your project. Claude Code loads it when a task matches its description.

How do I install Commodity Analysis Signals in Codex?

Run `npx skills add HKUDS/Vibe-Trading --skill commodity-analysis -a codex`. Or copy the skill folder (agent/src/skills/commodity-analysis in HKUDS/Vibe-Trading) into .agents/skills/commodity-analysis in your project. Codex loads it when a task matches its description.

Can I use Commodity Analysis Signals in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add HKUDS/Vibe-Trading --skill commodity-analysis -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/commodity-analysis, .gemini/skills/commodity-analysis, .github/skills/commodity-analysis and .opencode/skills/commodity-analysis in your project.

What does Commodity Analysis Signals need to run?

SKILL.md names no scripts, command-line tools or credentials: Commodity Analysis Signals is instructions for the agent only.

Does Commodity Analysis Signals access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Commodity Analysis Signals safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Commodity Analysis Signals use?

Commodity Analysis Signals is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Commodity Analysis Signals use?

About 2.3k tokens (SKILL.md is roughly 9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Commodity Analysis Signals?

Skills that share tags, products or a category with Commodity Analysis Signals: Strategy Performance Report (tradesdontlie/tradingview-mcp, 6.8k stars), Regime (jackson-video-resources/markov-hedge-fund-method, 483 stars), Quant Buddy Market Data and Backtesting (pseudo-longinus/quant-buddy-skills, 191 stars) and Alpha Desk Investment Research (JingHao-Leon/dsh-alpha-desk, 181 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Commodity Analysis Signals?

HKUDS (a GitHub organization) maintains it in HKUDS/Vibe-Trading, which has 34,884 GitHub stars. The repository holds 89 skills in this directory. The repository was last updated on October 6, 2026.

Source: HKUDS/Vibe-Trading on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.