Market Top Detector Agent Skill

Market Top Detector Skill

Purpose

Detect the probability of a market top formation using a quantitative 6-component scoring system (0-100). Integrates three proven market top detection methodologies:

• O'Neil - Distribution Day accumulation (institutional selling)
• Minervini - Leading stock deterioration pattern
• Monty - Defensive sector rotation signal

Unlike the Bubble Detector (macro/multi-month evaluation), this skill focuses on tactical 2-8 week timing signals that precede 10-20% market corrections.

When to Use This Skill

English:

• User asks "Is the market topping?" or "Are we near a top?"
• User notices distribution days accumulating
• User observes defensive sectors outperforming growth
• User sees leading stocks breaking down while indices hold
• User asks about reducing equity exposure timing
• User wants to assess correction probability for the next 2-8 weeks

Japanese:

• 「天井が近い？」「今は利確すべき？」
• ディストリビューションデーの蓄積を懸念
• ディフェンシブセクターがグロースをアウトパフォーム
• 先導株が崩れ始めているが指数はまだ持ちこたえている
• エクスポージャー縮小のタイミング判断
• 今後2〜8週間の調整確率を評価したい

Prerequisites

Required:

• FMP API Key: Set $FMP_API_KEY environment variable or pass --api-key. Free tier sufficient (~33 API calls per execution).
• WebSearch Access: Required to collect S&P 500 breadth (50DMA %) and CBOE Put/Call ratio data.

Optional:

• Margin Debt Data: Enhances sentiment scoring but typically 1-2 months lagged.
• VIX Term Structure: Auto-detected from FMP API if VIX3M quote available; manual override via --vix-term.

Data Freshness: All manually collected data should be from the most recent 3 business days for accurate analysis.

Difference from Bubble Detector

| Aspect | Market Top Detector | Bubble Detector |

|--------|-------------------|-----------------|

| Timeframe | 2-8 weeks | Months to years |

| Target | 10-20% correction | Bubble collapse (30%+) |

| Methodology | O'Neil/Minervini/Monty | Minsky/Kindleberger |

| Data | Price/Volume + Breadth | Valuation + Sentiment + Social |

| Score Range | 0-100 composite | 0-15 points |

Execution Workflow

Phase 1: Data Collection via WebSearch

Before running the Python script, collect the following data using WebSearch.

Data Freshness Requirement: All data must be from the most recent 3 business days. Stale data degrades analysis quality.

1. S&P 500 Breadth (200DMA above %)
   AUTO-FETCHED from TraderMonty CSV (no WebSearch needed)
   The script fetches this automatically from GitHub Pages CSV data.
   Override: --breadth-200dma [VALUE] to use a manual value instead.
   Disable: --no-auto-breadth to skip auto-fetch entirely.

2. [REQUIRED] S&P 500 Breadth (50DMA above %)
   Valid range: 20-100
   Primary search: "S&P 500 percent stocks above 50 day moving average"
   Fallback: "market breadth 50dma site:barchart.com"
   Direct fallback when search snippets are poor: fetch `https://www.barchart.com/stocks/quotes/$S5FI/overview` and extract the embedded `lastPrice` / `tradeTime` for “S&P 500 Stocks Above 50-Day Average”.
   Record the data date

3. [REQUIRED] CBOE Equity Put/Call Ratio
   Valid range: 0.30-1.50
   Primary search: "CBOE equity put call ratio today"
   Fallback: "CBOE total put call ratio current"
   Fallback: "put call ratio site:cboe.com"
   Direct fallback when Cboe CSV endpoints are stale: fetch `https://ycharts.com/indicators/cboe_equity_put_call_ratio` and parse the “Last Value” / “Latest Period” table fields. Treat this as a secondary source and cite it in freshness notes.
   Record the data date

4. [OPTIONAL] VIX Term Structure
   Values: steep_contango / contango / flat / backwardation
   Primary search: "VIX VIX3M ratio term structure today"
   Fallback: "VIX futures term structure contango backwardation"
   Note: Auto-detected from FMP API if VIX3M quote available.
   CLI --vix-term overrides auto-detection.

