analyze-silver-miner-metal-ratio

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

analyze-silver-miner-metal-ratio

NPX Install

Tags

SKILL.md Content (Chinese)