1---
2name: stock-analysis
3description: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management (create, add, remove assets), crypto analysis (Top 20 by market cap), and periodic performance reports (daily/weekly/monthly/quarterly/yearly). 8 analysis dimensions for stocks, 3 for crypto. Use for stock analysis, portfolio tracking, earnings reactions, or crypto monitoring.
4homepage: https://finance.yahoo.com
5metadata: {"clawdbot":{"emoji":"📈","requires":{"bins":["uv"],"env":[]},"install":[{"id":"uv-brew","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]}}
6---
7 
8# Stock Analysis (v5.0)
9 
10Analyze US stocks and cryptocurrencies using Yahoo Finance data. Includes portfolio management, crypto support, and periodic analysis.
11 
12## Quick Start
13 
14**IMPORTANT:** Pass ONLY the stock ticker symbol(s) as arguments. Do NOT add extra text, headers, or formatting in the command.
15 
16Analyze a single ticker:
17 
18```bash
19uv run {baseDir}/scripts/analyze_stock.py AAPL
20uv run {baseDir}/scripts/analyze_stock.py MSFT --output json
21```
22 
23Compare multiple tickers:
24 
25```bash
26uv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL
27```
28 
29## Cryptocurrency Analysis (v5.0)
30 
31Analyze top 20 cryptocurrencies by market cap:
32 
33```bash
34uv run {baseDir}/scripts/analyze_stock.py BTC-USD
35uv run {baseDir}/scripts/analyze_stock.py ETH-USD SOL-USD
36```
37 
38**Supported Cryptos:**
39BTC-USD, ETH-USD, BNB-USD, SOL-USD, XRP-USD, ADA-USD, DOGE-USD, AVAX-USD, DOT-USD, MATIC-USD, LINK-USD, ATOM-USD, UNI-USD, LTC-USD, BCH-USD, XLM-USD, ALGO-USD, VET-USD, FIL-USD, NEAR-USD
40 
41**Crypto Analysis Dimensions:**
42- Market cap (large/mid/small classification)
43- Category (Smart Contract L1, DeFi, Payment, etc.)
44- BTC correlation (30-day)
45- Momentum (RSI, price range)
46- Market context (VIX, general market regime)
47 
48## Portfolio Management (v5.0)
49 
50Create and manage portfolios with mixed assets (stocks + crypto):
51 
52```bash
53# Create portfolio
54uv run {baseDir}/scripts/portfolio.py create "My Portfolio"
55 
56# Add assets
57uv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150.00
58uv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000 --portfolio "My Portfolio"
59 
60# View holdings with current P&L
61uv run {baseDir}/scripts/portfolio.py show
62 
63# Update/remove assets
64uv run {baseDir}/scripts/portfolio.py update AAPL --quantity 150
65uv run {baseDir}/scripts/portfolio.py remove BTC-USD
66 
67# List/delete portfolios
68uv run {baseDir}/scripts/portfolio.py list
69uv run {baseDir}/scripts/portfolio.py delete "My Portfolio"
70```
71 
72**Portfolio Storage:** `~/.clawdbot/skills/stock-analysis/portfolios.json`
73 
74## Portfolio Analysis (v5.0)
75 
76Analyze all assets in a portfolio with optional period returns:
77 
78```bash
79# Analyze portfolio
80uv run {baseDir}/scripts/analyze_stock.py --portfolio "My Portfolio"
81 
82# With period returns (daily/weekly/monthly/quarterly/yearly)
83uv run {baseDir}/scripts/analyze_stock.py --portfolio "My Portfolio" --period weekly
84uv run {baseDir}/scripts/analyze_stock.py -p "My Portfolio" --period monthly
85```
86 
87**Portfolio Summary includes:**
88- Total cost, current value, P&L
89- Period return (if specified)
90- Concentration warnings (>30% in single asset)
91- Recommendation summary (BUY/HOLD/SELL counts)
92 
93**Examples:**
94- ✅ CORRECT: `uv run {baseDir}/scripts/analyze_stock.py BAC`
95- ✅ CORRECT: `uv run {baseDir}/scripts/analyze_stock.py BTC-USD`
96- ❌ WRONG: `uv run {baseDir}/scripts/analyze_stock.py === BANK OF AMERICA (BAC) - Q4 2025 EARNINGS ===`
97- ❌ WRONG: `uv run {baseDir}/scripts/analyze_stock.py "Bank of America"`
98 
99Use the ticker symbol only (e.g., BAC, not "Bank of America"). For crypto, use the -USD suffix (e.g., BTC-USD).
100 
101## Analysis Components
102 
103The script evaluates eight key dimensions:
104 
1051. **Earnings Surprise (30% weight)**: Actual vs expected EPS, revenue beats/misses
1062. **Fundamentals (20% weight)**: P/E ratio, profit margins, revenue growth, debt levels
1073. **Analyst Sentiment (20% weight)**: Consensus ratings, price target vs current price
1084. **Historical Patterns (10% weight)**: Past earnings reactions, volatility
1095. **Market Context (10% weight)**: VIX, SPY/QQQ trends, market regime
1106. **Sector Performance (15% weight)**: Stock vs sector comparison, sector trends
1117. **Momentum (15% weight)**: RSI, 52-week range, volume, relative strength
1128. **Sentiment Analysis (10% weight)**: Fear/Greed Index, short interest, VIX term structure, insider trading, put/call ratio
113 
114**Sentiment Sub-Indicators:**
115- **Fear & Greed Index (CNN)**: Contrarian signal (extreme fear = buy opportunity, extreme greed = caution)
116- **Short Interest**: High shorts + squeeze potential = bullish; justified shorts = bearish
117- **VIX Term Structure**: Contango = complacency/bullish; backwardation = stress/bearish
118- **Insider Activity**: Net buying/selling from SEC Form 4 filings (90-day window)
119- **Put/Call Ratio**: High ratio = excessive fear/bullish; low ratio = complacency/bearish
120 
121Weights auto-normalize if some components unavailable.
122 
123**Special Timing Checks:**
124- Pre-earnings warning (< 14 days): Recommends HOLD instead of BUY
125- Post-earnings spike detection (> 15% in 5 days): Flags "gains priced in"
126- Overbought conditions (RSI > 70 + near 52w high): Reduces confidence
127 
128## Timing Warnings & Risk Flags
129 
130The script detects high-risk scenarios:
131 
132### Earnings Timing
133- **Pre-Earnings Period**: If earnings < 14 days away, BUY signals become HOLD
134- **Post-Earnings Spike**: If stock up > 15% in 5 days after earnings, warns "gains may be priced in"
135 
136### Technical Risk
137- **Overbought Conditions**: RSI > 70 + near 52-week high = high-risk entry
138 
139### Market Risk
140- **High VIX**: Market fear (VIX > 30) reduces confidence in BUY signals
141- **Risk-Off Mode (v4.0.0)**: When safe-havens (GLD, TLT, UUP) rise together, reduces BUY confidence by 30%
142  - Detects flight to safety across gold, treasuries, and USD
143  - Triggers when GLD ≥ +2%, TLT ≥ +1%, UUP ≥ +1% (5-day change)
144 
145### Sector Risk
146- **Sector Weakness**: Stock may look good but sector is rotating out
147 
148### Geopolitical Risk (v4.0.0)
149The script now scans breaking news (last 24h) for crisis keywords and automatically flags affected stocks:
150 
151- **Taiwan Conflict**: Semiconductors (NVDA, AMD, TSM, INTC, etc.) → 30% confidence penalty
152- **China Tensions**: Tech/Consumer (AAPL, QCOM, NKE, SBUX, etc.) → 30% confidence penalty
153- **Russia-Ukraine**: Energy/Materials (XOM, CVX, MOS, CF, etc.) → 30% confidence penalty
154- **Middle East**: Oil/Defense (XOM, LMT, RTX, etc.) → 30% confidence penalty
155- **Banking Crisis**: Financials (JPM, BAC, WFC, C, etc.) → 30% confidence penalty
156 
157If a ticker is not in the affected list but its sector is exposed, applies a 15% confidence penalty.
158 
159**Example Alert:**
160```
161⚠️ SECTOR RISK: Tech supply chain and consumer market exposure (detected: china, tariff)
162```
163 
164### Breaking News Alerts (v4.0.0)
165- Scans Google News RSS for crisis keywords (war, recession, sanctions, disasters, etc.)
166- Displays up to 2 breaking news alerts in caveats (last 24 hours)
167- Uses 1-hour cache to avoid excessive API calls
168 
169## Output Format
170 
171**Default (text)**: Concise buy/hold/sell signal with 3-5 bullet points and caveats
172 
173**JSON**: Structured data with scores, metrics, and raw data for further analysis
174 
175## Limitations
176 
177- **Data freshness**: Yahoo Finance may lag 15-20 minutes
178- **Sentiment data staleness**:
179  - Short interest data lags ~2 weeks (FINRA reporting schedule)
180  - Insider trades may lag filing by 2-3 days
181  - VIX term structure only updates during futures trading hours
182- **Breaking news limitations (v4.0.0)**:
183  - Google News RSS may lag by 15-60 minutes
184  - Keyword matching may have false positives/negatives
185  - Does not analyze sentiment, only detects keywords
186  - 1-hour cache means alerts may be slightly stale
187- **Missing data**: Not all stocks have analyst coverage, options chains, or complete fundamentals
188- **Execution time**: 3-5s per stock with async parallel fetching and caching (shared indicators cached for 1h)
189- **Disclaimer**: All outputs include prominent "not financial advice" warning
190- **US markets only**: Non-US tickers may have incomplete data
191 
192## Error Handling
193 
194The script gracefully handles:
195- Invalid tickers → Clear error message
196- Missing analyst data → Signal based on available metrics only
197- API failures → Retry with exponential backoff, fail after 3 attempts
198