<essential_principles>
Miner-to-Metal Ratio:
ratio_t = miner_price_t / metal_price_t
Where:
- miner_price: Silver mining stock representative (ETF such as SIL/SILJ, or a self-built mining stock index)
- metal_price: Silver price (futures SI=F, spot XAGUSD, ETF SLV)
This ratio measures the valuation level of 'mining stocks relative to the metal itself':
- High ratio: Mining stocks are relatively expensive versus silver (possibly overly optimistic, high leverage premium)
- Low ratio: Mining stocks are relatively cheap versus silver (possibly undervalued, or reflecting cost/equity dilution risk)
Use historical percentiles (Percentile Rank) to judge the current ratio position:
| Percentile range | Label | Intuition |
|---|---|---|
| ≤ 20% | bottom | Mining stocks are historically very cheap relative to silver |
| 20-40% | low | Mining stocks are relatively undervalued |
| 40-60% | neutral | Historical median range |
| 60-80% | high | Mining stocks are relatively overvalued |
| ≥ 80% | top | Mining stocks are historically very expensive relative to silver |
A bottom range does not mean silver must rise: Mining stocks may be fairly priced due to costs/dilution.
When a 'low ratio + high silver' combination appears:
- The ratio is in the bottom range: Mining stocks are relatively cheap versus silver
- Silver is at a high level: The metal price is already at historical highs
This 'divergence' means:
- Mining stocks may have room to catch up (mean reversion logic)
- Or mining stocks are correctly reflecting structural problems (costs, dilution, geopolitical risk)
Cross-validation with fundamentals is needed, rather than blindly treating it as a buy signal.
Objective: If the ratio is to return to the historical top (or median), what conditions are needed?
Assume the current ratio = 1.14, target ratio (top threshold) = 2.45:
Scenario A: If silver is unchanged, how much do mining stocks need to rise?
miner_multiplier = target_ratio / current_ratio
= 2.45 / 1.14 = 2.15x (需漲 115%)
Scenario B: If mining stocks are unchanged, how much does silver need to fall?
metal_multiplier = current_ratio / target_ratio
= 1.14 / 2.45 = 0.46 (需跌 54%)
This projection provides a quantitative reference for 'extreme scenarios', not a forecast.
- Frequency selection: For long-cycle signals, weekly frequency (1wk) or monthly frequency (1mo) is recommended
- Smoothing window: A 4-week or 3-month moving average can optionally be used to reduce noise
- Event deduplication: The interval between analog events must be ≥ min_separation_days (e.g., 180 days)
This skill uses yfinance to obtain ETF/futures data, with weekly frequency alignment by default.
</essential_principles>
- Data integration: Obtain mining stock proxy and silver price series
- Ratio calculation: Calculate the relative ratio with optional smoothing
- Percentile judgment: The position of the current ratio in history
- Analog events: Event identification for historical bottom ranges
- Forward validation: Silver's 1/2/3-year performance after bottom events
- Scenario projection：How much do mining stocks need to rise / how much does silver need to fall to return to the top
Output: current status, historical analogies, scenario projection, risk warnings.
<quick_start>
Fastest way: run the default scenario analysis
cd skills/analyze-silver-miner-metal-ratio
pip install pandas numpy yfinance matplotlib # 首次使用
python scripts/ratio_analyzer.py --quick
Generate visualization chart (basic version)
python scripts/ratio_plotter.py --quick --output-dir ../../output
Generate full version chart (including bottom events, forward return statistics)
python scripts/ratio_plotter.py --comprehensive --start-date 2010-01-01 --output-dir ../../output
Chart output path:
- Basic version:
output/sil_silver_ratio_YYYY-MM-DD.png - Full version:
output/sil_silver_ratio_comprehensive_YYYY-MM-DD.png
Output example:
{
"skill": "analyze_silver_miner_metal_ratio",
"current": {
"ratio": 1.14,
"ratio_percentile": 18.7,
"zone": "bottom",
"bottom_threshold": 1.16,
"top_threshold": 2.45
},
"history_analogs": {
"bottom_event_dates": ["2010-08-06", "2016-01-29", "2020-03-20"],
"forward_metal_returns": {
"252": {"count": 3, "median": 0.42, "win_rate": 1.0}
}
},
"scenarios": {
"target": "return_to_top",
"miner_multiplier_if_metal_flat": 2.15,
"metal_drop_pct_if_miner_flat": 0.54
}
}
Full scenario analysis：
python scripts/ratio_analyzer.py \
--miner-proxy SIL \
--metal-proxy SI=F \
--start-date 2008-01-01 \
--freq 1wk \
--smoothing-window 4 \
--bottom-quantile 0.20 \
--top-quantile 0.80 \
--output result.json
</quick_start>
- Quick analysis - Use default parameters (SIL / SI=F) to calculate the current ratio status
- Full analysis - Customize parameters for scenario analysis (can choose mining stock/metal proxies, quantile thresholds)
- Visualization chart - Generate ratio trend chart, mark current position and quantile intervals
- Historical validation - View forward return statistics for bottom-range events
- Scenario projection - Calculate the mining stock gain or silver decline needed to "return to the top"
- Methodology learning - Understand ratio logic and quantile interpretation
Please select or directly provide analysis parameters.
After routing, read the corresponding document and execute.
<directory_structure>
analyze-silver-miner-metal-ratio/
├── SKILL.md # 本文件（路由器）
├── skill.yaml # 前端展示元數據
├── manifest.json # 技能元數據
├── workflows/
│ ├── analyze.md # 完整情境分析工作流
│ └── data-research.md # 數據源研究與替代方案
├── references/
│ ├── methodology.md # 方法論與計算邏輯
│ ├── input-schema.md # 完整輸入參數定義
│ └── data-sources.md # 數據來源與獲取方式
├── templates/
│ ├── output-json.md # JSON 輸出模板
│ └── output-markdown.md # Markdown 報告模板
├── scripts/
│ ├── ratio_analyzer.py # 主計算腳本
│ └── ratio_plotter.py # 視覺化圖表腳本
└── examples/
└── sample-output.json # 範例輸出
</directory_structure>
<reference_index>
Methodology: references/methodology.md
- Ratio definition and intuition
- Quantile interpretation logic
- Meaning of divergence signals
- Scenario projection mathematics
- Historical validation method
Data sources: references/data-sources.md
- Mining stock proxy (ETF/index)
- Silver price proxy
- Data alignment principles
Input parameters: references/input-schema.md
- Full parameter definitions
- Default values and recommended ranges
</reference_index>
<workflows_index>
| Workflow | Purpose | When to use |
|---|---|---|
| analyze.md | Full scenario analysis | Need to customize parameters to calculate ratios and scenarios |
| data-research.md | Data source research | Learn how to obtain or substitute mining stock/metal data |
| </workflows_index> |
<templates_index>
| Template | Purpose |
|---|---|
| output-json.md | JSON output structure definition |
| output-markdown.md | Markdown report template |
| </templates_index> |
<scripts_index>
| Script | Command | Purpose |
|---|---|---|
| ratio_analyzer.py | --quick |
Quick analysis SIL/SI=F |
| ratio_analyzer.py | --miner-proxy SILJ --freq 1mo |
Customize mining stocks and frequency |
| ratio_analyzer.py | --scenario-target return_to_median |
Return to median scenario |
| ratio_plotter.py | --quick --output-dir ../../output |
Quickly generate basic version chart |
| ratio_plotter.py | --comprehensive --start-date 2010-01-01 --output-dir ... |
Full version chart (including bottom events, forward return statistics) |
| </scripts_index> |
<input_schema_summary>
Core parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
| miner_proxy | string | SIL | Silver mining stock representative (ETF/index ticker) |
| metal_proxy | string | SI=F | Silver price representative (futures/spot/ETF) |
| start_date | string | 10 years ago | Historical backtest start point (YYYY-MM-DD) |
| end_date | string | today | Analysis end point |
| freq | string | 1wk | Sampling frequency (1d/1wk/1mo) |
Advanced parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
| smoothing_window | int | 4 | Ratio smoothing window (weeks/months) |
| bottom_quantile | float | 0.20 | Bottom valuation zone quantile threshold |
| top_quantile | float | 0.80 | Top valuation zone quantile threshold |
| min_separation_days | int | 180 | Analogous event deduplication interval |
| forward_horizons | list | [52, 104, 156] | Forward periods (weeks, corresponding to 1/2/3 years) |
| scenario_target | string | return_to_top | Scenario target (return_to_top/median) |
See full parameter definitions in references/input-schema.md。
</input_schema_summary>
<output_schema_summary>
{
"skill": "analyze_silver_miner_metal_ratio",
"inputs": {
"miner_proxy": "SIL",
"metal_proxy": "SI=F",
"start_date": "2010-01-01",
"freq": "1wk"
},
"current": {
"ratio": 1.14,
"ratio_percentile": 18.7,
"zone": "bottom",
"bottom_threshold": 1.16,
"top_threshold": 2.45
},
"history_analogs": {
"bottom_event_dates": ["2010-08-06", "2016-01-29", "2020-03-20"],
"forward_metal_returns": {
"252": {"count": 3, "median": 0.42, "mean": 0.39, "win_rate": 1.0, "worst": 0.18},
"504": {"count": 3, "median": 0.71, "mean": 0.66, "win_rate": 1.0, "worst": 0.31}
}
},
"scenarios": {
"target": "return_to_top",
"target_ratio": 2.45,
"miner_multiplier_if_metal_flat": 2.15,
"metal_multiplier_if_miner_flat": 0.46,
"metal_drop_pct_if_miner_flat": 0.54
},
"summary": "銀礦股價 / 銀價比率落在歷史低分位，顯示礦業股相對白銀偏便宜...",
"notes": [
"比率訊號衡量的是『相對估值』，不是單邊價格保證。",
"礦業股與金屬可能同漲，但礦業股也可能因成本上升、地緣/政策風險、增發稀釋而落後。",
"建議搭配：礦業股獲利率(成本曲線)、白銀實質利率/美元、投機部位(COT)、ETF 流量等做交叉驗證。"
]
}
Full output structure is shown in templates/output-json.md。
</output_schema_summary>
<success_criteria> Upon successful execution, the following should be produced:
- Current ratio and historical percentile
- Valuation range determination (bottom/low/neutral/high/top)
- List of historical bottom events and deduplication
- Forward return statistics after bottom events (mean/median/win rate/worst)
- Scenario projection (how much mining stocks need to rise / how much silver needs to fall)
- Results output in the specified format (JSON or Markdown)
- Visualization chart output (if needed)
- Risk warnings and suggestions for further research </success_criteria>