@openfinclaw/findoo-datahub-plugin 2026.3.2 → 2026.3.10

package/skills/us-earnings/skill.md

@@ -0,0 +1,149 @@
+---
+name: fin-us-earnings
+description: "US earnings season analysis — earnings calendar, historical beat/miss patterns, pre-earnings IV/straddle pricing, post-earnings price reaction stats, earnings surprise quantification. Use when: user asks about earnings dates, beat/miss history, earnings straddle, IV crush, or earnings season overview. NOT for: single-stock fundamentals/valuation (use fin-us-equity), A-share earnings (use fin-a-share), options Greeks lookup (use fin-derivatives), macro rates (use fin-macro)."
+metadata: { "openclaw": { "emoji": "📅", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# US Earnings Season Analysis
+
+Specialized in earnings **event-driven** analysis: calendar timing, beat/miss pattern recognition, pre-earnings options pricing, and post-earnings price reaction. Complements fin-us-equity's static fundamentals with temporal/event intelligence.
+
+## When to Use
+
+- "AAPL 财报什么时候出" / "When does AAPL report earnings"
+- "NVDA 上季度 beat 了吗" / "Did NVDA beat last quarter"
+- "财报前期权怎么玩" / "Pre-earnings straddle strategy"
+- "这个财报季整体情况如何" / "How is this earnings season going"
+- "TSLA 历史上财报后涨还是跌" / "TSLA post-earnings price reaction history"
+- "哪些大公司下周报财报" / "Which mega-caps report next week"
+- "GOOGL earnings surprise 有多大" / "GOOGL earnings surprise magnitude"
+
+## When NOT to Use
+
+- 个股基本面/估值/财务报表深度分析 (PE/PB/DCF) -> use `/fin-us-equity`
+- A 股/港股财报分析 -> use `/fin-a-share` / `/fin-hk-stock`
+- 纯期权 Greeks 查询 (非 earnings 相关) -> use `/fin-derivatives`
+- 宏观利率/GDP/CPI -> use `/fin-macro`
+- 股息/分红相关 -> use `/fin-us-dividend`
+- 全市场雷达/涨跌幅排行 -> use `/fin-a-share-radar`
+
+## Tools & Parameters
+
+### fin_stock
+
+| Parameter  | Type   | Required | Format          | Default | Example    |
+| ---------- | ------ | -------- | --------------- | ------- | ---------- |
+| symbol     | string | Yes      | US ticker       | —       | AAPL       |
+| endpoint   | string | Yes      | see table below | —       | us/income  |
+| start_date | string | No       | YYYY-MM-DD      | —       | 2025-01-01 |
+| end_date   | string | No       | YYYY-MM-DD      | —       | 2026-03-07 |
+| limit      | number | No       | 1-5000          | 200     | 20         |
+| provider   | string | No       | yfinance        | auto    | yfinance   |
+
+#### Endpoints
+
+| endpoint                        | Description                    | Example                                                                      |
+| ------------------------------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `fundamental/earnings_forecast` | Analyst consensus EPS/Revenue  | `fin_stock(symbol="AAPL", endpoint="fundamental/earnings_forecast")`         |
+| `us/income`                     | Actual GAAP EPS/Revenue        | `fin_stock(symbol="AAPL", endpoint="us/income")`                             |
+| `price/historical`              | OHLCV for post-earnings moves  | `fin_stock(symbol="AAPL", endpoint="price/historical", provider="yfinance")` |
+| `fundamental/ratios`            | Forward PE for re-rate context | `fin_stock(symbol="AAPL", endpoint="fundamental/ratios")`                    |
+| `us/trade_cal`                  | US trading calendar            | `fin_stock(endpoint="us/trade_cal")`                                         |
+
+### fin_derivatives
+
+| endpoint         | Description                | Example                                                     |
+| ---------------- | -------------------------- | ----------------------------------------------------------- |
+| `options/chains` | Option chain + IV + Greeks | `fin_derivatives(endpoint="options/chains", symbol="AAPL")` |
+
+### Auxiliary
+
+| tool           | endpoint        | use case                        |
+| -------------- | --------------- | ------------------------------- |
+| `fin_currency` | `news/company`  | Earnings-related news catalyst  |
+| `fin_ta`       | `rsi`, `bbands` | Post-earnings technical context |
+
+## Earnings Season Calendar
+
+**Quarterly cadence:** Jan (Q4 results), Apr (Q1), Jul (Q2), Oct (Q3).
+
+**Reporting order:** Banks (week 2) -> Mega-cap tech (weeks 3-4) -> Mid/small-cap (weeks 4-6).
+
+**Detection method:** When no dedicated earnings calendar API is available, use `fundamental/earnings_forecast` revision activity as a proxy — a spike in consensus revisions within 2-3 weeks signals an approaching report date.
+
+## Earnings Analysis Pattern
+
+1. **Consensus snapshot** `fin_stock(endpoint="fundamental/earnings_forecast", symbol="AAPL")` — Get analyst consensus EPS and Revenue estimates
+   - Record: consensus EPS, number of analysts, high/low range
+   - ⚠️ If analyst count < 5 -> small-cap coverage thin, consensus less reliable
+   - 💡 Wide high-low range (spread > 30% of consensus) -> high uncertainty, larger potential surprise
+
+2. **Historical beat/miss pattern** `fin_stock(endpoint="us/income", symbol="AAPL", limit=12)` — Pull last 8-12 quarters of actual EPS
+   - Compare each quarter's actual EPS vs that quarter's consensus (from step 1 historical data)
+   - Count consecutive beats/misses
+   - ⚠️ If 4+ consecutive beats -> market expects a beat, whisper number is 2-5% above consensus; a mere "inline" beat may trade like a miss
+   - ⚠️ If 2+ consecutive misses with downward revisions -> negative revision cycle, de-rate risk
+   - 💡 Cross-reference: beat magnitude trending smaller each Q -> "beat fatigue", re-rate ceiling forming
+
+3. **Pre-earnings IV & straddle pricing** `fin_derivatives(endpoint="options/chains", symbol="AAPL")` — Get ATM options near next expiry
+   - Calculate ATM straddle price = (ATM Call + ATM Put) / Stock Price = implied move %
+   - Get current IV and compare to 30-day historical IV -> IV percentile
+   - ⚠️ If IV percentile > 80th -> premium expensive, selling premium (short straddle/strangle) has edge IF expected move < implied move
+   - ⚠️ If IV percentile < 40th -> unusual for pre-earnings, possible complacency or low-vol name
+   - 💡 Compare implied move vs actual moves from last 4 earnings (step 2 price data): implied > average actual -> sell bias; implied < average actual -> buy bias
+
+4. **Post-earnings price reaction** `fin_stock(endpoint="price/historical", symbol="AAPL", limit=60, provider="yfinance")` — Analyze open-to-open moves on earnings days
+   - For each of last 8 earnings dates: Gap % = (Next-day Open - Prior Close) / Prior Close
+   - Build reaction table: Date | Actual EPS | Consensus | Beat/Miss | 1-day Move | 5-day Move
+   - ⚠️ If beat + price drops pattern (3 of last 4 Qs) -> "sell the news" regime, market pricing perfection
+   - ⚠️ If miss + price rises pattern -> market looking through to forward guidance
+   - 💡 Large gap (>5%) after earnings fills only ~40% within 30 days vs common gaps (~70% fill in 3 days)
+
+5. **Earnings surprise quantification**
+   - Surprise % = (Actual EPS - Consensus EPS) / |Consensus EPS| \* 100
+   - Revenue surprise % = (Actual Revenue - Consensus Revenue) / Consensus Revenue \* 100
+   - ⚠️ If EPS beat but Revenue miss -> cost-cutting driven, not sustainable growth
+   - ⚠️ If Revenue beat but EPS miss -> investment phase (bullish if margin trajectory intact)
+   - 💡 Cross-validate with step 4: large positive surprise + negative price reaction = high bar already embedded
+
+6. **Earnings season dashboard** (when user asks about overall season)
+   - Identify current season phase (early/mid/late) based on calendar
+   - Estimate sector-level beat rates from mega-cap bellwethers already reported
+   - 💡 If bank earnings (JPM/GS) set negative tone -> historically drags sentiment for 1-2 weeks
+   - 💡 If mega-cap tech all beat -> risk-on for rest of season, but concentration risk caveat
+
+## Data Notes
+
+- **Earnings calendar**: No dedicated calendar API. Use `fundamental/earnings_forecast` revision spikes + seasonal pattern (Jan/Apr/Jul/Oct) as proxy. Mega-cap dates are well-known and can be stated.
+- **US quotes**: yfinance, ~15min delay. Use `provider="yfinance"` for `price/historical`.
+- **Consensus EPS**: `fundamental/earnings_forecast` (tushare). Small-cap (<$2B) may lack analyst coverage.
+- **Options chains**: yfinance, ~15min delay. Greeks included (Delta/Gamma/Vega/Theta/IV).
+- **Whisper numbers**: Not available via API. Approximate as consensus + 2-5% for mega-cap names with strong beat streaks.
+- **Guidance**: Structured guidance data not available. Infer from `us/income` revenue trajectory and `earnings_forecast` revision direction.
+
+## Response Guidelines
+
+### Dollar Format
+
+- EPS: $1.52 / -$0.08 (2 decimal places, always show sign for surprise)
+- Revenue: $94.3B / $2.1B (use $B/$M shorthand)
+- Stock price: $192.53 (2 decimal places)
+- Surprise: +4.2% / -1.8% (always show +/- sign)
+- IV: 45.2% (1 decimal place)
+- Implied move: +/-3.8% (show as range)
+
+### Must Include
+
+- Data cutoff date ("Data as of 2026-03-07")
+- Consensus source note when citing EPS estimates
+- Beat/miss streak count (e.g., "Beat 6 of last 8 quarters")
+- Pre-earnings: days until report + market session (before/after market)
+- Post-earnings: actual vs consensus + surprise % + price reaction
+
+### Display Format
+
+- Single stock earnings deep-dive -> structured sections: Consensus | Beat/Miss History | IV Analysis | Price Reaction Table
+- Beat/miss history -> table with columns: Quarter | Actual EPS | Consensus | Surprise % | 1-Day Move
+- Earnings season overview -> sector-level summary table
+- Pre-earnings options -> show implied move vs historical average move comparison
+- Always end with actionable insight: "Based on patterns, key risk/opportunity is..."

package/skills/us-equity/skill.md

@@ -0,0 +1,235 @@
+---
+name: fin-us-equity
+description: "US equity analysis — GAAP financials (us/income), earnings beat/miss with revision cycle, options strategy selection (IV/Greeks via options/chains), Fed rate sensitivity, sector rotation. Data via massive + yfinance. Use when: user mentions US tickers (AAPL/NVDA/TSLA/MSFT), asks about US earnings, options strategies, or Fed impact on equities. NOT for: A-shares (use fin-a-share), HK stocks (use fin-hk-stock), crypto (use fin-crypto), US macro rates only (use fin-macro), US index options (use fin-derivatives)."
+metadata: { "openclaw": { "emoji": "🇺🇸", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# US Equity Analysis
+
+Use **fin_stock**, **fin_derivatives**, and auxiliary tools for US equity analysis. All data routes through DataHub.
+
+## Symbol Format
+
+US tickers: `AAPL`, `NVDA`, `TSLA`, `MSFT` (no suffix, no exchange code)
+
+## Available Endpoints (US)
+
+### fin_stock (12 endpoints)
+
+| endpoint                        | data                       | use case                                 |
+| ------------------------------- | -------------------------- | ---------------------------------------- |
+| `price/historical`              | OHLCV                      | price trend, technical overlay           |
+| `us/income`                     | US GAAP income statement   | revenue/EPS/margin, quarterly comparison |
+| `fundamental/ratios`            | PE/PB/ROE/margins          | valuation snapshot, sector comparison    |
+| `fundamental/metrics`           | EV/EBITDA                  | cross-method valuation, comps            |
+| `fundamental/earnings_forecast` | analyst consensus EPS      | PEG calc, earnings surprise detection    |
+| `fundamental/dividends`         | dividend history           | DDM input, yield analysis                |
+| `profile`                       | company overview           | sector, description, market cap          |
+| `discovery/gainers`             | top US gainers (no symbol) | market scan                              |
+| `discovery/losers`              | top US losers (no symbol)  | market scan                              |
+| `us/adj_factor`                 | 复权因子                   | 长期回测价格调整                         |
+| `us/trade_cal`                  | 美股交易日历               | 财报季/节假日自动化                      |
+| `historical_splits`             | 拆股历史                   | 长期回测需要拆股调整                     |
+
+### fin_derivatives (US Options)
+
+| endpoint         | data                                                       | use case                        |
+| ---------------- | ---------------------------------------------------------- | ------------------------------- |
+| `options/chains` | full option chain with Greeks (Delta/Gamma/Vega/Theta, IV) | strategy selection, IV analysis |
+
+### Auxiliary Tools
+
+| tool              | endpoint                              | use case                         |
+| ----------------- | ------------------------------------- | -------------------------------- |
+| `fin_macro`       | `treasury_us`                         | 10Y yield for DCF risk-free rate |
+| `fin_macro`       | `libor`                               | USD rate reference               |
+| `fin_macro`       | `news/company`                        | company news for US tickers      |
+| `fin_ta`          | `sma`, `ema`, `rsi`, `macd`, `bbands` | technical overlay                |
+| `fin_data_ohlcv`  | `symbol=AAPL, market=equity`          | OHLCV time series                |
+| `fin_data_regime` | `symbol=AAPL, market=equity`          | bull/bear/sideways regime        |
+
+**预计算技术因子:** `fin_stock(fundamental/stock_factor)` → MACD/KDJ/RSI/BOLL/CCI 预计算值（tushare 美股覆盖），可替代逐个 fin_ta 调用。
+
+## Data Sources
+
+| Provider | Coverage                       | Notes              |
+| -------- | ------------------------------ | ------------------ |
+| massive  | OHLCV + fundamentals           | needs API key      |
+| yfinance | price + fundamentals + options | free, ~15min delay |
+
+> **⚠️ US 股票 Provider 注意事项:**
+>
+> - `price/historical` 默认 tushare provider，对 US 股票返回 500；**必须添加 `provider="yfinance"`**
+> - `fundamental/ratios` 仅 tushare provider 可用，对 US 股票返回 204；改用 `fundamental/metrics` (massive) 或 `us/income` 手动计算
+> - `fundamental/balance` 路径正确（非 `us/balance`），需确认 provider 支持
+
+## Analysis Patterns
+
+### Earnings Analysis Tree (US Core)
+
+```
+Step 1: fin_stock(endpoint="fundamental/earnings_forecast", symbol="AAPL") -> consensus EPS
+Step 2: fin_stock(endpoint="us/income", symbol="AAPL") -> actual EPS/revenue
+  |-- Beat + guidance raised -> "beat and raise" -> positive revision cycle -> re-rate
+  |-- Beat + guidance cut -> "beat and lower" -> mixed -> watch next Q
+  |-- Miss + guidance raised -> market forgives -> potential opportunity
+  +-- Miss + guidance cut -> negative revision cycle -> valuation compression
+Step 3: fin_stock(endpoint="price/historical", symbol="AAPL") -> post-earnings price reaction
+  |-- Beat + price drops -> "sell the news" / priced-in / whisper number was higher
+  +-- Miss + price rises -> market looks through to forward guidance
+```
+
+**Revision cycle:** 3+ consecutive beats with upward revisions -> re-rate; 2+ misses with downward revisions -> de-rate. Track via `earnings_forecast` consensus changes QoQ.
+
+注意: `estimates/consensus` 通过 yfinance 获取，存在频率限制 (rate limit)，高频调用可能 429。备选: `fundamental/earnings_forecast` (tushare, 无限流)。
+
+**Whisper number:** Buy-side "whisper" is typically 2-5% above consensus. A <2% beat on high-expectations names often trades like a miss.
+
+**Earnings season:** Jan (Q4), Apr (Q1), Jul (Q2), Oct (Q3). Banks (week 2) -> mega-cap tech (week 3-4) -> mid/small-cap (weeks 4-6). Consensus revision spike in `earnings_forecast` = approaching report.
+
+### Options Strategy Selector (US Only)
+
+`fin_derivatives(endpoint="options/chains", symbol="AAPL")` -> ATM IV, Greeks, expiry chain. Rank IV against historical percentile:
+
+| IV Level      | Bullish                    | Bearish               | Neutral        |
+| ------------- | -------------------------- | --------------------- | -------------- |
+| Low (<30th)   | Buy Call / Bull Spread     | Buy Put               | Long Straddle  |
+| Mid (30-70th) | Bull Call Spread           | Bear Put Spread       | Iron Condor    |
+| High (>70th)  | Sell Put / Bull Put Spread | Sell Call / Bear Call | Short Strangle |
+
+**Earnings straddle:** Pre-earnings IV = 1.5-3x normal. Expected move = ATM straddle / stock price. Compare to last 4 Qs actual moves (`price/historical` open-to-open). Expected > avg -> sell bias; < avg -> buy bias. IV crush collapses 40-60%. Entry: 5-7 days before; exit: at announcement.
+
+### Fed Rate Sensitivity (US Only)
+
+```
+fin_macro(endpoint="treasury_us") -> 10Y yield; fin_stock(endpoint="fundamental/ratios") -> PE
+  |-- Rate rising + high PE -> rotate to value | Rate falling + low PE -> growth rebounds
+  +-- Rate stable -> fundamentals-driven stock picking
+```
+
+**Rate chain:** Fed funds -> 2Y -> 10Y -> ERP -> PE compression/expansion. Duration: tech (high), financials (inverse), utilities (high), energy (low).
+
+| Phase            | Favored                    | Avoid                    | Signal                        |
+| ---------------- | -------------------------- | ------------------------ | ----------------------------- |
+| Early easing     | Tech, Cons Disc, RE        | Energy, Materials        | 10Y falling, curve steepening |
+| Late easing      | Mega-cap growth, Small-cap | Utilities, Staples       | 10Y bottoming, spreads tight  |
+| Early tightening | Financials, Energy         | Long-duration, REITs     | 10Y rising, curve flattening  |
+| Late tightening  | Staples, Healthcare, Utils | Cyclicals, high-leverage | 10Y peaking, curve inverting  |
+
+### US Valuation (DCF)
+
+```
+Step 1: fin_macro(endpoint="treasury_us") -> Rf (10Y yield)
+Step 2: WACC = Rf + Beta * ERP(4-6%) + spread; Terminal growth = 2-3% (US GDP proxy)
+Step 3: fin_stock(endpoint="fundamental/metrics") -> EV/EBITDA comps cross-check
+```
+
+### Technical + Regime
+
+```
+Step 1: fin_data_ohlcv(symbol="AAPL", market="equity") -> OHLCV
+Step 2: fin_ta(indicator="sma/rsi/macd/bbands") -> overlay
+Step 3: fin_data_regime(symbol="AAPL", market="equity")
+  |-- Bull + RSI<40 -> pullback buy | Bear + RSI>70 -> rally sell
+  +-- Sideways + BBands squeeze -> breakout imminent
+```
+
+## US-Specific Patterns
+
+### Magnificent 7 / Mega-Cap Concentration
+
+Mag7 (AAPL, MSFT, NVDA, GOOG, AMZN, META, TSLA) = 25-35% of S&P 500 weight.
+
+```
+Step 1: For each Mag7: fin_stock(endpoint="fundamental/metrics") -> market cap, FCF
+         fin_stock(endpoint="fundamental/ratios") -> PE; fin_stock(endpoint="us/income") -> revenue growth
+Step 2: fin_data_ohlcv(market="equity") -> price perf; compare vs fin_index(endpoint="global_index") SPX
+  |-- Mag7 outperforming + breadth narrowing -> concentration risk -> hedging warranted
+  |-- Mag7 lagging + breadth expanding -> healthy rotation -> equal-weight favored
+  +-- Mag7 diverging -> stock-pick within group via earnings/growth differential
+```
+
+**Key Mag7 metrics:** Forward PE (`earnings_forecast`), revenue growth (`us/income` sequential Qs), FCF yield (`fundamental/metrics`). NVDA at 2-3x group PE justified only if AI growth sustains 40%+ YoY.
+
+### Dividend Aristocrats
+
+```
+Step 1: fin_stock(endpoint="fundamental/dividends", symbol="JNJ") -> dividend history
+Step 2: Count consecutive years of dividend growth (annual totals YoY)
+  |-- 25+ years -> Aristocrat | 10-24 -> Achiever | <10 or any cut -> not qualified
+Step 3: fin_stock(endpoint="fundamental/ratios", symbol="JNJ") -> payout ratio, ROE
+  |-- Payout < 60% + ROE > 15% -> sustainable | 60-80% -> watch | >80% -> at risk
+Step 4: Yield vs 10Y Treasury (fin_macro endpoint="treasury_us")
+  |-- Spread > 1.5% -> attractive income | Spread < 0% -> bonds win
+```
+
+Classic sectors: Industrials (MMM, CAT), Healthcare (JNJ, ABT), Staples (PG, KO, PEP).
+
+### Revenue Quality — SaaS (Rule of 40)
+
+```
+Step 1: fin_stock(endpoint="us/income", symbol="CRM") -> last 8 quarterly revenues
+Step 2: Revenue growth % = (Q_latest / Q_year_ago - 1) * 100
+         Gross margin = gross profit / revenue; Op margin = op income / revenue
+         Rule of 40 = Revenue growth % + Op margin %
+  |-- >40% -> elite SaaS (premium PE) | 25-40% -> solid | <25% -> problem
+Step 3: QoQ revenue acceleration across 4 quarters
+  |-- Accelerating + margin expanding -> strongest signal
+  +-- Decelerating + margin compressing -> re-rate risk
+```
+
+### Total Shareholder Yield (Dividend + Buyback)
+
+S&P 500: ~$1T buybacks vs ~$600B dividends annually. Mega-cap tech: buyback yield 3-5%, dividend <1%.
+
+```
+fin_stock(endpoint="fundamental/dividends") -> div/share
+fin_stock(endpoint="fundamental/metrics") -> market cap, FCF
+Buyback yield = (FCF - Dividends) / Mkt cap; Total yield = Div yield + Buyback yield
+  |-- >5% -> aggressive (AAPL/META) | 2-5% -> moderate | <2% -> growth reinvestor
+```
+
+### Pre/Post-Market Gap Analysis
+
+```
+Step 1: fin_stock(endpoint="price/historical", symbol="TSLA") -> multi-day OHLCV
+Step 2: Gap % = (Open - prior Close) / prior Close * 100
+  |-- >3% + vol >2x -> breakaway | >3% + normal vol -> exhaustion | <-3% + vol >2x -> breakdown
+  +-- 0.5-3% -> common gap (fills ~70% in 3 days); earnings gaps >5% fill only ~40% in 30 days
+```
+
+### Short Squeeze & Institutional Proxies
+
+No short interest / 13F — use price + volume signatures.
+
+```
+Squeeze: fin_data_ohlcv + fin_ta(rsi) -> price >10%/day + vol >5x avg + RSI <30->70 in 5 days
+  + fundamental/metrics -> small/mid (<$10B) = high squeeze prob; large = news-driven
+Institutional: price/historical vol >3x avg + news/company no catalyst = stealth accumulation
+  + fin_data_regime bear->bull + vol spike = institutional re-entry
+```
+
+## DataHub Gaps (US)
+
+| Missing           | Workaround                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
+| Earnings calendar | `earnings_forecast` revision spikes signal approaching report + season calendar (Jan/Apr/Jul/Oct) |
+| 13F holdings      | `price/historical` vol >2x avg without news = institutional flow proxy                            |
+| Short interest    | Price >10%/day + vol >5x avg + RSI whipsaw = squeeze proxy (see pattern above)                    |
+| Sector ETF flows  | `discovery/gainers`+`losers` sector clustering + `fundamental/ratios` PE expansion                |
+| Real-time quotes  | `fin_data_ohlcv` (~15min delay); caveat to user for time-sensitive analysis                       |
+| Intraday OHLCV    | Daily only; gap analysis (open vs prior close) as partial substitute                              |
+
+## Data Boundaries
+
+| Data               | Frequency    | Notes                                                              |
+| ------------------ | ------------ | ------------------------------------------------------------------ |
+| US quotes          | ~15min delay | yfinance                                                           |
+| US GAAP financials | quarterly    | 10-Q (45d), 10-K (60d)                                             |
+| Earnings forecast  | consensus    | small-cap may lack coverage; mega-cap (20+ analysts) most reliable |
+| Options chains     | ~15min delay | full Greeks (Delta/Gamma/Vega/Theta/IV)                            |
+| Dividends          | historical   | ex-date + amount                                                   |
+| Company news       | event-driven | `news/company`; may lag real-time by minutes-hours                 |
+| US 复权因子        | Daily        | tushare `us/adj_factor` (11397 records)                            |
+| US 交易日历        | —            | tushare `us/trade_cal` (预生成至 2026-12-31)                       |
+| 拆股历史           | event-driven | `fundamental/historical_splits` (e.g. AAPL 3 records)              |

package/skills/us-etf/skill.md

@@ -0,0 +1,261 @@
+---
+name: fin-us-etf
+description: "US ETF analysis — SPY/QQQ/VOO/VTI/SCHD comparison, expense ratio + AUM + tracking error framework, core-satellite portfolio construction, sector ETF rotation (XLK/XLF/XLE), DCA simulation. Use when: user asks about US ETF selection, passive investing, ETF comparison, sector ETFs, or ETF portfolio allocation. NOT for: A-share ETFs/funds (use fin-etf-fund), individual US stocks (use fin-us-equity), crypto (use fin-crypto), macro rates (use fin-macro)."
+metadata: { "openclaw": { "emoji": "🏦", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# US ETF Analysis
+
+US ETFs = the safest entry point for retail investors into US equities. Compare, construct portfolios, and simulate DCA returns.
+
+> **Scope boundary:** This skill covers US-listed ETFs (SPY, QQQ, VOO, etc.). For A-share ETFs (510300.SH) and mainland funds, use `/fin-etf-fund`. For individual US stocks, use `/fin-us-equity`.
+
+## When to Use
+
+- "SPY 和 VOO 哪个好" / "SPY vs VOO comparison"
+- "科技 ETF 有哪些" / "What tech ETFs are available"
+- "怎么配置 ETF 组合" / "How to build an ETF portfolio"
+- "QQQ 今年表现怎么样" / "QQQ performance this year"
+- "定投 VOO 30 年能赚多少" / "DCA into VOO for 30 years"
+- "SCHD 和 VYM 哪个分红更好" / "SCHD vs VYM dividend comparison"
+- "行业 ETF 现在买什么" / "Which sector ETF to buy now"
+
+## When NOT to Use
+
+- A 股 ETF / 场内基金 (510300.SH, 159919.SZ) -> use `/fin-etf-fund`
+- 场外基金 / 基金经理分析 -> use `/fin-etf-fund`
+- US 个股深度分析 (AAPL, NVDA) -> use `/fin-us-equity`
+- 加密货币 / DeFi -> use `/fin-crypto`
+- 宏观利率 / 国债收益率 -> use `/fin-macro`
+- US options/derivatives -> use `/fin-us-equity` (options section)
+
+## Tools & Parameters
+
+### fin_stock (ETF price + fundamentals)
+
+| Parameter | Type   | Required | Format    | Default | Example          |
+| --------- | ------ | -------- | --------- | ------- | ---------------- |
+| symbol    | string | Yes      | US ticker | —       | SPY              |
+| endpoint  | string | Yes      | see below | —       | price/historical |
+| provider  | string | No       | yfinance  | auto    | yfinance         |
+| limit     | number | No       | 1-5000    | 200     | 250              |
+
+> **Important:** For US ETFs, always use `provider="yfinance"` with `price/historical`. Default tushare provider returns 500 for US symbols.
+
+#### Endpoints for ETFs
+
+| endpoint                | Description              | Example                                                                     |
+| ----------------------- | ------------------------ | --------------------------------------------------------------------------- |
+| `price/historical`      | ETF OHLCV price history  | `fin_stock(symbol="SPY", endpoint="price/historical", provider="yfinance")` |
+| `fundamental/dividends` | ETF dividend history     | `fin_stock(symbol="SPY", endpoint="fundamental/dividends")`                 |
+| `fundamental/ratios`    | Basic ratios (yield)     | `fin_stock(symbol="SPY", endpoint="fundamental/ratios")`                    |
+| `fundamental/metrics`   | Key metrics (market cap) | `fin_stock(symbol="SPY", endpoint="fundamental/metrics")`                   |
+| `profile`               | ETF description + sector | `fin_stock(symbol="SPY", endpoint="profile")`                               |
+
+### fin_index (for benchmark comparison)
+
+| endpoint       | Description               | Example                                                  |
+| -------------- | ------------------------- | -------------------------------------------------------- |
+| `constituents` | Index constituents        | `fin_index(endpoint="constituents", symbol="000300.SH")` |
+| `daily_basic`  | Index valuation (A-share) | N/A for US — use `price/historical` on index ETF instead |
+
+### fin_data_ohlcv (K-line data)
+
+| Parameter | Type   | Required | Default | Example |
+| --------- | ------ | -------- | ------- | ------- |
+| symbol    | string | Yes      | —       | SPY     |
+| market    | string | No       | equity  | equity  |
+| timeframe | string | No       | 1d      | 1w      |
+| limit     | number | No       | 200     | 250     |
+
+### Auxiliary Tools
+
+| tool              | use case                            |
+| ----------------- | ----------------------------------- |
+| `fin_macro`       | `treasury_us` for risk-free rate    |
+| `fin_ta`          | RSI/SMA/MACD for timing             |
+| `fin_data_regime` | Market regime for allocation adjust |
+
+## US ETF Knowledge Base
+
+> DataHub cannot directly query expense ratio, AUM, or tracking error. The following reference data enables analysis.
+
+### Core Broad Market ETFs
+
+| Ticker | Index           | Expense Ratio | AUM ($B) | Style        |
+| ------ | --------------- | ------------- | -------- | ------------ |
+| SPY    | S&P 500         | 0.09%         | ~550     | Large Cap    |
+| VOO    | S&P 500         | 0.03%         | ~450     | Large Cap    |
+| IVV    | S&P 500         | 0.03%         | ~500     | Large Cap    |
+| VTI    | Total US Market | 0.03%         | ~400     | Total Market |
+| QQQ    | Nasdaq 100      | 0.20%         | ~280     | Large Growth |
+| QQQM   | Nasdaq 100      | 0.15%         | ~30      | Large Growth |
+| IWM    | Russell 2000    | 0.19%         | ~70      | Small Cap    |
+| DIA    | Dow Jones 30    | 0.16%         | ~35      | Large Value  |
+| RSP    | S&P 500 EW      | 0.20%         | ~50      | Equal Weight |
+
+### Dividend/Income ETFs
+
+| Ticker | Focus               | Expense Ratio | Yield | Style       |
+| ------ | ------------------- | ------------- | ----- | ----------- |
+| SCHD   | Dividend Growth     | 0.06%         | ~3.5% | Quality Div |
+| VYM    | High Dividend Yield | 0.06%         | ~3.0% | High Yield  |
+| DVY    | Select Dividend     | 0.38%         | ~3.8% | High Yield  |
+| DGRO   | Dividend Growth     | 0.08%         | ~2.3% | Growth Div  |
+| HDV    | High Dividend       | 0.08%         | ~3.5% | Defensive   |
+
+### Sector ETFs (SPDR Select Sector)
+
+| Ticker | Sector           | Expense Ratio | Economic Cycle Phase |
+| ------ | ---------------- | ------------- | -------------------- |
+| XLK    | Technology       | 0.09%         | Early/Late Expansion |
+| XLF    | Financials       | 0.09%         | Early Recovery       |
+| XLE    | Energy           | 0.09%         | Late Cycle/Inflation |
+| XLV    | Healthcare       | 0.09%         | Defensive/Late Cycle |
+| XLU    | Utilities        | 0.09%         | Recession/Defensive  |
+| XLI    | Industrials      | 0.09%         | Early Recovery       |
+| XLB    | Materials        | 0.09%         | Mid Cycle/Inflation  |
+| XLP    | Consumer Staples | 0.09%         | Recession/Defensive  |
+| XLY    | Consumer Disc    | 0.09%         | Early Recovery       |
+| XLRE   | Real Estate      | 0.09%         | Rate Sensitive       |
+| XLC    | Communication    | 0.09%         | Growth-oriented      |
+
+### Factor ETFs
+
+| Ticker | Factor    | Expense Ratio | Use Case                    |
+| ------ | --------- | ------------- | --------------------------- |
+| MTUM   | Momentum  | 0.15%         | Trend following             |
+| QUAL   | Quality   | 0.15%         | Defensive growth            |
+| VLUE   | Value     | 0.15%         | Mean reversion / contrarian |
+| SIZE   | Small Cap | 0.15%         | Small cap premium           |
+| USMV   | Min Vol   | 0.15%         | Low volatility              |
+
+### Bond ETFs (for portfolio construction)
+
+| Ticker | Focus             | Expense Ratio | Duration | Use Case          |
+| ------ | ----------------- | ------------- | -------- | ----------------- |
+| AGG    | US Aggregate Bond | 0.03%         | ~6yr     | Core bond holding |
+| BND    | Total Bond Market | 0.03%         | ~6yr     | Core bond holding |
+| TLT    | 20+ Year Treasury | 0.15%         | ~17yr    | Rate bet / hedge  |
+| SHV    | Short Treasury    | 0.15%         | <1yr     | Cash equivalent   |
+| TIP    | TIPS              | 0.19%         | ~7yr     | Inflation hedge   |
+
+## ETF Comparison Analysis Pattern
+
+1. **Price Performance** `fin_stock(endpoint="price/historical", symbol="SPY", provider="yfinance", limit=250)` — YTD + 1Y price comparison
+   - Pull historical prices for each ETF being compared
+   - Calculate: YTD return, 1Y return, 3Y annualized, max drawdown
+   - ⚠️ If comparing SPY vs VOO, note they track the same index — difference is mainly expense ratio and liquidity
+   - 💡 For fair comparison, use total return (price + dividends reinvested) — approximate by adding annual dividend yield
+
+2. **Dividend Analysis** `fin_stock(endpoint="fundamental/dividends", symbol="SCHD")` — Yield + growth
+   - Compare: current yield, 5-year dividend CAGR, payout consistency
+   - ⚠️ High yield (>5%) in equity ETFs may indicate value trap constituents
+   - 💡 Dividend growth rate matters more than current yield for long-term compounding
+
+3. **Risk Metrics** — Calculate from price history
+   - Annualized volatility = stdev(daily returns) \* sqrt(252)
+   - Sharpe ratio = (annualized return - risk-free rate) / annualized volatility
+   - Max drawdown = largest peak-to-trough decline
+   - Use `fin_macro(endpoint="treasury_us")` for risk-free rate
+   - ⚠️ Sharpe < 0.5 = poor risk-adjusted return; > 1.0 = excellent
+   - 💡 Compare Sharpe across ETFs rather than raw returns for quality assessment
+
+4. **Cost Analysis** — Reference knowledge base above
+   - Expense ratio difference impact: $100K invested, 0.06% difference = $60/year, ~$3,000 over 30 years (compounded)
+   - ⚠️ For identical-index ETFs (SPY/VOO/IVV), always recommend lowest expense ratio unless liquidity requirements differ
+
+## Portfolio Construction Patterns
+
+### Core-Satellite Strategy
+
+| Component | Weight | ETF Selection        | Criteria                          |
+| --------- | ------ | -------------------- | --------------------------------- |
+| Core      | 60-70% | VOO or VTI           | Lowest cost broad market exposure |
+| Satellite | 20-30% | Sector/thematic ETFs | Momentum + conviction-based       |
+| Income    | 0-15%  | SCHD or AGG          | Dividend income or bond ballast   |
+
+### Classic Portfolio Templates
+
+| Portfolio       | Allocation                            | Risk Level | Best For          |
+| --------------- | ------------------------------------- | ---------- | ----------------- |
+| US 60/40        | 60% VOO + 40% AGG                     | Moderate   | Conservative      |
+| All-Weather     | 30% VTI + 40% TLT + 15% TIP + 15% GLD | Low-Med    | All conditions    |
+| Growth          | 50% QQQ + 30% VOO + 20% IWM           | High       | Long-term growth  |
+| Dividend Income | 40% SCHD + 30% VYM + 30% AGG          | Low-Med    | Income generation |
+| Lazy 3-Fund     | 60% VTI + 30% VXUS + 10% BND          | Moderate   | Set-and-forget    |
+
+### DCA Simulation Pattern
+
+```
+Input: monthly_amount, etf_symbol, years
+Step 1: fin_stock(price/historical, limit=years*250) -> daily prices
+Step 2: For each month, calculate shares_bought = monthly_amount / price_on_date
+Step 3: Total shares * current price = current value
+Step 4: Total invested = monthly_amount * months
+Step 5: Return = (current_value - total_invested) / total_invested
+```
+
+Historical DCA benchmarks (for context, not prediction):
+
+- SPY 10-year DCA: ~10-12% annualized (2015-2025)
+- QQQ 10-year DCA: ~15-18% annualized (2015-2025)
+- SCHD 10-year DCA: ~9-11% annualized (2015-2025)
+
+### Sector ETF Rotation Pattern
+
+1. **Sector Scoreboard** — Pull price/historical for all 11 sector ETFs (XLK through XLC)
+   - Calculate: 1W, 1M, 3M relative returns vs SPY
+   - Rank by momentum (3M relative return)
+   - ⚠️ Sector leading for > 6 months with decelerating momentum = potential mean reversion
+   - 💡 Cross-validate with `fin_data_regime` — defensive sectors (XLU/XLP/XLV) outperform in bear/volatile regimes
+
+2. **Economic Cycle Mapping** — Use `fin_macro(endpoint="treasury_us")` for yield curve context
+   - Early recovery: XLF, XLY, XLI (rate-sensitive, cyclical)
+   - Mid cycle: XLK, XLC (growth acceleration)
+   - Late cycle: XLE, XLB (commodity/inflation beneficiaries)
+   - Recession: XLU, XLP, XLV (defensive, low beta)
+   - ⚠️ If 2Y-10Y spread inverted (< 0) -> late cycle/recession signal, rotate to defensives
+
+3. **Rebalancing Signal** — Monthly check
+   - If top sector 3M return > SPY +10% AND RSI > 70 -> overbought, consider trimming
+   - If bottom sector 3M return < SPY -10% AND RSI < 30 -> oversold, consider adding
+   - 💡 Sector rotation is not about catching tops/bottoms — it's about gradual tilt adjustments
+
+## Data Notes
+
+- **yfinance ETF data**: ~15min delay, covers price/dividends/basic fundamentals. Always specify `provider="yfinance"` for US ETFs
+- **Missing from DataHub**: ETF holdings (constituent weights), AUM (assets under management), expense ratio (use knowledge base above), tracking error, fund flows, net asset value (use closing price as proxy)
+- **Expense ratio / AUM**: Hardcoded in knowledge base above. Values are approximate and updated periodically. For exact current figures, advise user to check fund provider website
+- **Dividend data**: `fundamental/dividends` returns historical ex-date + amount. Calculate trailing 12M yield = sum of last 4 quarterly dividends / current price
+- **Total return approximation**: Daily price return + (annual dividend yield / 252) for rough total return. Not perfectly accurate but sufficient for comparison
+- **Bond ETFs**: Price history available but duration/credit quality metrics are from knowledge base, not live data
+
+## Response Guidelines
+
+### Number Formats
+
+- ETF price: $452.30 (2 decimal places)
+- Returns: +12.5% / -3.2% (always with +/- sign, 1 decimal)
+- Expense ratio: 0.03% (2 decimal places)
+- AUM: $450B / $35B (use $B)
+- Dividend yield: 3.5% (1 decimal)
+- Sharpe ratio: 1.05 (2 decimal)
+- Dollar amounts in DCA: $10,000 -> $285,000 (round to nearest thousand for large projections)
+
+### Must Include
+
+- Data timestamp ("Data as of YYYY-MM-DD")
+- Expense ratio for every ETF mentioned (from knowledge base)
+- Performance comparison must include at least 1Y timeframe
+- Risk disclaimer for any forward-looking projection ("Past performance does not guarantee future results")
+- Note when data comes from embedded knowledge base vs live DataHub query
+
+### Display Format
+
+- ETF comparison -> side-by-side table (ticker, expense ratio, 1Y return, yield, Sharpe)
+- Portfolio construction -> allocation table with weights + rationale
+- DCA simulation -> input assumptions + result table + compound growth note
+- Sector rotation -> ranked table with momentum scores + economic cycle annotation
+- Single ETF analysis -> structured sections: Overview, Performance, Risk, Dividend, Verdict
+- Always include actionable takeaway: "For most investors, [recommendation] because [reason]"