detect-us-equity-valuation-percentile-extreme

What problem does it solve?

This skill assesses whether US equity valuations are historically extreme by turning multiple valuation metrics into historical percentiles and aggregating them into a single risk score. It enables users to understand relative valuation strength, track potential earnings compression, and gauge tail risks.

Core Features & Use Cases

• Convert indicators like CAPE, trailing P/E, forward P/E, P/B, P/S, and market cap to GDP into 0-100 percentiles based on long-run history.
• Combine metrics via mean, median, or trimmed_mean to produce a robust composite score and flag extreme periods.
• Identify historical analogs (e.g., 1929, 1965, 1999, 2021) and output post-event statistics for risk assessment and scenario planning.
• Provide a risk-interpretation framework that communicates that high valuations do not guarantee a crash but imply upper-tail risk and potential returns compression.

Quick Start

• cd skills/detect-us-equity-valuation-percentile-extreme
• pip install pandas numpy yfinance requests matplotlib openpyxl xlrd
• python scripts/visualize_valuation.py -o output
• python scripts/valuation_percentile.py --quick
• python scripts/valuation_percentile.py --as_of_date 2026-01-21 --universe "^GSPC" --metrics "cape,mktcap_to_gdp,trailing_pe,pb" --output result.json