| name | detect-us-equity-valuation-percentile-extreme |
| description | 把多個股票估值指標統一轉成在過去百年歷史中的分位數，再合成一個總分，判斷目前是否處於歷史極端高估區間，並用歷史類比（如 1929、1965、1999）給出風險解讀。 |
<essential_principles>
**分位數標準化核心**
將不同單位的估值指標（PE、PB、CAPE 等）統一成「0-100 的歷史分位數」：
- 分位數 = 100 × (歷史中 ≤ 當前值的樣本數 / 總樣本數)
- 例：CAPE 位於歷史第 98 分位 → 過去 130 年只有 2% 的時間比現在更貴
- 統一單位後，可跨指標合成「綜合估值分位數」
**多指標合成邏輯**
合成公式：composite_percentile = 加權平均(各指標分位數)
支援三種合成方式：
| 方式 | 公式 | 適用場景 |
|---|
| mean | 算術平均 | 各指標同等重要 |
| median | 中位數 | 抵抗單一指標異常拉升 |
| trimmed_mean | 去極端平均 | 穩健估計 |
重要：各指標可能有不同歷史長度，預設使用「各自歷史」計算分位數再合成。
**極端高估偵測邏輯**
if composite_percentile >= extreme_threshold (預設 95):
→ 判定「歷史極端高估」
→ 觸發風險解讀流程
歷史類比事件識別：
- 找出合成分位數超過門檻的峰值
- 用
episode_min_gap_days 去重（預設 10 年內只保留最高點）
- 輸出：1929、1965、1999、2021、當前...
**風險解讀框架**
「估值極端高」≠「明天崩盤」，但歷史特徵是：
- 風險分布不對稱：下跌尾巴變厚
- 未來中期報酬壓縮：估值均值回歸壓低長期報酬上限
- 波動先升後跌：事件後 6-12 月波動率通常上升
輸出事後統計：
- 未來 180/365/1095 天報酬分布
- 最大回撤中位數與尾部風險
- 波動率變化機率
**資料來源與限制揭露**
本 skill 使用公開替代資料，非彭博原始數據：
- Shiller CAPE: Robert Shiller 公開資料集（可回溯至 1871 年）
- 市值/GDP: FRED 公開數據（可回溯至 1950 年代）
- PE/PB/PS: 公開金融資料（歷史較短，約 30-50 年）
必須揭露：
- 各指標可得期間不同
- 合成分位數為「近似重建」，非精確複製
</essential_principles>
偵測美股估值是否處於歷史極端區間：
- 收集估值指標：從公開數據源取得 PE、CAPE、PB、PS、市值/GDP 等
- 計算分位數：將各指標轉換為歷史分位數（0-100）
- 合成總分：加權平均（或中位數）得到綜合估值分位數
- 判定極端：若總分 ≥ 門檻（預設 95），觸發極端高估警報
- 歷史類比：找出歷史上的類似事件（1929、1965、1999 等）
- 事後統計：計算這些事件後的報酬、回撤、波動變化
輸出：當前狀態、各指標分位數、歷史類比事件、風險解讀。
<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
輸出：
output/us_valuation_percentile_YYYY-MM-DD.png - 歷史走勢圖（類似 @ekwufinance 風格）output/us_valuation_breakdown_YYYY-MM-DD.png - 各指標分位數分解圖output/us_valuation_analysis_YYYY-MM-DD.json - JSON 結果
圖表特色：
- 多指標合成分位數的歷史走勢（非單一時間點）
- 歷史峰值標記：1929、1965、1999、2021
- S&P 500 指數疊加（對數刻度）
- 當前「新高」標註
快速檢查（純 JSON）：
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
</quick_start>
需要進行什麼操作？
- 視覺化分析（推薦） - 生成歷史走勢圖表，標記歷史峰值
- 快速檢查 - 查看目前的估值分位數與極端狀態
- 完整分析 - 執行完整的歷史分位數分析與風險解讀
- 歷史類比 - 深入分析歷史極端高估事件與事後表現
- 方法論學習 - 了解估值分位數模型的邏輯
- 自訂參數 - 指定估值指標、門檻、合成方式等
請選擇或直接提供分析參數。
| Response | Action |
|----------------------------------|----------------------------------------------|
| 1, "視覺化", "圖表", "chart" | 執行 `python scripts/visualize_valuation.py -o output` |
| 2, "快速", "quick", "check" | 執行 `python scripts/valuation_percentile.py --quick` |
| 3, "完整", "full", "analysis" | 閱讀 `workflows/execute-analysis.md` 並執行 |
| 4, "歷史", "類比", "episodes" | 閱讀 `workflows/historical-episodes.md` 並執行 |
| 5, "學習", "方法論", "why" | 閱讀 `references/methodology.md` |
| 6, "自訂", "custom", 提供參數 | 閱讀 `workflows/execute-analysis.md` 並使用參數執行 |
路由後，閱讀對應文件並執行。
<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>
方法論: references/methodology.md
- 分位數標準化原理
- 多指標合成邏輯
- 極端偵測與歷史類比
資料來源: references/data-sources.md
- Shiller CAPE 資料集
- FRED 系列代碼
- 公開替代資料說明
估值指標: references/valuation-metrics.md
- PE、Forward PE、CAPE 定義
- PB、PS、EV/EBITDA 定義
- Q Ratio、市值/GDP 定義
輸入參數: references/input-schema.md
</reference_index>
<workflows_index>
| Workflow | Purpose | 使用時機 |
|---|
| execute-analysis.md | 完整估值分析 | 需要完整報告時 |
| historical-episodes.md | 歷史事件深度分析 | 理解歷史類比與事後統計 |
| </workflows_index> | | |
<templates_index>
| Template | Purpose |
|---|
| output-json.md | JSON 輸出結構定義 |
| output-markdown.md | Markdown 報告模板 |
| </templates_index> | |
<scripts_index>
| Script | Command | Purpose |
|---|
| visualize_valuation.py | -o output | 視覺化分析（推薦） |
| valuation_percentile.py | --quick | 快速檢查當前狀態 |
| valuation_percentile.py | --as_of_date DATE --output FILE | 完整分析 |
| fetch_valuation_data.py | --metrics cape,pe | 抓取估值資料 |
| </scripts_index> | | |
<input_schema_summary>
核心參數
| 參數 | 類型 | 預設值 | 說明 |
|---|
| as_of_date | string | today | 評估日期 |
| universe | string | ^GSPC | 市場代碼 |
| history_start | string | 1900-01-01 | 歷史起算日 |
| metrics | array | [cape, ...] | 估值指標清單 |
| aggregation | string | mean | 合成方法 |
門檻參數
| 參數 | 類型 | 預設值 | 說明 |
|---|
| extreme_threshold | number | 95 | 極端高估門檻（分位數） |
| episode_min_gap_days | int | 3650 | 歷史事件去重間隔 |
| forward_windows_days | array | [180, 365, 1095] | 事後統計視窗 |
完整參數定義見 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 年代",
"合成分位數使用各指標自身歷史分布"
]
}
完整輸出結構見 templates/output-json.md。
</output_schema_summary>
<success_criteria>
執行成功時應產出：
視覺化輸出（使用 visualize_valuation.py）：
