Claude Investment Skills
13 investment analysis skills + 5 real-time firehoses for 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:
- Ask the PREP questionnaire (OS, what you want — analysis only? alerts? firehoses? webhook for instant chat?)
- Pick a flow (A: core skills · B: GH-cron alerts · C: chat via polling · D: webhook for 1-3 sec replies)
- Walk you through forking the repo, creating a Telegram bot via
@BotFather, setting GitHub Secrets, and enabling workflows — step by step, button by button - 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).
| Skill | What it does |
|---|---|
analyze-stock |
Deep-dive: valuation, technicals, insider activity, full investment thesis |
macro-risk-check |
Macro regime read — run this before opening any new position |
earnings-prep |
Pre-earnings setup: consensus expectations, risk/reward, sizing guidance |
leaps-screen |
Screen for asymmetric long-dated options opportunities |
option-wall-analysis |
Gamma walls, max pain, dealer positioning |
portfolio-audit |
Full portfolio health check with trim recommendations and dry-powder math |
find-untapped-thesis |
Surface under-the-radar angles the market hasn't priced yet |
find-alpha |
Cross-asset alpha screen across sectors and themes |
macro-warning |
Daily pre-market regime scan — catches regime shifts early |
narrative-reversal-screen |
Find tickers where the market narrative is quietly flipping |
sector-rotation-analysis |
Which sectors are flowing in and out of favor |
review-investment-screenshot |
Drop in a portfolio screenshot for honest P&L review |
tax-optimize |
Loss harvesting and lot selection for taxable accounts |
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.
| Firehose | What it monitors |
|---|---|
| Insider | Form 4 filings: executive open-market buys ≥ $200k |
| 13F | Famous funds: Berkshire, Druckenmiller, Ackman, Leopold, Dalio, and more |
| Political | Congress + White House mandatory trade disclosures (STOCK Act / OGE 278-T) |
| Strategic partner | 8-K filings: Tier-1 investor stakes, major contracts, PIPE rounds |
| Price alerts | Custom price triggers on any ticker → instant Telegram push |
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
| Requirement | Purpose | Required for |
|---|---|---|
| Claude Code | Runs all analysis skills locally | Analysis skills |
| Anthropic API key | Powers natural-language analysis (Claude Code handles this) | Analysis skills |
| GitHub account + Personal Access Token | Hosts firehose cron jobs, stores alert state | Firehoses & alerts |
| Telegram bot token + chat ID | Receives push notifications | Alerts |
| Python 3.9+, macOS or Linux | Runs local scripts | Both |
| Cloudflare account | Fast bot replies (1–3 sec vs 2–15 min) | Optional |
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.shis 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.shitself 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.mdis 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)
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:
| You ask | Where it computes | Why |
|---|---|---|
| "What's NVDA's 50DMA right now?" (analysis) | Your laptop, via quote_pull.py called by analyze-stock skill |
Claude Code is interactive; pulls live data when you ask |
| "Alert me when NVDA crosses 50DMA" (alert) | GitHub Actions runner, via check_alerts.py cron |
Cron runs even when your laptop is off; that's the whole point of alerts |
| "Set the alert via Telegram bot" (chat) | GitHub Actions (Option A) or Cloudflare Worker (Option B) | Whichever chat path you picked — both call the same Yahoo API |
Where does each kind of intelligence live?
| Question | Who decides | Where Claude lives |
|---|---|---|
| Which skill matches "analyze NVDA"? | Claude Code on your laptop | Local |
| Should we add NVDA at this price? | analyze-stock skill, runs locally with your Claude |
Local |
Is alerts.json valid JSON? |
GitHub Action sanity check | GitHub (no AI needed) |
| Did NVDA cross $213.89? | check_alerts.py Python |
GitHub cron (no AI) |
| What did the user mean by "等英伟达跌破 213.89 通知我"? | Anthropic API tool-use call | GitHub cron (Option A) OR Cloudflare Worker (Option B) |
| Should I add NVDA after the alert fires? | Your laptop's Claude Code with analyze-stock |
Local |
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.
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%.
| Source | Date | Price | Lag from SEC |
|---|---|---|---|
| SEC 8-K Item 3.02 OpenAI $350M PIPE | 2025-03-31 | $40-48 | 0 days |
| Bloomberg article | 2025-04-15 | $50 | +15 days |
| First Substack writeup | 2025-05-08 | $54 | +38 days |
| Reddit pump | 2025-05-19 | $80 | +49 days |
| Twitter parabolic ATH | 2025-06-16 | $187 | +77 days, +367% |
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.
| Source | Date | Price | Lag from SEC |
|---|---|---|---|
| SEC 8-K Item 1.01 + 8.01 (anonymous customer) | 2026-05-06 | $186 | 0 days |
| Crux Capital tweet | 2026-05-08 | $202 | +2 days (+8%) |
| Kaduna pump tweet | 2026-05-12 | $322 | +6 days, +73% |
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%.
| Source | Date | Price | Lag from SEC |
|---|---|---|---|
| SEC 8-K Item 3.02 SK Telecom $200M | 2024-07-15 | $20 | 0 days |
| Public rebrand SGH → PENG | 2024-10 | $22 | +3 months |
| CES 2025 collaboration press | 2025-01-09 | $22 | +6 months |
| Q2 inference-AI pivot | 2026-04-01 | $18-30 | +20 months |
| First Substack writeup | 2026-05-08 | $44 | +21.5 months |
| Kaduna pump tweet | 2026-05-12 | $50 | +22 months, +150% |
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.
| Source | Date | Trades | Lag from disclosure |
|---|---|---|---|
| OGE 278-T filed (Trump Q1 2026) | 2026-05-08 | MSFT $5M–$25M buy, VIG $5M–$25M sell, ORCL $1M–$5M buy (3/17), NVDA $1M–$5M buy | 0 days (script same day) |
| House PTR filed (McGuire) | 2026-05-13 | AAPL + MSFT + NVDA buys | 0 days (9 AM alert) |
| Media begins covering 278-T | 2026-05-10 | — | +2 days |
| Twitter viral "$MSFT White House buying" | 2026-05-14 | — | +6 days |
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
| Channel | What it watches | What it discovers |
|---|---|---|
insider-firehose |
SEC Form 4 atom feed | Officer/director open-market buys ≥ $200k (Code "P" only, no RSU vests) |
strategic-partner-firehose |
SEC 8-K + SC 13D atom feeds | Path A: Named Tier-1 strategic partners (NVIDIA, MSFT, SK Telecom, Samsung, MGX, PIF, …). Path B: Theme classifier catches anonymous-hyperscaler deals like POWL |
political-firehose |
OGE Form 278-T (White House) + STOCK Act PTR (Congress) | 12 tracked officials' stock trades — 0-day alerts vs. 2–14 day Twitter lag |
composite.py (shared) |
The above firehoses' alert logs | Same ticker fires two channels within 30 days → 🚨🚨🚨 MEGA SIGNAL (rare, < 1% of alerts) |
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
| Component | Cost |
|---|---|
| SEC EDGAR (8-K, 13D, Form 4 feeds) | $0 (public, free, no API key) |
| yfinance enrichment (P/E, mcap, 52W) | $0 |
| GitHub Actions cron | $0 (public repos) |
| Telegram bot | $0 |
| Total | $0 / month |
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)
| State | Path in repo | How to inspect | Who writes it |
|---|---|---|---|
| Active alerts | price-alert/alerts.json |
curl https://raw.githubusercontent.com/<you>/claude-investment-skills/main/price-alert/alerts.json |
You (git commit) OR bot (via chat path) |
| Fired alert history | price-alert/alerts_fired.log |
Same URL, change path | check_alerts.py cron — append-only |
| Bot poll cursor (Option A only) | price-alert/tg_state.json |
Same URL, change path | chat_handler.py cron — auto-commits last update_id |
Your secrets (three potential homes — each path needs its own copy)
| Secret | Local .env |
GitHub Secrets | CF Worker Secrets |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
for local CLI testing | ✅ Flow B+ | ✅ Flow D |
TELEGRAM_CHAT_ID |
for local CLI testing | ✅ Flow B+ | ✅ Flow D |
ANTHROPIC_API_KEY |
optional | ✅ Flow C | ✅ Flow D |
GITHUB_TOKEN (Contents: R+W PAT) |
optional | (built-in to workflow runner) | ✅ Flow D |
GITHUB_REPO (<owner>/<repo>) |
optional | (built-in) | ✅ Flow D |
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
| Question you might ask | Command | What it shows |
|---|---|---|
| Did the cron run recently? | gh run list --workflow=price-alerts.yml --limit=5 --repo <you>/claude-investment-skills |
Last 5 scan runs + status |
| Why did one run fail? | gh run view <run-id> --log |
Full stdout from that run |
| Is the webhook registered + healthy? | curl "https://api.telegram.org/bot$TOKEN/getWebhookInfo" |
URL + pending count + last error |
| What's the webhook doing RIGHT NOW? | cd .../webhook && wrangler tail |
Streaming requests + console.log |
| Is my bot reachable? | curl "https://api.telegram.org/bot$TOKEN/getMe" |
Bot username + capabilities |
| Webhook 7-day request history | Cloudflare dashboard → Workers → price-alert-webhook → Logs |
Real-time + retained 7 days |
Where market data comes from (external sources, fetched fresh each call)
| Data | Source | URL pattern | Cost |
|---|---|---|---|
| Live prices, MAs, target, P/E, 52w range | Yahoo Finance | query1.finance.yahoo.com/v8/finance/chart/<ticker> |
Free, no key |
| Form 4 insider transactions (P / S / A / M / F / G codes) | openinsider.com | openinsider.com/screener?s=<ticker> |
Free, scraped HTML |
| Options chains, IV, OI | yfinance | Same Yahoo backend | Free |
| Macro indicators (CPI, CAPE, yields, USDJPY) | FRED CSV | fred.stlouisfed.org/graph/fredgraph.csv?id=<series> |
Free, no key |
| Fear & Greed Index | CNN unofficial JSON | production.dataviz.cnn.io/index/fearandgreed/graphdata |
Free |
| Stock news, earnings calls, regulatory filings | WebSearch (built into Claude Code) |
n/a | Free w/ Pro/Max sub |
Where your install code lives
| Component | Local path |
|---|---|
| Skill markdown + Python scripts | ~/.claude/skills/ (git clone) OR ~/.claude/plugins/claude-investment-skills/ (plugin install) |
| Python venv | /tmp/.insider_venv/ (created by setup.sh, recreates fresh each run) |
| MCP server registration | ~/.claude.json (managed by claude mcp add) |
| Your conversation memory | ~/.claude/projects/<workspace>/memory/MEMORY.md |
| Your shell history / preferences | (not stored by this toolkit; lives where your shell puts it) |
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.pycall.
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:
🔧 Source:
diagrams/architecture-en.mmd— edit the.mmdfile, push, and the.svg/.pngregenerate automatically viarender-diagrams.yml. See Diagrams pipeline below.
Two chat paths, same outcome — different latency:
| Option A: GitHub Actions polling | Option B: Cloudflare Worker webhook | |
|---|---|---|
| Model | Pull (cron asks "any new msgs?") | Push (Telegram delivers msg instantly) |
| Latency | 2-15 min | 1-3 sec |
| Cold start | Ubuntu VM ~10-30 sec | V8 isolate ~50 ms |
| Setup time | 10 min (SETUP.md) | +5 min on top (SETUP-WEBHOOK.md) |
| Cost | $0 | $0 (CF free tier = 100k req/day) |
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?
GitHub native \``mermaid` block |
Pre-rendered SVG (this repo) | |
|---|---|---|
| Render quality | Variable; clipping, font fallback on mobile | Pixel-perfect, identical everywhere |
| Load speed | Client-side render after page load | Instant (static asset) |
Works in git clone viewer (VS Code, etc.) |
✅ usually | ✅ always |
| Embeddable in other places (slides, docs) | ❌ Mermaid-only | ✅ SVG/PNG works anywhere |
| Source-of-truth file in repo | ❌ Inline in .md, hard to diff |
✅ Standalone .mmd file |
🗣️ How natural language triggers skills (the magic)
You don't memorize commands. You just talk. Here's why that works:
The mechanism
- Each skill has a
description:field in itsSKILL.mdfrontmatter listing trigger phrases (English + Chinese). - Claude Code matches your input against all skill descriptions and picks the best fit.
- 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:
| What you say | What happens |
|---|---|
| "macro warning" | → triggers macro-warning |
| "is the market at peak right now?" | → triggers macro-warning |
| "should I take profits?" | → triggers macro-warning |
| "宏观警报" | → triggers macro-warning |
| "市场是不是要顶了" | → triggers macro-warning |
| "regime 怎么样" | → triggers macro-warning |
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 NVDAis 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:
| Skill | Purpose | Trigger Keywords |
|---|---|---|
analyze-stock |
10-step deep dive on any stock | "analyze X", "is X a buy", "deep dive" |
macro-risk-check |
Daily macro radar (VIX/MOVE/yields/USDJPY) — news-driven | "macro check", "regime read" |
macro-warning |
Daily batch-mode 8-layer pullback radar (NDX PE / VIX / F&G / credit / breadth / sectors) — quantitative | "macro warning", "is the market at peak", "宏观警报" |
find-untapped-thesis |
NOK-style screening (未爆发) | "find next NOK", "undervalued in X" |
earnings-prep |
Pre-earnings decision framework | "should I hold X through earnings" |
leaps-screen |
LEAPS selection (1-3yr options) | "what LEAPS for X", "stock or LEAPS" |
option-wall-analysis |
Max pain + gamma walls | "max pain on X", "option walls" |
tax-optimize |
LTCG vs STCG decisions | "should I sell X for tax" |
portfolio-audit |
Full portfolio risk audit | "review my portfolio", "what to trim" |
narrative-reversal-screen |
ORCL-style reversal screening | "beaten-down with thesis" |
sector-rotation-analysis |
Sector heat map + rotation | "what sector to rotate to" |
price-alert |
GitHub Actions + Telegram price alerts (any ticker, any threshold/%) | "alert me when X hits Y", "X 跌到 Y 通知我" — see setup guide |
Plus existing skills:
review-investment-screenshot— Quick portfolio review from screenshotfind-alpha— Time-horizon alpha screeningschedule— Recurring agents
📦 Installation
Prerequisites
| Requirement | Version | Install |
|---|---|---|
| Claude Code | Latest | https://docs.claude.com/claude-code/install |
| Python | 3.9+ | brew install python3 (macOS) |
| Git | Any | brew install git |
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.csvis 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.pyalready 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)
| Server | Use Case | How |
|---|---|---|
| Notion | Save analysis to your notebook | https://claude.ai/customize/connectors |
| Gmail | Read earnings call summaries | Same as above |
| Google Calendar | Auto-schedule earnings reminders | Same as above |
| Google Drive | Reference investment docs | Same as above |
Step-by-Step Install
# 1. Install Claude Code (if not already)
# Follow https://docs.claude.co
No comments yet
Be the first to share your take.