zeberg-salomon-rotator Skill

<essential_principles>

<principle name="two_state_model"> **兩態切換模型核心**

Zeberg–Salomon 模型將市場簡化為兩種狀態：

RISK_ON: 持有股票（SPY），景氣擴張期
RISK_OFF: 持有長債（TLT），景氣收縮期

切換邏輯基於「領先指標先轉弱，同時指標後確認」的景氣循環規律。 </principle>

<principle name="leading_coincident"> **領先 vs 同時指標**

| 類型 | 作用 | 典型成分 | 領先時間 | |------------|------|------------------------------|----------| | Leading | 預警 | 殖利率曲線、新訂單、房市許可 | 6-12 月 | | Coincident | 確認 | 就業、工業生產、實質收入 | 同步 |

合成方式：

各序列做 transform（yoy/mom/diff）
統一方向（direction +1/-1）
Rolling z-score 標準化
EMA 平滑
加權合成 </principle>

<principle name="iceberg_sinking"> **冰山事件 vs 下沉事件**

Iceberg Event: LeadingIndex < iceberg_threshold
  → 預警：景氣開始轉弱
  → 搭配「領先指標下降」+ 可選「市場亢奮」濾鏡

Sinking Event: CoincidentIndex < sinking_threshold
  → 確認：實體經濟收縮
  → 通常在 Iceberg 之後數月發生

狀態機邏輯：

RISK_ON → RISK_OFF：Iceberg 連續確認 + 斜率為負
RISK_OFF → RISK_ON：領先指標回升超過 (threshold + hysteresis) </principle>

<principle name="data_access"> **資料取得方式**

本 skill 使用無需 API key 的資料來源：

FRED CSV: https://fred.stlouisfed.org/graph/fredgraph.csv?id={SERIES_ID}
Yahoo Finance: yfinance 套件抓取 SPY, TLT, VIX

腳本位於 scripts/ 目錄，可直接執行。 </principle>

</essential_principles>

<objective> 實作 Zeberg–Salomon 兩態輪動策略：

建構指標：從 FRED 數據合成 LeadingIndex 與 CoincidentIndex
偵測事件：識別「冰山」（領先轉弱）與「下沉」（同時確認）
切換訊號：產生 RISK_ON ↔ RISK_OFF 切換事件
回測績效：計算累積報酬、MaxDD、CAGR、與 benchmark 比較

輸出：切換事件清單、指標時間序列、回測摘要、診斷資訊。 </objective>

<quick_start>

最快的方式：執行預設回測

cd skills/zeberg-salomon-rotator
pip install pandas numpy yfinance pandas-datareader  # 首次使用
python scripts/rotator.py --quick

輸出範例：

{
  "state": "RISK_ON",
  "latest_indices": {"LeadingIndex": 0.41, "CoincidentIndex": 0.22},
  "iceberg_event": false,
  "sinking_event": false,
  "last_switch": {"date": "2023-06-30", "action": "EXIT_LONG_BOND_ENTER_EQUITY"}
}

完整回測：

python scripts/rotator.py --start 2000-01-01 --end 2026-01-01 --output result.json

</quick_start>

<intake> 需要進行什麼操作？

快速檢查 - 查看目前的景氣狀態與最新指標
完整回測 - 執行完整的歷史回測與績效分析
視覺化圖表 - 生成多面板回測結果圖表
監控模式 - 設定持續監控與切換警報
方法論學習 - 了解 Zeberg-Salomon 模型的邏輯

請選擇或直接提供分析參數。 </intake>

<routing> | Response | Action | |-------------------------------|---------------------------------------------| | 1, "快速", "quick", "check" | 執行 `python scripts/rotator.py --quick` | | 2, "回測", "backtest", "full" | 閱讀 `workflows/backtest.md` 並執行 | | 3, "視覺化", "chart", "plot" | 閱讀 `workflows/visualize.md` 並執行 | | 4, "監控", "monitor", "alert" | 閱讀 `workflows/monitor.md` 並執行 | | 5, "學習", "方法論", "why" | 閱讀 `references/methodology.md` | | 提供參數 (如日期範圍) | 閱讀 `workflows/backtest.md` 並使用參數執行 |

