Agent Skills › staskh/trading_skills › whale-hunting

whale-hunting

GitHub

扫描标的期权链以识别机构级大额交易。通过Yahoo Finance粗筛异常合约，再利用Massive API精确检测秒级资金流出异常，输出鲸鱼事件详情及汇总数据。

.claude/skills/whale-hunting/SKILL.md staskh/trading_skills

触发场景

询问特定代码的异常期权活动查询大型机构块状交易分析机构期权资金流向

安装

npx skills add staskh/trading_skills --skill whale-hunting -g -y

更多选项

非标准路径

npx skills add https://github.com/staskh/trading_skills/tree/main/.claude/skills/whale-hunting -g -y

不安装直接使用

npx skills use staskh/trading_skills@whale-hunting

指定 Agent (Claude Code)

npx skills add staskh/trading_skills --skill whale-hunting -a claude-code -g -y

安装 repo 全部 skill

npx skills add staskh/trading_skills --all -g -y

预览 repo 内 skill

npx skills add staskh/trading_skills --list

SKILL.md

Frontmatter

{
    "name": "whale-hunting",
    "description": "Detect institutional whale activity in options for a given underlying. Use when the user asks about unusual options activity, large block trades, whale trades, or institutional options flow for a specific symbol.",
    "dependencies": [
        "trading-skills"
    ]
}

Whale Hunting

Scans option chains for a given underlying to identify institutional-sized trades using a two-step approach:

Crude scan (Yahoo Finance) — finds contracts with anomalous daily investment vs the rest of the chain.
Precise drill-down (Massive API) — fetches per-second bars for each candidate and flags seconds with outlier dollar invested.

Instructions

Note: If uv is not installed or pyproject.toml is not found, replace uv run python with python in all commands below.

uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py SYMBOL [--months N] [--date YYYY-MM-DD] [--sigma F] [--sigma-z F] [--summary]

Arguments

SYMBOL — Underlying ticker (e.g. AAPL, NVDA, SPY)
--months — Max months until option expiration to consider (default: 2)
--date — Trading date to analyze in YYYY-MM-DD format (default: latest trading day)
--sigma — Std-deviation multiplier for crude outlier threshold (default: 3.0)
--sigma-z — Modified Z-Score threshold for per-second small-sample detection (default: 3.5)
--summary — Also compute per-ticker summary and include it in the JSON output

Output

Returns JSON with:

underlying — The scanned symbol
trading_date — Date analyzed
source — "massive" (per-second data) or "yahoo only" (daily chain data)
total_whales — Total whale events found
total_call_invested — Sum of invested dollars in call whale events
total_put_invested — Sum of invested dollars in put whale events
call_put_ratio — Call invested / put invested (null if no puts)
whales — List of whale events:
- timestamp, ticker, type, strike, expiry
- close, volume, transactions, invested, break_even
summary (present only when --summary is passed) — List of per-ticker aggregates:
- ticker, type, strike, expiry, whale_count, total_invested, break_even

Examples

# Hunt whales for AAPL (latest trading day)
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py AAPL

# Hunt whales for NVDA on a specific date
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py NVDA --date 2026-03-13

# With per-ticker summary
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py HOOD --months 3 --summary

# Looser detection threshold
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py SPY --sigma 2.0

Reporting

After running the script, present the results as follows.

Header line:

Whale activity for {underlying} on {trading_date} — source: {source} Call flow: ${total_call_invested:,.0f} | Put flow: ${total_put_invested:,.0f} | C/P ratio: {call_put_ratio:.2f}

When --summary was requested, render the summary array as a table:

Time (ET)	Ticker	Type	Strike	Expiry	# Events	Total Invested	Break Even
{timestamp}	{ticker}	{type}	{strike}	{expiry}	{whale_count}	${total_invested:,.0f}	{break_even}

Sort by total_invested descending. For multi-event rows use the time range of first–last event (e.g. 11:46–12:33).

Interpretation guidance:

source: "massive" — High-confidence; per-second block trade data from Massive API
source: "yahoo only" — Fallback; daily-level data (Massive API key missing or no intraday data)
Low C/P ratio (< 0.5) — Bearish institutional positioning
High C/P ratio (> 2.0) — Bullish institutional positioning
transactions: 1 — Single block trade; strongest whale signal

Requirements

MASSIVE_API_KEY environment variable for per-second data. Without it, falls back to Yahoo Finance daily data.

Timezone

All timestamps and time-based calculations must use the America/New_York timezone. All JSON output must include generated_at (NY time string) and data_delay fields.