5. [OPTIONAL] Margin Debt YoY %
   Primary search: "FINRA margin debt latest year over year percent"
   Fallback: "NYSE margin debt monthly"
   Note: Typically 1-2 months lagged. Record the reporting month.

Phase 2: Execute Python Script

Run the script with collected data as CLI arguments:

python3 skills/market-top-detector/scripts/market_top_detector.py \
  --api-key $FMP_API_KEY \
  --breadth-50dma [VALUE] --breadth-50dma-date [YYYY-MM-DD] \
  --put-call [VALUE] --put-call-date [YYYY-MM-DD] \
  --vix-term [steep_contango|contango|flat|backwardation] \
  --margin-debt-yoy [VALUE] --margin-debt-date [YYYY-MM-DD] \
  --output-dir reports/ \
  --context "Consumer Confidence=[VALUE]" "Gold Price=[VALUE]"
# 200DMA breadth is auto-fetched from TraderMonty CSV.
# Override with --breadth-200dma [VALUE] if needed.
# Disable with --no-auto-breadth to skip auto-fetch.

The script will:

• Fetch S&P 500, QQQ, VIX quotes and history from FMP API
• Fetch Leading ETF (ARKK, WCLD, IGV, XBI, SOXX, SMH, KWEB, TAN) data
• Fetch Sector ETF (XLU, XLP, XLV, VNQ, XLK, XLC, XLY) data
• Calculate all 6 components
• Generate composite score and reports

Phase 3: Present Results

Present the generated Markdown report to the user, highlighting:

• Composite score and risk zone
• Data freshness warnings (if any data older than 3 days)
• Strongest warning signal (highest component score)
• Historical comparison (closest past top pattern)
• What-if scenarios (sensitivity to key changes)
• Recommended actions based on risk zone
• Follow-Through Day status (if applicable)
• Delta vs previous run (if prior report exists)

6-Component Scoring System

| # | Component | Weight | Data Source | Key Signal |

|---|-----------|--------|-------------|------------|

| 1 | Distribution Day Count | 25% | FMP API | Institutional selling in last 25 trading days |

| 2 | Leading Stock Health | 20% | FMP API | Growth ETF basket deterioration |

| 3 | Defensive Sector Rotation | 15% | FMP API | Defensive vs Growth relative performance |

| 4 | Market Breadth Divergence | 15% | Auto (CSV) + WebSearch | 200DMA (auto) / 50DMA (WebSearch) breadth vs index level |

| 5 | Index Technical Condition | 15% | FMP API | MA structure, failed rallies, lower highs |

| 6 | Sentiment & Speculation | 10% | FMP + WebSearch | VIX, Put/Call, term structure |

Risk Zone Mapping

| Score | Zone | Risk Budget | Action |

|-------|------|-------------|--------|

| 0-20 | Green (Normal) | 100% | Normal operations |

| 21-40 | Yellow (Early Warning) | 80-90% | Tighten stops, reduce new entries |

| 41-60 | Orange (Elevated Risk) | 60-75% | Profit-taking on weak positions |

| 61-80 | Red (High Probability Top) | 40-55% | Aggressive profit-taking |

| 81-100 | Critical (Top Formation) | 20-35% | Maximum defense, hedging |

API Requirements

Required: FMP API key (free tier sufficient: ~33 calls per execution)

Optional: WebSearch data for breadth and sentiment (improves accuracy)

Output Files

• JSON: market_top_YYYY-MM-DD_HHMMSS.json
• Markdown: market_top_YYYY-MM-DD_HHMMSS.md

Reference Documents

references/market_top_methodology.md

• Full methodology with O'Neil, Minervini, and Monty frameworks
• Component scoring details and thresholds
• Historical validation notes

references/distribution_day_guide.md

• Detailed O'Neil Distribution Day rules
• Stalling day identification
• Follow-Through Day (FTD) mechanics

references/historical_tops.md

• Analysis of 2000, 2007, 2018, 2022 market tops
• Component score patterns during historical tops
• Lessons learned and calibration data

When to Load References

• First use: Load market_top_methodology.md for full framework understanding
• Distribution day questions: Load distribution_day_guide.md
• Historical context: Load historical_tops.md
• Regular execution: References not needed - script handles scoring