路由後，閱讀對應文件並執行。 </routing>

<directory_structure>

zeberg-salomon-rotator/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── backtest.md                    # 完整回測工作流
│   ├── visualize.md                   # 視覺化工作流
│   ├── monitor.md                     # 持續監控工作流
│   └── analyze.md                     # 深度分析工作流
├── references/
│   ├── data-sources.md                # FRED 系列代碼與資料來源
│   ├── methodology.md                 # Zeberg-Salomon 方法論解析
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
└── scripts/
    ├── rotator.py                     # 主輪動腳本
    ├── visualize.py                   # 視覺化繪圖工具
    └── fetch_data.py                  # 數據抓取工具

</directory_structure>

<reference_index>

方法論: references/methodology.md

Zeberg-Salomon 模型概念
冰山/下沉事件定義
兩態切換邏輯

資料來源: references/data-sources.md

FRED 系列代碼（領先/同時）
Yahoo Finance 資產代碼
數據頻率與對齊

輸入參數: references/input-schema.md

完整參數定義
預設值與建議範圍

</reference_index>

<workflows_index> | Workflow | Purpose | 使用時機 | |--------------|----------------|------------------| | backtest.md | 完整歷史回測 | 需要績效分析時 | | visualize.md | 生成視覺化圖表 | 需要圖表展示時 | | monitor.md | 持續監控狀態 | 日常監控或警報 | | analyze.md | 深度指標分析 | 理解當前市場狀態 | </workflows_index>

<templates_index> | Template | Purpose | |--------------------|-------------------| | output-json.md | JSON 輸出結構定義 | | output-markdown.md | Markdown 報告模板 | </templates_index>

<scripts_index> | Script | Command | Purpose | |---------------|-------------------------------|------------------| | rotator.py | --quick | 快速檢查當前狀態 | | rotator.py | --start DATE --end DATE | 完整回測 | | visualize.py | -i result.json -o chart.png | 生成視覺化圖表 | | fetch_data.py | --series T10Y3M,PAYEMS | 抓取 FRED 資料 | </scripts_index>

<input_schema_summary>

核心參數

| 參數 | 類型 | 預設值 | 說明 | |--------------|--------|------------|--------------| | start_date | string | 2000-01-01 | 回測起始日 | | end_date | string | today | 回測結束日 | | freq | string | M | 頻率（M=月） | | equity_proxy | string | SPY | 風險資產代理 | | bond_proxy | string | TLT | 長債代理 |

門檻參數

| 參數 | 類型 | 預設值 | 說明 | |-------------------|--------|--------|--------------| | iceberg_threshold | number | -0.3 | 領先指標門檻 | | sinking_threshold | number | -0.5 | 同時指標門檻 | | confirm_periods | int | 2 | 連續確認期數 | | hysteresis | number | 0.15 | 進出場間距 |

完整參數定義見 references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "zeberg-salomon-rotator",
  "as_of": "2026-01-14",
  "state": "RISK_ON",
  "latest_indices": {
    "LeadingIndex": 0.41,
    "CoincidentIndex": 0.22,
    "iceberg_event": false,
    "sinking_event": false
  },
  "switch_events": [...],
  "backtest_summary": {
    "cagr": 0.123,
    "max_drawdown": -0.27,
    "turnovers": 10
  }
}

完整輸出結構見 templates/output-json.md。 </output_schema_summary>

<success_criteria> 執行成功時應產出：

[ ] 當前狀態（RISK_ON 或 RISK_OFF）
[ ] LeadingIndex 與 CoincidentIndex 數值
[ ] 冰山/下沉事件判定
[ ] 切換事件清單（含日期、原因）
[ ] 回測績效摘要（CAGR, MaxDD, 換手次數）
[ ] 與 benchmark 比較（買入持有、60/40）
[ ] 診斷資訊（各指標貢獻）
[ ] 視覺化圖表（可選，輸出至 output/ 目錄） </success_criteria>

Agent Skills: zeberg-salomon-rotator

Install this agent skill to your local

Skill Files