monitor-etf-holdings-drawdown-risk

Original：🇨🇳 Chinese

Translated

4 scriptsChecked / no sensitive code detected

Detect the divergence phenomenon where commodity prices rise but the holdings of corresponding physical ETFs/trusts decline, and use multi-indicator cross-validation to assess the risk of physical supply tightness/delivery pressure.

11installs

Sourcefatfingererr/macro-skills

Added on2026-02-08

NPX Install

npx skill4agent add fatfingererr/macro-skills monitor-etf-holdings-drawdown-risk

SKILL.md Content (Chinese)

View Translation Comparison →

<essential_principles>

<principle name="divergence_core"> **Core Logic of Divergence Signals**

Definition of Divergence Event:

Price Rise:
```
price_return >= min_price_return_pct
```
(e.g., +15%)

Inventory Decline:

inventory_change <= -min_inventory_drawdown_pct

(e.g., -10%)

Concurrent Occurrence: Both conditions are met within the same window period (e.g., 180 days)

It is normal when prices and inventory move in the same direction (both rise or fall); vigilance is required only when they move in opposite directions (prices rise while inventory declines). </principle>

<principle name="dual_hypothesis"> **Dual Hypothesis Validation**

Do not directly interpret "inventory decline" as "physical hoarding"; cross-validation is required:

Hypothesis	Supporting Conditions	Refuting Conditions
Physical Tightness	Decline in COMEX/LBMA inventories, backwardation, rising lease rates, widening retail premiums	Stable other inventories, contango, stable premiums
Capital Flow/Redemption	ETF outflows but stable exchange inventories, non-tight futures structure	Synchronized decline in multiple inventories

Output both interpretations for users to judge which one better fits the current data. </principle>

<principle name="data_access"> **Data Acquisition Methods**

This skill prioritizes using:

ETF Official Website Inventory: Scraped using Selenium to simulate human browser behavior (to avoid API restrictions)
Yahoo Finance: Spot/futures prices obtained via the
```
yfinance
```
package
Cross-Validation: Public data such as COMEX inventories and futures structures

Scripts are located in the

scripts/

directory and follow the anti-detection strategy in

references/data-sources.md

. </principle>

<principle name="stress_scoring"> **Stress Score Calculation**

stress_score = 100 × min(1.0,
    0.6 × divergence_severity +      # Divergence severity
    0.2 × decade_low_bonus +         # Decade-low bonus
    0.2 × ratio_extreme_bonus        # Extreme ratio bonus
)

Score Range	Interpretation
0-30	Normal, no obvious divergence
30-60	Mild divergence, worthy of attention
60-80	Moderate divergence, in-depth verification recommended
80-100	Severe divergence, high alert

</principle>

</essential_principles>

<objective> Monitor the divergence between holdings of physical ETFs (e.g., SLV, PSLV, GLD) and commodity prices:

Detect Divergence: Prices rise but ETF inventory declines
Assess Severity: Calculate divergence degree, decade-low levels, and extreme ratios
Cross-Validation: Use indicators such as COMEX data, futures structures, and retail premiums
Generate Insights: Provide two opposing hypotheses to avoid single-narrative bias

Output: Divergence status, stress score, cross-validation results, and recommendations for next-step checks. </objective>

<quick_start>

Fastest Way: Check SLV Divergence Status

bash

cd skills/monitor-etf-holdings-drawdown-risk
pip install pandas numpy yfinance selenium webdriver-manager beautifulsoup4 matplotlib  # First-time use
python scripts/divergence_detector.py --etf SLV --quick

Sample Output:

json

{
  "asof": "2026-01-20",
  "divergence": false,
  "price_return_window": 1.92,
  "inventory_change_window": 0.15,
  "inventory_decade_low": false,
  "stress_score_0_100": 20.0,
  "interpretations": ["Physical Tightness", "ETF Flow Hypothesis"]
}

Full Analysis + Visualization Report:

bash

# 1. Execute divergence detection
python scripts/divergence_detector.py \
  --etf SLV \
  --start 2010-01-01 \
  --end 2026-01-20 \
  --output result.json

# 2. Generate visualization report
python scripts/visualize_divergence.py \
  --result result.json \
  --output ../../../output/

Output:

JSON analysis result:
```
result.json
```

Visualization report:

output/SLV_divergence_report_20260120.png

PDF report:

output/SLV_divergence_report_20260120.pdf

</quick_start>

<intake> What operation do you need to perform?

Quick Check - View the current divergence status and stress score of the specified ETF
Full Analysis - Perform a complete historical divergence analysis
Cross-Validation - Verify the authenticity of divergence signals using multiple indicators
Monitoring Mode - Set up continuous monitoring and divergence alerts
Methodology Learning - Understand divergence detection and dual hypothesis logic

