Claude Investment Skills

13 investment analysis skills + 5 real-time firehoses for [Claude Code](https://docs.claude.com/claude-code). Ask in plain English or Chinese. Get structured stock analysis, macro regime reads, options setups, and earnings prep — or let the free firehoses monitor SEC filings 24/7 and push Telegram alerts before Twitter picks them up.

中文版本 · 5-min Introduction · 中文介绍

🚀 A friend sent you this repo? Let your agent install it for you.

You don't have to read 1200 lines of README. The repo ships with AGENTS.md — a complete setup playbook your AI coding agent reads and executes. Open Claude Code (or any agent that respects AGENTS.md / CLAUDE.md — Codex, Cursor, custom CLI agents) and paste:

Read https://github.com/ssurmic/claude-investment-skills/blob/main/AGENTS.md
and walk me through setting up this repo end-to-end. Ask me anything you
need (which OS, do I want price alerts / firehoses / just the analysis
skills, do I have a Telegram bot yet, etc.) and install the pieces I want.

The agent will:

1. Ask the PREP questionnaire (OS, what you want — analysis only? alerts? firehoses? webhook for instant chat?)
2. Pick a flow (A: core skills · B: GH-cron alerts · C: chat via polling · D: webhook for 1-3 sec replies)
3. Walk you through forking the repo, creating a Telegram bot via @BotFather, setting GitHub Secrets, and enabling workflows — step by step, button by button
4. Verify each step before moving on, and warn you about the 6 known gotchas (PAT scope, webhook SSL, btoa Latin-1, etc.)

No prior Claude Code / Python / GitHub Actions experience required — the agent handles it. Estimated time: 5 min (analysis only) → 30 min (full firehose + webhook stack).

Prefer to do it yourself? Skip to Install below for the manual path.

What's included

Analysis skills — powered by Claude

These run locally in Claude Code and require an Anthropic API key (which Claude Code already uses — no extra setup).

Trigger any skill in plain language — no slash commands required:

analyze NVDA
macro risk check
what's the gamma wall on NOK this week?
find me an AI power play no one's talking about

Discovery firehoses — free, no API key needed

These run as GitHub Actions cron jobs and push Telegram alerts. The only cost is your time to set them up.

Optional: Add a Cloudflare Worker (~15 min setup) to get 1–3 second Telegram bot responses instead of 2–15 minutes. See ARCHITECTURE.md.

What you need

Install

Option 1 — Git clone (3 min, recommended — gives you a fork to customize):

# 1. Clone the repo into Claude Code's skills dir. This brings down everything
#    in the repo — all 13 skills, all Python scripts, AND setup.sh.
git clone https://github.com/ssurmic/claude-investment-skills.git ~/.claude/skills

# 2. Run the bundled setup.sh (it lives at the repo root, so step 1 put it
#    here). It creates a Python venv at /tmp/.insider_venv and installs
#    yfinance + pandas + requests.
bash ~/.claude/skills/setup.sh

Option 2 — Plugin marketplace (30 sec, easiest way to get started):

# 1. /plugin install copies the same repo contents (including setup.sh) into
#    Claude Code's plugin dir.
/plugin install claude-investment-skills@claude-investment-skills-marketplace

# 2. Same setup.sh, different path — it lives wherever the plugin landed.
bash ~/.claude/plugins/claude-investment-skills/setup.sh

setup.sh is committed to the repo root — you don't download it separately. Step 1 of either option pulls it down along with everything else, then step 2 just executes the file that's now on your disk. setup.sh itself auto-detects which of the two install modes you're in.

Both methods install the same 13 skills, same Python scripts, and the same alert pipeline. You can switch between them at any time — your alerts.json lives in your GitHub fork either way.

After setup, open Claude Code and start talking:

analyze NVDA
macro risk check

Slash commands also work if you prefer: /analyze-stock NVDA, /macro-risk-check.

🤖 For AI agents / CLI users

Two entry points, depending on what phase the agent is in:

• Setup phase (user just pasted this URL and wants you to install/configure things) → read AGENTS.md. It contains PREP questionnaire, flow detection, step-by-step install, gotchas (PAT scope, webhook SSL, etc.), and handoff rules. Works for Claude Code, Codex, Cursor, custom agents — CLAUDE.md is a thin alias.
• Runtime phase (skills are installed, user is asking investment questions) → read AGENT-TOOL-REFERENCE.md. It contains NL triggers in EN + CN, exact CLI templates, parameter specs, and multi-tool composite patterns.

Also useful: INVESTMENT-WORKFLOW.md (which skill to pick for an investment question) and ARCHITECTURE.md (why the data plumbing looks the way it does — yfinance MCP + direct HTTP APIs + openinsider, not a 3-MCP stack).

⚡ Quick Start — pick ONE install method

Prerequisites: macOS or Linux, Python 3.9+, Claude Code installed.

Option 1 — Plugin marketplace (recommended for new users, 30 seconds)

# 1. Add the marketplace to Claude Code
/plugin marketplace add ssurmic/claude-investment-skills

# 2. Install the plugin
/plugin install claude-investment-skills@claude-investment-skills-marketplace

# 3. Run setup (creates Python venv, installs yfinance)
bash ~/.claude/plugins/claude-investment-skills/setup.sh

# 4. Talk to Claude in plain English (or Chinese)
analyze NVDA          # natural language works

Option 2 — Git clone (recommended if you want to fork + customize, 3 minutes)

# 1. Clone to where Claude Code looks for skills
git clone https://github.com/ssurmic/claude-investment-skills.git ~/.claude/skills

# 2. Run setup (creates Python venv, installs yfinance, verifies all 14 skills)
bash ~/.claude/skills/setup.sh

# 3. Talk to Claude in plain English (or Chinese)
analyze NVDA

Two-way door. Both methods install the exact same 14 skills, the same Python scripts, the same Telegram alert pipeline. Pick based on whether you want to fork the repo (Option 2) or just use the tool (Option 1). You can switch later — uninstall one, install the other; alerts.json lives in your GitHub fork either way.

No slash commands needed for analysis skills. They trigger from natural language regardless of install method. (Slash commands are still available if you prefer — /analyze-stock NVDA works too.)

📦 Component map — what runs where (read this first)

Component map architecture

Where does each kind of "moving average" come from?

This trips people up because the SAME data is computed in TWO different places depending on what you're asking for:

Where does each kind of intelligence live?

The pattern: all real investment thinking happens locally in Claude Code. GitHub / Cloudflare only handle the boring stuff (scheduling, NL parsing for short bot replies, JSON edits). You never have to trust a remote AI with your decisions — the decision-grade analysis only runs when YOU are sitting in front of Claude Code.

🔥 Four discovery channels — catch the next ticker before Twitter does

The problem this solves

Every time a stock 10x's, the same pattern repeats:

❌ Day 0: SEC filing makes the news public. Nobody on Twitter sees it. ❌ Day 30: Bloomberg covers it briefly. ❌ Day 60: First Substack writer publishes a paid "deep dive." ❌ Day 120: Reddit catches wind. ❌ Day 180-540: A KOL on Twitter pumps it. The chart is parabolic. You buy the top.

The information was free and public the whole time. The bottleneck wasn't access — it was speed.

What this skill does

Three SEC EDGAR firehoses run as GitHub Actions cron jobs every 30 minutes weekdays 9 AM - 7:30 PM ET. They scan every filing the SEC publishes, extract the alpha-rich ones, enrich with valuation + price action, score 0-10, and push to Telegram.

You don't tell them what to watch. They tell you what to watch.

Firehose architecture

Three case studies — the actual alpha-leak timelines

These are not hypothetical. These are real filings with real prices.

#### Case 1: CoreWeave (CRWV) — $40 to $187 in 3 months

The single most dramatic AI-era IPO story. The 8-K naming OpenAI as a strategic equity investor was on EDGAR 2 days after IPO. The first Substack writeup came 5 weeks later. By the time the chart went parabolic on Twitter, the stock was already +367%.

CRWV alpha leak

#### Case 2: Powell Industries (POWL) — anonymous customer, +73% in 7 days

A 50-year-old industrial company. Boring. Then a single 8-K announced "the largest order in company history, $400M+ for a major U.S. technology company." The customer was redacted — typical for hyperscaler deals.

A naive scanner would miss this because "NVIDIA" / "Microsoft" / "Amazon" aren't in the text. v2.4 Path B (Theme Classifier) catches it via keyword density: "behind-the-meter" + "multi-gigawatt" + "data center" + "largest order in company history" scores 10/10.

POWL alpha leak

#### Case 3: Penguin Solutions (PENG, formerly SGH) — 22 months of dormant alpha

The longest fuse. SK Telecom's $200M PIPE Preferred filing on 8-K Item 3.02 sat in EDGAR for 22 months before Twitter discovered it. Patient capital ran +150%.

PENG alpha leak

#### Case 4: Political official trade monitor — White House + Congress, mandatory disclosure windows

Federal law requires all government officials to disclose trades within 30-45 days. That window sits days to weeks ahead of Twitter/CNBC coverage.

Trump Q1 2026: 3,642 trades in a single quarter (MSFT $5M–$25M buy · VANGUARD $5M–$25M sell · NVDA/ORCL/META buys). The 278-T was filed with OGE on 5/8/2026 — our script caught it same day. CNBC analysis came 2 days later.

Rep. John McGuire (R-VA): Bought AAPL + MSFT + NVDA on 5/13/2026. House PTR filed same day — Telegram alert by 9 AM.

Political official trade monitor

Telegram alert format (OGE 278-T — objective mandatory disclosure data, not investment advice):

🏛 OGE 278-T  ⚡ NEW FILING

👤 Donald J. Trump  🔴 R
🎯 President of the United States
🗓 Filed: 5/8/2026  |  2,707 transactions (2,415 buys / 292 sells)

🟢 TOP BUYS (2,415 total):
  🟢 MSFT  Microsoft Corp       $5M–$25M  3/17/2026
  🟢 NVDA  Nvidia Corp          $1M–$5M   2/10/2026
  🟢 ORCL  Oracle Corp          $1M–$5M   3/17/2026
  🟢 HOOD  Robinhood Markets    $1M–$5M   2/10/2026
  _...+2,411 more buys_

🔴 TOP SELLS (292 total):
  🔴 VIG   Vanguard Div ETF     $5M–$25M
  🔴 META  Meta Platforms       $5M–$25M
  _...+290 more sells_

📎 OGE 278-T PDF →  https://extapps2.oge.gov/...

Tracked officials (12): Trump · Bessent (Treasury) · Lutnick (Commerce) · Tuberville · Kelly · Sullivan · Whitehouse · Pelosi · Austin Scott · Crenshaw · McCaul · Gottheimer

The four alpha channels

How you use it

   1. Fork this repo (one click)
   2. Set TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID in GitHub Secrets
   3. Enable the GitHub Actions workflows
   4. ─── Now wait ───
   5. Telegram alerts arrive every time the SEC has news
   6. (Optional) Talk to Claude Code about the tickers that show up

This is cron-driven, not chat-driven. The firehoses do not require natural-language commands — they run silently in the background. NL is only how you investigate and act on what they discover:

"analyze TICKR"                  → invokes analyze-stock
"is TICKR a buy at $X"           → invokes analyze-stock + macro-warning gate
"option walls for TICKR"         → invokes option-wall-analysis
"find next PENG"                 → invokes find-untapped-thesis
"set price alert TICKR below $X" → invokes price-alert

What this skill is NOT

• ❌ Not a trading bot — it doesn't place orders
• ❌ Not a backtest engine — historical replays are limited to fixture-based unit tests
• ❌ Not real-time tick streaming — SEC EDGAR doesn't offer WebSocket; we poll atom feeds every 30 minutes (already 6-540× faster than Twitter)
• ❌ Not a "secret edge" — Substack writers read the same EDGAR. We just automate the polling so you don't need a $20/mo subscription per writer

Costs

Your only cost is one fork on GitHub and the 5 minutes to set up Telegram.

🔍 State sources — where everything lives + how to inspect it

Every piece of state has one authoritative source. Knowing where to look turns "the bot isn't working" mysteries into 30-second diagnostics. Nothing is hidden — every state location is reachable with a single cat / curl / gh / wrangler command.

Your config state (lives in your GitHub fork)

Your secrets (three potential homes — each path needs its own copy)

Inspect what's set where:

# Local .env (values visible — that's the point of local)
cat ~/.claude/{skills,plugins/claude-investment-skills}/price-alert/.env 2>/dev/null

# GitHub Secrets (names only, values encrypted)
gh secret list --repo <you>/claude-investment-skills

# Cloudflare Worker Secrets (names only)
cd ~/.claude/{skills,plugins/claude-investment-skills}/price-alert/webhook 2>/dev/null && wrangler secret list

Live operational state

Where market data comes from (external sources, fetched fresh each call)

Where your install code lives

What is NOT stored (ephemeral by design)

• Your portfolio positions — never persisted by this toolkit. If you paste a screenshot, it lives in that conversation only.
• Live price quotes — fetched fresh on every skill invocation; never cached.
• Analysis outputs — only as your conversation history (in Claude Code's own state, not by this repo).
• Insider raw HTML — fetched fresh from openinsider every insider_ratio.py call.

Key principle: every observable in this list is reachable from your terminal with one command. If you can't see it, something is broken (or not installed). When you ask "is my bot working?", run one of the commands above instead of guessing.

🏗️ Architecture at a glance

For the price-alert skill (optional Telegram + Anthropic API integration). The chat path has two interchangeable implementations — pick one based on the latency you want:

Architecture: price-alert skill with both polling and webhook chat paths

🔧 Source: diagrams/architecture-en.mmd — edit the .mmd file, push, and the .svg/.png regenerate automatically via render-diagrams.yml. See Diagrams pipeline below.

Two chat paths, same outcome — different latency:

Start with Option A. Upgrade to webhook only if you actively chat with the bot and the 2-15 min delay annoys you.

Monthly cost estimate: $0 if you skip the optional Telegram chat bot; ~$1-4/mo for moderate use of bidirectional NL chat via Anthropic API (same cost regardless of which chat path you pick — the API call is identical). Full breakdown in INTRODUCTION.md.

For a full deep-dive into how each piece works, see INTRODUCTION.md → How it all works.

🎨 Diagrams pipeline (Mermaid → SVG)

The architecture images in this README and in INTRODUCTION.md are not rendered client-side by GitHub. They live as checked-in .svg + .png files generated from Mermaid source so the README loads fast and looks identical across GitHub, mobile, and local viewers.

diagrams/
├── architecture-en.mmd       ← source of truth (edit this)
├── architecture-en.svg       ← committed artifact, used by README.md
├── architecture-en.png       ← committed artifact, fallback for non-SVG viewers
├── architecture-zh.mmd       ← Chinese source of truth
├── architecture-zh.svg       ← used by README-zh.md
└── architecture-zh.png

Local workflow

# 1. Install mermaid-cli (one-time)
npm install -g @mermaid-js/mermaid-cli

# 2. Edit a diagram source
$EDITOR diagrams/architecture-en.mmd

# 3. Regenerate the .svg + .png next to it
bash scripts/render-diagrams.sh                  # render all
bash scripts/render-diagrams.sh diagrams/architecture-en.mmd  # one file

# 4. Commit both the .mmd source and the regenerated artifacts
git add diagrams/architecture-en.{mmd,svg,png}
git commit -m "docs: tweak architecture diagram"

CI workflow (auto-render on push)

.github/workflows/render-diagrams.yml watches diagrams/**.mmd and regenerates the .svg/.png whenever you push a source change. The workflow installs mermaid-cli + fonts-noto-cjk (so Chinese diagrams render correctly), runs scripts/render-diagrams.sh, and commits any image deltas back to main.

This means you can edit just the `.mmd` file in the GitHub web editor and the workflow handles the render. No local mermaid-cli required if you don't want to install it.

Why pre-render instead of letting GitHub render Mermaid blocks?

🗣️ How natural language triggers skills (the magic)

You don't memorize commands. You just talk. Here's why that works:

The mechanism

1. Each skill has a `description:` field in its SKILL.md frontmatter listing trigger phrases (English + Chinese).
2. Claude Code matches your input against all skill descriptions and picks the best fit.
3. The matched skill loads its full instructions and runs (pulls live data, runs analysis, returns answer).

Example: how macro-warning gets triggered

The skill's description includes:

Triggers in English ("macro warning", "regime check", "is the market at peak",
"should I take profits", "is it time to buy") or Chinese ("宏观警报",
"市场是不是顶了", "该不该减仓", "regime 怎么样", "该入场吗")

So all of these phrasings invoke the same skill:

Composite triggers (multiple skills in one ask)

You can chain skills naturally:

You: "I want to buy AMD before earnings, is the macro safe?"
→ Claude triggers macro-risk-check first (regime read)
→ then earnings-prep (AMD-specific decision)
→ then maybe analyze-stock (full deep dive if regime is green)

Why this is robust

• Phrasing variations work — you don't need exact words
• Bilingual works mid-sentence — "analyze NVDA, 顺便看看 macro warning"
• Ambiguity gets clarified — Claude asks if your input could match multiple skills
• Slash commands still work — /analyze-stock NVDA is the explicit fallback

The full mapping (every trigger phrase → skill) is in AGENT-TOOL-REFERENCE.md.

💬 Real Conversation Examples

Five complete conversations showing how this works in practice. Every reply uses live data at the time of the conversation.

Example 1 — Stock deep dive (English)

You: analyze NVDA

Claude: [pulls live price, valuation, insider activity, options IV, and macro
        context, then returns]

NVDA — current $1,142, Forward P/E 38.2 (vs sector median 26)

Macro context: 🟠 ORANGE regime (NDX P/E 38, VIX 17 — see macro-warning)
Year theme: AI capex extends through 2026; power constraint risk
Sector tilt: SMH +138% YoY = mania territory
Insider activity (90d): 0 buys, 4 sells = $312M (10b5-1 plan-based, lighter)
Catalysts: 5/20 earnings (implied move ±8%), new GB300 ramp, China overhang

Recommendation: HOLD existing, no add at $1,142
3-tier entry plan if you want to start fresh:
  - Tier 1 (35%): $1,020-1,060 (50DMA + 20% drawdown)
  - Tier 2 (35%): $920-960 (200DMA, historical bounce zone)
  - Tier 3 (30%): $820 (38% drawdown — max-pain in cyclical correction)

LEAPS alternative: Jan 2027 $1100 call @ $215, breakeven $1315 (15% above
spot), gives 5x leverage at 50% IV. Stronger if you want defined risk.

Example 2 — Macro check before adding (Chinese)

你: 宏观警报，能不能加仓？

Claude: [跑 macro_pull.py 拉 8 层指标]

🟠 ORANGE regime — Composite 11/16

触发的硬规则:
  ✦ Shiller CAPE 42.05 > 38 (extreme)
  ✦ VIX 17.19 < 18 (exit-signal threshold)

8 层得分:
  🔴 估值 (2/2)  CAPE 42.05, SPX trailing PE 31.83
  🔴 波动 (2/2)  VIX 17.19, MOVE 67.25
  🟡 情绪 (1/2)  CNN F&G 66.9 (一周前 71.2，正在降温)
  🔴 信用 (2/2)  HY OAS 279 bps (complacency)
  🟡 货币 (1/2)  USD/JPY 156.62 (差 BOJ 干预区 3.4)
  🟡 宽度 (1/2)  SPX top 50 中只 44% 在 200DMA 上
  🟢 CTA  (0/2)  无公开 API
  🔴 板块 (2/2)  SMH 一年涨 +142% = mania

判断: 不建议加仓。现金 30-35%，trim AI/Semi 抛物 (-15-20%)，
买便宜 hedge (VIX 17 = put 极便宜)。

升级到 🔴 RED 触发器:
  - VIX < 14
  - F&G > 85
  - USD/JPY > 160
  - 30Y > 5.10%

Example 3 — Pre-earnings decision (mixed CN/EN)

You: AMD 财报后天，I'm holding 350 shares at $280 cost

Claude: [pulls AMD live data, options chain, 8-quarter history]

AMD Earnings Prep — reports 5/12 AMC

Implied move (ATM straddle): ±9.2% ($30 swing)
Last 8 quarters: 6 beat / 2 miss; avg reaction +4.1%, range -12% to +18%
What's priced in: 17% YoY revenue growth, MI400 ramp Q3/Q4 commentary
Your position: $98K @ $280 cost, currently +14% (+$13.7K unrealized)

4 scenarios (probability-weighted):
  📈 Beat + raise (40%): +12-18% → $314-$330
  📊 In-line (30%):     -2 to +5% → $275-$295
  📉 Light guide (20%): -8 to -12% → $247-$258
  💥 Miss + cut (10%):  -15 to -20% → $225-$238

Recommendation: TRIM 30% (105 shares) before earnings, hold 245
  Why: STCG bracket (held 7 months), implied move pricing rich vs. realized
       Lock in 14% on partial; remaining gives upside, downside cushion in
       case of miss.
  Tax note: 105 × ($295-$280) = $1,575 STCG → ~$580 federal + state

Example 4 — Portfolio audit from screenshot

You: [pastes screenshot of portfolio]
     review my portfolio

Claude: [parses screenshot, computes risk metrics]

Portfolio Audit — 12 positions, $487K total

Concentration risks:
  🔴 NVDA 28% (>10% cap) — single-name risk
  🟠 SMH+NVDA+TSM = 51% AI semi (sector concentration)

Factor exposure:
  - High beta names: 67% of book (>50% caution threshold)
  - LEAPS theta drag: $890/week (acceptable)
  - All long, no hedges (vulnerable to macro flip)

Trim list (in priority order):
  1. NVDA: trim 8% → 20% allocation. Sell 21 shares ≈ $24K.
     Why: concentration, parabolic +60% YoY, macro ORANGE
  2. SMH: trim 5% → 12%. Sell 6 shares ≈ $3.4K.
     Why: index proxy duplicates NVDA exposure
  3. PLTR: trim full position ($18K).
     Why: insider check shows 0 buys / 41 sells past 12 months

Cash target after trims: 28% (currently 8%)
Suggested hedge: 1% in QQQ Aug 680P @ $14 = $1,400 protection

Example 5 — Discovery / theme screening

You: 找未爆发的 AI 电力股

Claude: [screens utility + power-adjacent names with AI data center exposure]

Top 3 untapped AI Power candidates:

1. CEG (Constellation Energy) — $267
   Forward P/E: 24 (vs VST 31, NRG 28)
   1Y return: +18% (vs sector +35%)
   Catalyst: Microsoft 20-yr nuclear PPA (signed 9/2024); reactivation
            of Three Mile Island Unit 1 by 2028
   Insider: 2 buys, 0 sells past 90d = STRONG BUY signal
   Entry: 3-tier — $250 / $230 / $210

2. NRG (NRG Energy) — $94
   ...

3. PWR (Quanta Services) — $312
   Picks-and-shovels for grid build-out, not direct AI exposure but
   ...

Each candidate has: 3-tier entry, position size cap, catalyst date,
LEAPS alternative, downside scenario.

🎯 What This Does

10 specialized skills that work together to give you fund-manager-grade analysis:

Plus existing skills:

• review-investment-screenshot — Quick portfolio review from screenshot
• find-alpha — Time-horizon alpha screening
• schedule — Recurring agents

📦 Installation

Prerequisites

Required MCP Servers

#### 1. yfmcp (YFinance MCP) — REQUIRED Provides live stock data, options chains, news.

# Install via Claude Code
claude mcp add yfmcp -- npx -y @modelcontextprotocol/yfmcp

# Or check the latest install command at:
# https://github.com/...yfmcp

#### 2. WebSearch — Built-in Already available in Claude Code. Used for macro events, news, contracts.

Optional: full-MCP stack (NOT recommended for this repo)

Some teams pair Claude with a 3-MCP investment stack:

- Yahoo Finance MCP   → prices, options, VIX     ✅ we use this (yfmcp)
- FRED MCP            → macro indicators          ❌ we use direct CSV instead
- SEC EDGAR MCP       → filings + Form 4          ❌ we use openinsider scrape

We deliberately use only the first one. Full reasoning in ARCHITECTURE.md. TL;DR:

• FRED MCP: our use case is fixed (6 macro series). Direct fredgraph.csv is cron-friendlier and has no MCP startup overhead.
• EDGAR MCP: gives raw Form 4 XML; you'd have to re-implement code-aware filtering, recency bucketing, RSU exclusion, 10b5-1 awareness — all of which our insider_ratio.py already does on top of openinsider's pre-parsed data.

Add EDGAR MCP later only if you need 10-K / 8-K / S-1 / 13D parsing (none of our current skills need it).

Optional MCP Servers (claude.ai connectors)

Step-by-Step Install

# 1. Install Claude Code (if not already)
# Follow https://docs.claude.com/claude-code/install

# 2. Install yfmcp MCP server
claude mcp add yfmcp -- npx -y @modelcontextprotocol/yfmcp

# 3. Clone this repo
cd ~/.claude/skills
git clone https://github.com/YOUR_USERNAME/claude-investment-skills.git .

# 4. Run setup
bash setup.sh

# 5. Verify
ls ~/.claude/skills/
# Should see: analyze-stock, macro-risk-check, etc.

# 6. Test
# Open Claude Code, type:
/analyze-stock NVDA

🛠 What's Inside

~/.claude/skills/
├── setup.sh                            # One-click installer
├── INVESTMENT-WORKFLOW.md              # Master decision tree
├── README.md                           # This file (English)
├── README-zh.md                        # Chinese version
│
├── AGENT-TOOL-REFERENCE.md             # NEW v1.2: natural-language → CLI for agents/CLI
│
├── analyze-stock/SKILL.md              # 10-step master framework
├── macro-risk-check/SKILL.md           # Daily macro radar (news-driven)
├── macro-warning/SKILL.md              # NEW v1.3: daily 8-layer pullback radar (batch)
├── find-untapped-thesis/SKILL.md       # NOK-style screening
├── earnings-prep/SKILL.md              # Pre-earnings analysis
├── leaps-screen/SKILL.md               # LEAPS selection
├── option-wall-analysis/SKILL.md       # Max pain + walls
├── tax-optimize/SKILL.md               # LTCG/STCG calculator
├── portfolio-audit/SKILL.md            # Portfolio risk review
├── narrative-reversal-screen/SKILL.md  # ORCL-style hunting
├── sector-rotation-analysis/SKILL.md   # Sector heat map
│
└── review-investment-screenshot/       # (existing)
    └── scripts/
        ├── insider_ratio.py            # v3: openinsider primary, Form 4 code-aware, recency-bucketed
        ├── cluster_buy_scan.py         # NEW: scans openinsider /latest-cluster-buys for cluster signals
        ├── quote_pull.py               # Batch live quotes
        ├── option_walls.py             # Top OI clusters
        └── max_pain.py                 # Max pain calculator

🎓 The Philosophy

Top-down macro-aware framework with these core principles:

1. AI = Factory mode, not software tax. Hyperscalers buy compute like factories buy machines.
2. K-shape divergence: Within sectors, winners crush losers. Pick winners.
3. Power as bottleneck: Constrained inputs reprice upward (electricity, fuel, materials).
4. Demand destruction risk windows: Monitor oil/inflation/geopolitical indicators.
5. Carry trade structures: BOJ policy can trigger global risk-off cascades.

Combined with discipline rules:

• Always check insider trading (use insider_ratio.py, not yfinance summary)
• Always check macro before adding (regime > stock)
• 3-tier entry plans (no "buy at market")
• Position size caps (max 10% single name, max 5% high beta)
• Cash is the alpha (40-50% in danger zones)

📝 Examples — What to Say (English + 中文)

Every skill triggers via natural language in either English or Chinese. Just say it like a human — no slash commands needed (though slash works too).

🆕 macro-warning (daily pullback radar)

English triggers:

• "Run macro warning"
• "Is the market at peak?"
• "Should I take profits?"
• "Regime check"
• "Is it time to buy?"
• "What's the pullback risk today?"

中文 triggers:

• "宏观警报"
• "市场是不是顶了"
• "现在该不该减仓"
• "regime 怎么样"
• "今天能不能加仓"
• "市场风险大不大"

Schedule it (daily auto-run):

• "Set up daily macro-warning at 8am ET pre-market" → triggers /schedule
• "每天早上 8 点跑一次 macro-warning"

📊 analyze-stock (10-step deep dive)

English:

• "Analyze NVDA"
• "Is TSEM a buy?"
• "Deep dive on FN"
• "What about CEG stock?"
• "Research VST"

中文:

• "分析一下 NVDA"
• "TSEM 怎么样"
• "FN 能买吗"
• "深度看一下 GFS"
• "调研 VST"

🔍 find-untapped-thesis (NOK-style screening)

English:

• "Find me the next NOK"
• "What's undervalued in AI Power"
• "Show me cheap names in semiconductor"
• "Find untapped uranium plays"

中文:

• "找未爆发的 AI 电力股"
• "光通信板块还有什么便宜的"
• "找下一个 NOK"
• "X 主题筛选"

🎯 find-alpha (3-horizon discovery)

English:

• "Find alpha"
• "Weekly alpha scan"
• "What's the next MRVL setup?"
• "Find me 3 swing trades"

中文:

• "找 alpha"
• "本周 alpha 扫一下"
• "找下一个 MRVL"

📈 macro-risk-check (news-driven macro)

English:

• "Macro check"
• "Is the market safe?"
• "Risk on or off?"

中文:

• "看一下宏观"
• "市场风险怎么样"
• "现在能加仓吗"

💰 earnings-prep (pre-earnings decision)

English:

• "Earnings prep for AMD"
• "Should I hold NVDA through earnings?"
• "What's priced in for CRWD earnings?"
• "AMD reports tomorrow, what do I do?"

中文:

• "AMD 财报前怎么看"
• "NVDA 财报应该减仓吗"
• "CRWD 财报前分析"
• "X implied move"

📞 leaps-screen (long-dated options)

English:

• "LEAPS for NVDA"
• "What call should I buy on TSEM?"
• "Stock or LEAPS for VST?"

中文:

• "NVDA 买什么 LEAPS"
• "TSEM 的长期 call"
• "VST 现货还是期权"
• "FN 2027 call 推荐"

🧱 option-wall-analysis (max pain + gamma)

English:

• "Max pain on NVDA"
• "Option walls for AAPL"
• "Where will SPY pin this week?"

中文:

• "NVDA 的 max pain"
• "AAPL 期权墙"
• "SPY 这周走哪里"

💼 portfolio-audit (full risk audit)

English:

• "Review my portfolio"
• "Audit my book"
• "Am I too concentrated?"
• "What should I trim?"

中文:

• "审一下我的组合"
• "我组合风险大吗"
• "该减什么仓"

🧾 tax-optimize (LTCG vs STCG)

English:

• "Should I sell NOK for tax?"
• "Tax on selling AMD"
• "LTCG vs STCG on NVDA"

中文:

• "X 减仓税务"
• "现在卖还是等长期"
• "X 减仓最省税"

🔄 sector-rotation-analysis

English:

• "Sector rotation"
• "What sector to add?"
• "Am I too tech-heavy?"

中文:

• "板块轮动"
• "该买哪个板块"
• "我是不是 tech 太重"

🪞 narrative-reversal-screen

English:

• "Find beaten-down stocks with thesis"
• "Stocks at bottom that can recover"
• "Comeback candidates"

中文:

• "找暴跌反转股"
• "ORCL 那种反转"
• "已经跌透的好股"

📸 review-investment-screenshot

English: Just paste a portfolio screenshot and ask "what do you think?"

中文: 直接发组合截图，问"看一下我的组合"

🔧 Insider scripts (technical, advanced)

Cluster buy hunt (market-wide):

• "Find cluster buys"
• "Who's buying what?"
• "找 cluster buy"
• "最近高管买入"

Single-stock insider check:

• "Insider check on NVDA"
• "TSEM 内部交易"
• "X 高管在卖吗"

🚀 Common Workflows

Workflow 1: "Should I buy NVDA?"

1. /macro-risk-check          # Is regime safe to add?
2. /analyze-stock NVDA        # 10-step deep dive
3. /option-wall-analysis NVDA # Short-term levels
4. /leaps-screen NVDA         # LEAPS option (if good entry)

Workflow 2: "Should I trim my portfolio?"

1. /macro-risk-check          # Regime read
2. /portfolio-audit           # Full audit (provide positions)
3. /tax-optimize NOK 1000     # For each trim, check tax

Workflow 3: "AMD reports tomorrow, what do I do?"

1. /earnings-prep AMD         # Implied move + scenarios
2. /option-wall-analysis AMD  # Where will it pin
3. /tax-optimize AMD 350      # If trimming, check tax

Workflow 4: "Find me good ideas"

1. /macro-risk-check          # Avoid bad timing
2. /find-untapped-thesis "AI Power"  # Screening
3. /narrative-reversal-screen        # Reversal candidates
4. /analyze-stock [TOP_PICK]         # Deep dive winners

📅 Recommended Recurring Tasks

Set up via /schedule skill (just say "set up daily macro warning at 8am ET" / "每天早上 8 点跑 macro-warning"):

🔧 Key Scripts (under the hood)

All scripts use /tmp/.insider_venv (set up by setup.sh).

Insider data sources (cross-verify, in trust order)

1. openinsider.com/screener?s=TICKER — primary. Form 4 with codes (P=Purchase, S=Sale, A=Award/Grant, M=Exercise, F=Tax, G=Gift). Free.
2. secform4.com — for 10b5-1 plan footnote disclosure.
3. stocktitan.net SEC filings — readable Form 4 narratives.
4. yfinance — fallback. Has known blind spots (missed real cluster buys).

⚠️ Hard Rules (Never Violate)

1. Always run `insider_ratio.py --window 90` (openinsider primary) — never trust yfinance "% Net Shares Purchased" headline (counts RSU as buys)
2. Form 4 code "P" only counts as buy — A/M/F/G are RSU/exercise/tax/gift, NOT buys. Verified false positives: UNH "10 directors" 4/1/2026 (DSU grants), PLTR "Karp 1.47M" (RSU vesting)
3. Verify any "cluster buy" headline at openinsider.com/[TICKER] — news routinely mislabels compensation flows
4. For sells, check 10b5-1 at secform4.com before treating as bearish — scheduled trust sales tell you nothing about today's view
5. Always check macro before adding — even great stocks fail in red regime
6. Position size caps: max 10% single, max 5% high beta
7. 3-tier entry: never "buy at market" without 50DMA / 200DMA fallback
8. Concrete evidence > narrative: "AI is good" ≠ thesis
9. Cite sources: every macro claim has WebSearch link
10. Tax-aware exits: especially for high earners

🐛 Troubleshooting

"yfmcp not found"

claude mcp list  # Check installed
claude mcp add yfmcp -- npx -y @modelcontextprotocol/yfmcp

"Python venv not working"

rm -rf /tmp/.insider_venv
bash ~/.claude/skills/setup.sh

"yfinance: ModuleNotFoundError"

/tmp/.insider_venv/bin/pip install --upgrade yfinance pandas numpy

"Skills not showing up in Claude Code"

• Restart Claude Code
• Verify SKILL.md frontmatter has name: and description:
• Check ~/.claude/skills/ permissions: chmod -R 755 ~/.claude/skills/

📚 Learn More

• Master decision tree: INVESTMENT-WORKFLOW.md
• Agent CLI contract: AGENT-TOOL-REFERENCE.md
• Architecture decisions: ARCHITECTURE.md — why this repo uses direct APIs + 1 MCP, not 3
• Price alerts setup: price-alert/SETUP.md — one-time Telegram bot + GitHub Secrets walkthrough
• Each skill's details: [skill-name]/SKILL.md
• Macro framework: See analyze-stock/SKILL.md Year Theme section
• Insider methodology: See review-investment-screenshot/SKILL.md (existing)

🤝 Sharing With Friends

# They run:
git clone https://github.com/YOUR_USERNAME/claude-investment-skills.git ~/.claude/skills
bash ~/.claude/skills/setup.sh

# That's it. They have your entire investment thinking system.

⚖️ Disclaimer

These skills are tools for personal investment research. They do not constitute financial advice. Past performance doesn't guarantee future results. Consult a licensed financial advisor for actual investment decisions.

The framework is opinionated — it reflects one specific style (top-down, value-aware, macro-conscious, options-friendly). It is NOT designed for:

• Day trading
• Pure quantitative strategies
• Crypto-only portfolios
• Forex trading

📜 Credits

• Framework inspirations: Buffett (margin of safety), Druckenmiller (macro pivots), Stan Weinstein (stage analysis)
• Built with: Claude Code by Anthropic

Version: 1.5 Last updated: 2026-05-10 License: MIT

Changelog

• 2.2 (2026-05-12): NEW SKILL `strategic-partner-firehose` — real-time SEC 8-K + SC 13D monitor for strategic PIPE deals + JVs from NVIDIA/MSFT/SK Telecom/Samsung/Oracle and sovereign funds (MGX, Saudi PIF, Mubadala). Filters: US-listed ≥ $50M mcap, deal ≥ $50M. Auto-scores 0-10 "Partner Score" via cross-skill enrichment. 32 unit tests pass; PENG/SGH backtest scores 9/10 EXCEPTIONAL. Catches "next PENG" 6-18 months before Twitter/Substack pumps. See strategic-partner-firehose/README.md for what 8-K and SC 13D actually are.
• 2.1 (2026-05-12): insider-firehose v2.1: alerts auto-include business one-liner + P/E + market cap + net cash + 52W context + 0-10 Smart Money Score. Enrichment is on by default; toggle via Telegram /enrich on / /enrich off (Chinese aliases too), CLI firehose_cli.py, GitHub Actions input, or ENRICH env var. Non-fatal pipeline — if yfinance fails, falls back to v2.0 basic alert.
• 2.0 (2026-05-11): NEW SKILL insider-firehose — real-time SEC EDGAR Form 4 monitor with Telegram push for officer/director open-market buys ≥ $200k. 30-min cron weekdays. 2-5 min latency vs openinsider's 12-24 hours.
• 1.7 (2026-05-11): Plugin marketplace install path (two-way door with git-clone). 47 SKILL.md script paths rewritten to dual-mode resolution. NEXT-STEPS roadmap.
• 1.6 (2026-05-11): Cloudflare Worker webhook (1-3 sec chat latency), AGENTS.md, pre-rendered Mermaid diagrams, pre-flight methodology embedded in 6 skills.
• 1.5 (2026-05-10): First public release on GitHub. Added MIT LICENSE, INTRODUCTION.md/INTRODUCTION-zh.md (5-min friendly intro), full Chinese translations of ARCHITECTURE, INVESTMENT-WORKFLOW, AGENT-TOOL-REFERENCE. Enhanced README with "How natural language triggers skills" section and 5 real conversation examples (EN + CN). Updated setup.sh to verify macro_pull.py.
• 1.4 (2026-05-09): macro-warning gets a real data backend — scripts/macro_pull.py with direct APIs (yfinance + FRED CSV + CNN unofficial JSON + multpl scrape). New ARCHITECTURE.md documenting why we use direct APIs + 1 MCP instead of 3-MCP stack.
• 1.3 (2026-05-08): New macro-warning skill — daily batch-mode 8-layer pullback radar (NDX P/E >38 / VIX <14 / F&G >85 = override YELLOW). Cron-friendly. Memory integration via macro_history.jsonl. Added bilingual examples section.
• 1.2 (2026-05-05): New AGENT-TOOL-REFERENCE.md — natural-language → CLI contract for AI agents. Cross-linked from all docs.
• 1.1 (2026-05-05): insider_ratio.py v3 (openinsider primary, Form 4 code-aware, 90d default window). New cluster_buy_scan.py. Updated all skills to reflect 8-rule insider methodology (yfinance summary broken, recency dominates, 10b5-1 awareness, BUY rarity, news false positives, yfinance blind spots, micro-buy ESPP filter).
• 1.0 (2026-05-04): Initial release.