| name | stock-researcher |
| description | Zerodha Kite portfolio analyser and on-demand stock deep-dive. Use when the user says "/stock-researcher", "show portfolio menu", or wants to choose which analysis to run. For direct sub-skill invocations use: /stock-researcher:performance, /stock-researcher:stage, /stock-researcher:full, or /stock-researcher:stock <TICKER>.
|
Stock Researcher
MCP Tools used by this skill
mcp__kite__loginmcp__kite__get_profilemcp__kite__get_holdingsmcp__kite__get_historical_datamcp__kite__search_instruments (stock sub-skill only)mcp__kite__get_ltp (stock sub-skill only)
Sub-skills
| Command | What it does |
|---|
/stock-researcher:performance | Module 1 — Portfolio returns vs NIFTY 50, 500, SMLCAP 250 benchmarks |
/stock-researcher:stage | Module 2 — Weinstein stage + 0-100 fundamental scoring for all holdings |
/stock-researcher:full | Module 1 + 2 — Complete portfolio report |
/stock-researcher:stock <TICKER> | Module 3 — 8-section institutional deep-dive on any NSE/BSE stock |
Module Routing — Read FIRST
If the invocation is /stock-researcher:stock <TICKER> or any "analyse TICKER / deep dive on TICKER / research TICKER" request:
→ Skip Step 0. Load stock-researcher-stock sub-skill and follow its steps.
→ Do NOT call get_profile() or get_holdings(). Module 3 resolves the ticker via search_instruments.
If the invocation is /stock-researcher:performance, /stock-researcher:stage, or /stock-researcher:full:
→ Continue to Step 0 below.
If the invocation is /stock-researcher with no sub-command:
→ Show the menu above and ask which module to run.
Step 0 — ALWAYS FIRST for portfolio analysis (parallel)
mcp__kite__get_profile()
mcp__kite__get_holdings()
Extract per stock: tradingsymbol, exchange, instrument_token, quantity,
average_price, last_price, pnl, day_change_percentage
Compute once and reuse:
cost_value = quantity × average_pricecurrent_value = quantity × last_pricetotal_invested = Σ cost_valuetotal_current = Σ current_valuetotal_pnl = total_current − total_investedtotal_return_pct = (total_pnl / total_invested) × 100day_change_abs = last_price × (day_change_percentage/100) × quantity per stocktotal_day_change = Σ day_change_absweight = current_value / total_current per stock- tracking = True if
weight ≤ 0.002 (0.2%)
instrument_token is read directly from holdings — never call search_instruments.
Benchmark tokens (hardcoded — do not search)
| Index | Token |
|---|
| NIFTY 50 | 256265 |
| NIFTY 500 | 268041 |
| NIFTY SMLCAP 250 | 267273 |
Tracking Position Rule
Weight ≤ 0.2% → label TRACKING. Never recommend EXIT based on size alone.
Full stage + concall analysis still applies.
Speed Rules (finish in under 5 minutes)
Rule 1: Fire ALL historical data calls in ONE parallel batch (all stocks + benchmarks simultaneously).
Rule 2: Use from_date = today minus 365 days for ALL fetches. Single dataset serves both modules.
Rule 3: Fire ALL WebSearches in parallel with historical data fetches.
Rule 4: Write JSON in one atomic write (.tmp → rename). Token budget ≤ 3,000 total.
Rule 5: Extract ONLY these values from each candle dataset:
close_today, close_30d, close_90d, close_180d, close_365dma50, ma150, ma200 (approx if <200 trading days available)slope200 = ma200[today] − ma200[30d ago]high_1y, low_1ypct_from_high = ((close_today − high_1y) / high_1y) × 100 ← always ≤ 0pct_above_200ma = ((close_today − ma200) / ma200) × 100
Rule 6: Guards:
- Empty holdings → "No holdings found. Check your Kite session." and stop.
- Stock with <50 trading days → skip MA classification; show "INSUFFICIENT DATA".
- Stage 1 and Stage 2 tracked separately — never merge into "uptrend capital".
Authentication
On session error:
mcp__kite__login()
Show login URL as markdown link. Wait for user confirmation.
JSON Output
Write a single JSON file per run to ~/.portfolio/data/portfolio-YYYY-MM-DD.json.
Latest symlink: ~/.portfolio/data/latest.json
After writing, open the report:
open "$(dirname "$(dirname "$0")")/../../report/report.html" 2>/dev/null \
|| open ~/Desktop/portfolio-report-*.html 2>/dev/null \
|| echo "Report written to ~/.portfolio/data/latest.json — open report/report.html in your browser"
Schema reference: docs/portfolio-data-schema.md (in repo root, one level above this plugin folder)
Output (chat — brief)
- Portfolio: current value, total P&L %, top 3 action flags (with scores)
- Stock deep-dive: ticker, score/100, action, 1-line key insight
Reference files (repo root, relative to plugin)
../../docs/portfolio-data-schema.md — full JSON field reference../../docs/prompt-library-index.md — prompt ID → section mapping for stock deep-dive../../docs/stage-framework.md — Weinstein stage rules../../docs/sample-stock-data.json — exact JSON schema for Module 3 output../../report/report.html — static report UI (never modify)
