detect-us-equity-valuation-percentile-extreme

<essential_principles>

Convert valuation metrics with different units (PE, PB, CAPE, etc.) uniformly into "historical percentiles from 0-100":

• Percentile = 100 × (number of historical samples ≤ current value / total number of samples)
• Example: CAPE is at the 98th historical percentile → over the past 130 years, only 2% of the time was more expensive than now
• After unifying the units, a "composite valuation percentile" can be synthesized across metrics

Composite formula:composite_percentile = 加權平均(各指標分位數)

Three composition methods are supported:

Method	Formula	Applicable scenario
mean	Arithmetic mean	All metrics are equally important
median	Median	Resists abnormal upward distortion by a single metric
trimmed_mean	Trimmed mean	Robust estimation

Important: Each metric may have a different historical length; by default, percentiles are calculated using "each metric's own history" and then combined.

if composite_percentile >= extreme_threshold (預設 95):
    → 判定「歷史極端高估」
    → 觸發風險解讀流程

Identification of historical analogy events:

1. Find peaks where the composite percentile exceeds the threshold
2. Use episode_min_gap_days for deduplication (by default, keep only the highest point within 10 years)
3. Output: 1929, 1965, 1999, 2021, current...

"Extremely high valuation" ≠ "a crash tomorrow", but the historical characteristics are:

• Asymmetric risk distribution: the downside tail becomes fatter
• Compressed medium-term future returns: mean reversion in valuation lowers the upper limit of long-term returns
• Volatility rises first and then falls: volatility usually rises 6-12 months after the event

Output post-event statistics:

• Return distribution over the next 180/365/1095 days
• Median maximum drawdown and tail risk
• Probability of volatility changes

This skill usespublic alternative data, not raw Bloomberg data:

• Shiller CAPE: Robert Shiller public dataset (goes back to 1871)
• Market cap/GDP: FRED public data (goes back to the 1950s)
• PE/PB/PS: Public financial data (shorter history, about 30-50 years)

Must disclose：

• The available periods of each metric differ
• The composite percentile is an "approximate reconstruction", not an exact replication

</essential_principles>

1. Collect valuation metrics: Obtain PE, CAPE, PB, PS, market cap/GDP, etc. from public data sources
2. Calculate percentiles: Convert each metric into a historical percentile (0-100)
3. Composite total score: Weighted average (or median) to obtain the composite valuation percentile
4. Determine extremity: If the total score ≥ threshold (default 95), trigger an extreme overvaluation alert
5. Historical analogy: Find similar historical events (1929, 1965, 1999, etc.)
6. Post-event statistics: Calculate the returns, drawdowns, and volatility changes after these events

Output: current status, percentiles of each metric, historical analogy events, risk interpretation.

<quick_start>

The fastest way: run visual analysis

cd skills/detect-us-equity-valuation-percentile-extreme
pip install pandas numpy yfinance requests matplotlib openpyxl xlrd  # 首次使用
python scripts/visualize_valuation.py -o output

Output:

• output/us_valuation_percentile_YYYY-MM-DD.png - Historical trend chart (similar to @ekwufinance style)
• output/us_valuation_breakdown_YYYY-MM-DD.png - Individual indicator percentile decomposition chart
• output/us_valuation_analysis_YYYY-MM-DD.json - JSON results

Chart features：

• Multi-indicator composite percentilehistorical trend(not a single point in time)
• Historical peak markers：1929、1965、1999、2021
• S&P 500 index overlay (logarithmic scale)
• Current "new high" annotation

Quick check (pure JSON)：

python scripts/valuation_percentile.py --quick

Full analysis：

python scripts/valuation_percentile.py \
  --as_of_date 2026-01-21 \
  --universe "^GSPC" \
  --metrics "cape,mktcap_to_gdp,trailing_pe,pb" \
  --output result.json

</quick_start>

1. Visualization analysis (recommended) - Generate historical trend charts and mark historical peaks
2. Quick check - View current valuation percentiles and extreme states
3. Full analysis - Run a complete historical percentile analysis and risk interpretation
4. Historical analogy - In-depth analysis of historical extreme overvaluation events and subsequent performance
5. Methodology learning - Understand the logic of the valuation percentile model
6. Custom parameters - Specify valuation indicators, thresholds, composition method, etc.

Please select or directly provide analysis parameters.

After routing, read the corresponding document and execute.

<directory_structure>

