analyze-silver-miner-metal-ratio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<essential_principles>

<principle name="ratio_definition"> **比率定義與意義**

礦業股/金屬比率（Miner-to-Metal Ratio）：

ratio_t = miner_price_t / metal_price_t

其中：

miner_price：銀礦股代表（ETF 如 SIL/SILJ，或自建礦業股指數）
metal_price：白銀價格（期貨 SI=F、現貨 XAGUSD、ETF SLV）

此比率衡量「礦業股相對於金屬本體」的估值水位：

比率高：礦業股相對白銀偏貴（可能過度樂觀、槓桿溢價高）
比率低：礦業股相對白銀偏便宜（可能被低估、或反映成本/股權稀釋風險） </principle>

<principle name="quantile_interpretation"> **分位數解讀邏輯**

使用歷史分位數（Percentile Rank）判斷當前比率位置：

分位數區間	標籤	直覺
≤ 20%	bottom (底部)	礦業股相對白銀歷史上很便宜
20-40%	low (偏低)	礦業股相對估值偏低
40-60%	neutral (中性)	歷史中位區間
60-80%	high (偏高)	礦業股相對估值偏高
≥ 80%	top (頂部)	礦業股相對白銀歷史上很貴

底部區間不等於白銀必漲：可能是礦業股因成本/稀釋被合理定價。 </principle>

<principle name="divergence_signal"> **背離訊號的意義**

當出現「比率低 + 白銀高」的組合：

比率處於底部區：礦業股相對白銀偏便宜
白銀處於高位：金屬價格已在歷史高檔

此「背離」意味著：

礦業股可能有追趕空間（均值回歸邏輯）
或礦業股正確反映了結構性問題（成本、稀釋、地緣風險）

需結合基本面交叉驗證，而非盲目視為買入訊號。 </principle>

<principle name="scenario_math"> **情境推演計算**

目標：若比率要回到歷史頂部（或中位），需要什麼條件？

假設當前比率 = 1.14，目標比率（頂部門檻）= 2.45：

情境 A：白銀不變，礦業股需漲多少？

miner_multiplier = target_ratio / current_ratio
                 = 2.45 / 1.14 = 2.15x (需漲 115%)

情境 B：礦業股不變，白銀需跌多少？

metal_multiplier = current_ratio / target_ratio
                 = 1.14 / 2.45 = 0.46 (需跌 54%)

此推演提供「極端情境」的量化參考，非預測。 </principle>

<principle name="data_alignment"> **數據對齊原則**

頻率選擇：長週期訊號建議使用週頻（1wk）或月頻（1mo）
平滑視窗：可選 4 週或 3 個月移動平均降低雜訊
事件去重：類比事件間隔需 ≥ min_separation_days（如 180 天）

本 skill 使用 yfinance 取得 ETF/期貨數據，預設週頻對齊。 </principle>

</essential_principles>

<objective> 實作「銀礦股價 / 銀價比率」分析模型：

數據整合：取得礦業股代理與白銀價格序列
比率計算：計算相對比率並可選平滑
分位數判斷：當前比率在歷史的位置
類比事件：歷史底部區間的事件識別
前瞻驗證：底部事件後白銀的 1/2/3 年表現
情境推演：礦業股需漲多少 / 白銀需跌多少才回到頂部

輸出：當前狀態、歷史類比、情境推演、風險提示。 </objective>

<quick_start>

最快的方式：執行預設情境分析

bash

cd skills/analyze-silver-miner-metal-ratio
pip install pandas numpy yfinance matplotlib  # 首次使用
python scripts/ratio_analyzer.py --quick

生成視覺化圖表（基本版）

bash

python scripts/ratio_plotter.py --quick --output-dir ../../output

生成完整版圖表（含底部事件、前瞻報酬統計）

bash

python scripts/ratio_plotter.py --comprehensive --start-date 2010-01-01 --output-dir ../../output

圖表輸出路徑：

基本版：
```
output/sil_silver_ratio_YYYY-MM-DD.png
```

完整版：

output/sil_silver_ratio_comprehensive_YYYY-MM-DD.png

輸出範例：

json

{
  "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
  }
}

完整情境分析：

bash

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>

<intake> 需要進行什麼操作？