Please select or directly provide analysis parameters (e.g., ETF ticker symbol). </intake>

<routing> | Response | Action | |---------------------------------|-----------------------------------------------| | 1, "快速", "quick", "check" | Execute `scripts/divergence_detector.py --quick` | | 2, "分析", "analyze", "full" | Read `workflows/analyze.md` and execute | | 3, "驗證", "validate", "cross" | Read `workflows/cross-validate.md` and execute| | 4, "監控", "monitor", "alert" | Read `workflows/monitor.md` and execute | | 5, "學習", "方法論", "why" | Read `references/methodology.md` | | Provide ETF ticker (e.g., SLV, GLD) | Read `workflows/analyze.md` and execute with parameters |

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

<directory_structure>

monitor-etf-holdings-drawdown-risk/
├── SKILL.md                           # This file (router)
├── skill.yaml                         # Frontend display metadata
├── manifest.json                      # Skill metadata
├── workflows/
│   ├── analyze.md                     # Full divergence analysis workflow
│   ├── monitor.md                     # Continuous monitoring workflow
│   └── cross-validate.md              # Cross-validation workflow
├── references/
│   ├── data-sources.md                # ETF inventory and price data sources
│   ├── methodology.md                 # Divergence detection methodology
│   └── input-schema.md                # Complete input parameter definition
├── templates/
│   ├── output-json.md                 # JSON output template
│   └── output-markdown.md             # Markdown report template
└── scripts/
    ├── divergence_detector.py         # Main detection script
    ├── fetch_etf_holdings.py          # ETF inventory scraping (Selenium)
    └── fetch_prices.py                # Commodity price scraping

</directory_structure>

<reference_index>

Methodology: references/methodology.md

Divergence detection logic
Dual hypothesis validation framework
Stress score calculation

Data Sources: references/data-sources.md

ETF official website inventory scraping (Selenium)
Yahoo Finance price data
Cross-validation data sources (COMEX, LBMA)

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 Divergence Analysis	When complete historical analysis is needed
monitor.md	Continuous Status Monitoring	For daily monitoring or alerts
cross-validate.md	Cross-Validate Divergence Signals	When verifying the authenticity of divergence
</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
divergence_detector.py	`--etf SLV --quick`	Quick Divergence Status Check
divergence_detector.py	`--start DATE --end DATE --output FILE`	Complete Historical Analysis
visualize_divergence.py	`--result result.json --output DIR`	Generate Visualization Report
fetch_etf_holdings.py	`--etf SLV --output holdings.csv`	Scrape ETF Inventory
fetch_prices.py	`--symbol SI=F --output prices.csv`	Scrape Commodity Prices
</scripts_index>

<input_schema_summary>

Core Parameters

Parameter	Type	Default Value	Description
etf_ticker	string	(Required)	ETF/trust ticker symbol (e.g., SLV)
commodity_price_symbol	string	(Required)	Commodity price symbol (e.g., XAGUSD)
start_date	string	10 years ago	Analysis start date
end_date	string	today	Analysis end date

Divergence Parameters

Parameter	Type	Default	Description
divergence_window_days	int	180	Divergence calculation window (days)
decade_low_window_days	int	3650	Decade-low calculation window (days)
min_price_return_pct	float	0.15	Price rise threshold
min_inventory_drawdown_pct	float	0.10	Inventory decline threshold

Complete parameter definition can be found in

references/input-schema.md

</input_schema_summary>

<output_schema_summary>

json

{
  "skill": "monitor-etf-holdings-drawdown-risk",
  "asof": "2026-01-16",
  "inputs": {
    "etf_ticker": "SLV",
    "commodity_price_symbol": "XAGUSD"
  },
  "result": {
    "divergence": true,
    "price_return_window": 0.32,
    "inventory_change_window": -0.18,
    "inventory_decade_low": true,
    "inventory_to_price_ratio_z": -2.4,
    "stress_score_0_100": 78.5
  },
  "interpretations": [...],
  "next_checks": [...]
}

Complete output structure can be found in

templates/output-json.md

. </output_schema_summary>

<success_criteria> Upon successful execution, the following should be generated:

Divergence status determination (divergence: true/false)
Price change and inventory change values
Decade-low determination
Inventory/price ratio Z-score
Stress score (0-100)
Two opposing hypothesis interpretations
List of next-step verification recommendations </success_criteria>

monitor-etf-holdings-drawdown-risk

NPX Install

Tags

SKILL.md Content (Chinese)