detect-us-equity-valuation-percentile-extreme/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── execute-analysis.md            # 完整分析工作流
│   ├── visualize-analysis.md          # 視覺化分析工作流
│   └── historical-episodes.md         # 歷史類比分析工作流
├── references/
│   ├── methodology.md                 # 估值分位數方法論
│   ├── data-sources.md                # 資料來源與代碼
│   ├── valuation-metrics.md           # 估值指標定義
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
├── scripts/
│   ├── valuation_percentile.py        # 主分析腳本
│   ├── visualize_valuation.py         # 視覺化腳本（歷史走勢圖）
│   └── fetch_valuation_data.py        # 資料抓取工具
└── examples/
    └── sample_output.json             # 範例輸出

</directory_structure>

<reference_index>

Methodology: references/methodology.md

• Principle of percentile normalization
• Multi-indicator composition logic
• Extreme detection and historical analogy

Data sources: references/data-sources.md

• Shiller CAPE dataset
• FRED series codes
• Public alternative data documentation

Valuation indicators: references/valuation-metrics.md

• PE, Forward PE, CAPE definitions
• PB, PS, EV/EBITDA definitions
• Q Ratio, Market Cap/GDP definitions

Input parameters: references/input-schema.md

• Full parameter definitions
• Default values and recommended ranges

</reference_index>

<workflows_index>

Workflow	Purpose	When to use
execute-analysis.md	Full valuation analysis	When a complete report is needed
historical-episodes.md	In-depth analysis of historical events	Understand historical analogies and subsequent statistics
</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
visualize_valuation.py	-o output	Visualization analysis (recommended)
valuation_percentile.py	--quick	Quickly check the current state
valuation_percentile.py	--as_of_date DATE --output FILE	Full analysis
fetch_valuation_data.py	--metrics cape,pe	Fetch valuation data
</scripts_index>

<input_schema_summary>

Core parameters

Parameter	Type	Default value	Description
as_of_date	string	today	Valuation date
universe	string	^GSPC	Market code
history_start	string	1900-01-01	History start date
metrics	array	[cape, ...]	Valuation indicator list
aggregation	string	mean	Composition method

Threshold parameters

Parameter	Type	Default value	Description
extreme_threshold	number	95	Extreme overvaluation threshold (percentile)
episode_min_gap_days	int	3650	Historical event deduplication interval
forward_windows_days	array	[180, 365, 1095]	Subsequent statistics window

For full parameter definitions, see references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "detect-us-equity-valuation-percentile-extreme",
  "as_of_date": "2026-01-21",
  "universe": "^GSPC",
  "composite_percentile": 97.3,
  "extreme_threshold": 95,
  "is_extreme": true,
  "metric_percentiles": {
    "cape": 98.2,
    "mktcap_to_gdp": 96.5,
    "trailing_pe": 94.1
  },
  "historical_episodes": [
    {"date": "1929-09-01", "composite_percentile": 97.8},
    {"date": "1999-12-01", "composite_percentile": 98.5}
  ],
  "forward_stats": {
    "365d_forward_return": {"median": -8.2, "p25": -22.1, "p10": -38.5},
    "1095d_max_drawdown": {"median": -28.4, "p75": -42.1}
  },
  "data_quality_notes": [
    "CAPE 資料可回溯至 1871 年",
    "市值/GDP 資料可回溯至 1950 年代",
    "合成分位數使用各指標自身歷史分布"
  ]
}

For the full output structure, see templates/output-json.md。 </output_schema_summary>

<success_criteria> On successful execution, it should produce:

• Current composite valuation percentile (0-100)
• Individual percentile for each indicator
• Extreme overvaluation determination (yes/no)
• List of historical analogy events (date, percentile)
• Subsequent statistics (returns, drawdowns, volatility)
• Data quality notes (available period for each indicator)
• Risk interpretation framework (optional, output to Markdown)

Visualization output(using visualize_valuation.py):

• Historical trend chart (us_valuation_percentile_YYYY-MM-DD.png）
  • Multi-indicator composite percentile time series
  • Historical peak markers (1929, 1965, 1999, 2021)
  • S&P 500 index overlay (logarithmic scale)
  • Current position annotation
• Indicator decomposition chart (us_valuation_breakdown_YYYY-MM-DD.png）
  • Horizontal bar chart of each indicator's percentile
  • Extreme threshold reference lines
• JSON result file (us_valuation_analysis_YYYY-MM-DD.json） </success_criteria>