快速分析 - 使用預設參數（SIL / SI=F）計算當前比率狀態
完整分析 - 自訂參數進行情境分析（可選擇礦業股/金屬代理、分位門檻）
視覺化圖表 - 生成比率走勢圖，標記當前位置與分位數區間
歷史驗證 - 查看底部區間事件的前瞻報酬統計
情境推演 - 計算「回到頂部」需要的礦業股漲幅或白銀跌幅
方法論學習 - 了解比率邏輯與分位數解讀

請選擇或直接提供分析參數。 </intake>

<routing> | Response | Action | |-------------------------------|---------------------------------------------------------------------| | 1, "快速", "quick", "分析" | 執行 `python scripts/ratio_analyzer.py --quick` | | 2, "完整", "full", "自訂" | 閱讀 `workflows/analyze.md` 並執行 | | 3, "圖表", "chart", "視覺化" | 執行 `python scripts/ratio_plotter.py --quick --output-dir output/` | | 4, "歷史", "驗證", "backtest" | 閱讀 `workflows/analyze.md` 並聚焦歷史類比 | | 5, "情境", "scenario", "推演" | 閱讀 `workflows/analyze.md` 並聚焦情境推演 | | 6, "學習", "方法論", "why" | 閱讀 `references/methodology.md` | | 提供參數 (如礦業股/金屬代理) | 閱讀 `workflows/analyze.md` 並使用參數執行 |

路由後，閱讀對應文件並執行。 </routing>

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

方法論: references/methodology.md

比率定義與直覺
分位數解讀邏輯
背離訊號的意義
情境推演數學
歷史驗證方法

資料來源: references/data-sources.md

礦業股代理（ETF/指數）
白銀價格代理
數據對齊原則

輸入參數: references/input-schema.md

完整參數定義
預設值與建議範圍

</reference_index>

<workflows_index>

Workflow	Purpose	使用時機
analyze.md	完整情境分析	需要自訂參數計算比率與情境
data-research.md	數據源研究	了解如何獲取或替代礦業股/金屬數據
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON 輸出結構定義
output-markdown.md	Markdown 報告模板
</templates_index>

<scripts_index>

Script	Command	Purpose
ratio_analyzer.py	`--quick`	快速分析 SIL/SI=F
ratio_analyzer.py	`--miner-proxy SILJ --freq 1mo`	自訂礦業股與頻率
ratio_analyzer.py	`--scenario-target return_to_median`	回到中位數情境
ratio_plotter.py	`--quick --output-dir ../../output`	快速生成基本版圖表
ratio_plotter.py	`--comprehensive --start-date 2010-01-01 --output-dir ...`	完整版圖表（含底部事件、前瞻報酬統計）
</scripts_index>

<input_schema_summary>

核心參數

參數	類型	預設值	說明
miner_proxy	string	SIL	銀礦股代表（ETF/指數代號）
metal_proxy	string	SI=F	白銀價格代表（期貨/現貨/ETF）
start_date	string	10 年前	歷史回溯起點（YYYY-MM-DD）
end_date	string	today	分析終點
freq	string	1wk	取樣頻率（1d/1wk/1mo）

進階參數

參數	類型	預設值	說明
smoothing_window	int	4	比率平滑視窗（週數/月數）
bottom_quantile	float	0.20	底部估值區分位數門檻
top_quantile	float	0.80	頂部估值區分位數門檻
min_separation_days	int	180	類比事件去重間隔
forward_horizons	list	[52, 104, 156]	前瞻期（週數，對應 1/2/3 年）
scenario_target	string	return_to_top	情境目標（return_to_top/median）

完整參數定義見

references/input-schema.md

。

</input_schema_summary>

<output_schema_summary>

json

{
  "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 流量等做交叉驗證。"
  ]
}

完整輸出結構見

templates/output-json.md

。 </output_schema_summary>

<success_criteria> 執行成功時應產出：

當前比率與歷史分位數
估值區間判定（bottom/low/neutral/high/top）
歷史底部事件列表與去重
底部事件後的前瞻報酬統計（平均/中位/勝率/最差）
情境推演（礦業股需漲多少 / 白銀需跌多少）
結果輸出為指定格式（JSON 或 Markdown）
視覺化圖表輸出（若需要）
風險提示與後續研究建議 </success_criteria>

<essential_principles>

<principle name="ratio_definition"> **Ratio Definition and Significance**

Miner-to-Metal Ratio:

ratio_t = miner_price_t / metal_price_t

Where:

miner_price: Proxy for silver mining stocks (ETFs such as SIL/SILJ, or self-constructed 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 overvalued compared to silver (may be due to excessive optimism, high leverage premium)
Low ratio: Mining stocks are relatively undervalued compared to silver (may be undervalued, or reflect cost/equity dilution risks) </principle>

<principle name="quantile_interpretation"> **Percentile Interpretation Logic**

Use historical Percentile Rank to determine the current ratio position:

Percentile Range	Label	Intuition
≤ 20%	bottom	Mining stocks are historically 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 expensive relative to silver

Bottom range does not guarantee silver price rise: Mining stocks may be reasonably priced due to costs/dilution. </principle>

<principle name="divergence_signal"> **Significance of Divergence Signals**

When the combination of "low ratio + high silver price" occurs:

Ratio is in bottom range: Mining stocks are relatively undervalued compared to silver
Silver is at a high level: Metal price is already at a historical high

This "divergence" implies:

Mining stocks may have room to catch up (mean reversion logic)
Or mining stocks correctly reflect structural issues (costs, dilution, geopolitical risks)

Cross-validation with fundamentals is required, rather than blindly treating it as a buy signal. </principle>

<principle name="scenario_math"> **Scenario Projection Calculation**

Objective: What conditions are needed for the ratio to return to historical top (or median)?

Assume current ratio = 1.14, target ratio (top threshold) = 2.45:

Scenario A: Silver price remains unchanged, how much do mining stocks need to rise?

miner_multiplier = target_ratio / current_ratio
                 = 2.45 / 1.14 = 2.15x (needs to rise 115%)

Scenario B: Mining stock price remains unchanged, how much does silver need to fall?

metal_multiplier = current_ratio / target_ratio
                 = 1.14 / 2.45 = 0.46 (needs to fall 54%)

This projection provides quantitative reference for "extreme scenarios", not a prediction. </principle>

<principle name="data_alignment"> **Data Alignment Principles**

Frequency selection: Weekly (1wk) or monthly (1mo) frequency is recommended for long-term signals
Smoothing window: Optional 4-week or 3-month moving average to reduce noise
Event deduplication: Interval between analogous events must be ≥ min_separation_days (e.g., 180 days)

This skill uses yfinance to obtain ETF/futures data, with default weekly frequency alignment. </principle>

</essential_principles>

<objective> Implement the "Silver Mining Stock Price / Silver Price Ratio" analysis model:

Data Integration: Obtain time series of mining stock proxies and silver prices
Ratio Calculation: Calculate relative ratio with optional smoothing
Percentile Judgment: Current ratio's position in history
Analogous Events: Identify historical bottom range events
Forward Validation: Silver's 1/2/3-year performance after bottom events
Scenario Projection: How much mining stocks need to rise / silver need to fall to return to top

Output: Current status, historical analogs, scenario projections, risk warnings. </objective>

<quick_start>

Fastest way: Execute default scenario analysis

bash

cd skills/analyze-silver-miner-metal-ratio
pip install pandas numpy yfinance matplotlib  # First-time use
python scripts/ratio_analyzer.py --quick

Generate visualization charts (basic version)

bash

python scripts/ratio_plotter.py --quick --output-dir ../../output

Generate full version charts (including bottom events, forward return statistics)

bash

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:

json

{
  "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:

bash

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>

<intake> What operation do you need to perform?

Quick Analysis - Calculate current ratio status using default parameters (SIL / SI=F)
Full Analysis - Customize parameters for scenario analysis (can select mining stock/metal proxy, percentile thresholds)
Visualization Charts - Generate ratio trend chart, mark current position and percentile ranges
Historical Validation - View forward return statistics of bottom range events
Scenario Projection - Calculate how much mining stocks need to rise / silver need to fall to return to top
Methodology Learning - Understand ratio logic and percentile interpretation

Please select or directly provide analysis parameters. </intake>

<routing> | Response | Action | |-------------------------------|---------------------------------------------------------------------| | 1, "quick", "快速", "分析" | Execute `python scripts/ratio_analyzer.py --quick` | | 2, "full", "完整", "自訂" | Read `workflows/analyze.md` and execute | | 3, "chart", "圖表", "視覺化" | Execute `python scripts/ratio_plotter.py --quick --output-dir output/` | | 4, "history", "歷史", "驗證" | Read `workflows/analyze.md` and focus on historical analogs | | 5, "scenario", "情境", "推演" | Read `workflows/analyze.md` and focus on scenario projections | | 6, "learn", "學習", "方法論" | Read `references/methodology.md` | | Provide parameters (e.g., mining stock/metal proxy) | Read `workflows/analyze.md` and execute with parameters |

After routing, read the corresponding file and execute. </routing>

<directory_structure>

analyze-silver-miner-metal-ratio/
├── SKILL.md                           # This file (router)
├── skill.yaml                         # Frontend display metadata
├── manifest.json                      # Skill metadata
├── workflows/
│   ├── analyze.md                     # Full scenario analysis workflow
│   └── data-research.md               # Data source research and alternatives
├── references/
│   ├── methodology.md                 # Methodology and calculation logic
│   ├── input-schema.md                # Complete input parameter definition
│   └── data-sources.md                # Data sources and acquisition methods
├── templates/
│   ├── output-json.md                 # JSON output template
│   └── output-markdown.md             # Markdown report template
├── scripts/
│   ├── ratio_analyzer.py              # Main calculation script
│   └── ratio_plotter.py               # Visualization chart script
└── examples/
    └── sample-output.json             # Sample output

</directory_structure>

<reference_index>

Methodology: references/methodology.md

Ratio definition and intuition
Percentile interpretation logic
Significance of divergence signals
Scenario projection mathematics
Historical validation methods

Data Sources: references/data-sources.md

Mining stock proxies (ETF/index)
Silver price proxies
Data alignment principles

Input Parameters: references/input-schema.md

Complete parameter definition
Default values and recommended ranges

</reference_index>

<workflows_index>

Workflow	Purpose	Usage Scenario
analyze.md	Full scenario analysis	Need to customize parameters to calculate ratio and scenarios
data-research.md	Data source research	Understand how to obtain or replace 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 of SIL/SI=F
ratio_analyzer.py	`--miner-proxy SILJ --freq 1mo`	Customize mining stock 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	Proxy for silver mining stocks (ETF/index symbol)
metal_proxy	string	SI=F	Proxy for silver price (futures/spot/ETF)
start_date	string	10 years ago	Historical backtest start date (YYYY-MM-DD)
end_date	string	today	Analysis end date
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 range percentile threshold
top_quantile	float	0.80	Top valuation range percentile threshold
min_separation_days	int	180	Analogous event deduplication interval
forward_horizons	list	[52, 104, 156]	Forward horizons (weeks, corresponding to 1/2/3 years)
scenario_target	string	return_to_top	Scenario target (return_to_top/median)

Complete parameter definition can be found in

references/input-schema.md

</input_schema_summary>

<output_schema_summary>

json

{
  "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": "Silver Mining Stock Price / Silver Price ratio is in the historical low percentile, indicating mining stocks are relatively undervalued compared to silver...",
  "notes": [
    "Ratio signals measure 'relative valuation', not a one-way price guarantee.",
    "Mining stocks and metals may rise together, but mining stocks may also lag due to rising costs, geopolitical/policy risks, and issuance dilution.",
    "Recommended to cross-validate with: mining stock profitability (cost curve), silver real interest rate/USD, speculative positions (COT), ETF flows, etc."
  ]
}

Complete output structure can be found in

templates/output-json.md

. </output_schema_summary>

<success_criteria> Successful execution should produce:

Current ratio and historical percentile
Valuation range determination (bottom/low/neutral/high/top)
List of historical bottom events with deduplication
Forward return statistics after bottom events (average/median/win rate/worst case)
Scenario projections (how much mining stocks need to rise / silver need to fall)
Results output in specified format (JSON or Markdown)
Visualization chart output (if required)
Risk warnings and follow-up research suggestions </success_criteria>