Index of every page on this site: llms.txt
All skills
tradermonty avatar

/market-top-detector

@f95e770
Run it yourself

Assesses heuristic market top risk using O'Neil Distribution Days, Minervini Leading Stock Deterioration, and Monty Defensive Sector Rotation. Generates a 0-100 composite score with risk zone classification. Use when user asks about market top risk, distribution days, defensive rotation, leadership breakdown, or whether to reduce equity exposure. Focuses on 2-8 week tactical timing signals for 10-20% corrections.

Use this Skill: https://skilld.dev/gh/tradermonty/claude-trading-skills/market-top-detector

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈109 tokens for metadata: the name and description. ≈2.5k when used: this file. ≈6k more on demand in 4 files.

Description uses 5.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈438 characters, or 5.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Market Top Detector Skill

Purpose

Assess heuristic market top risk using a 6-component scoring system (0-100). Integrates three market risk methodologies:

  1. O'Neil - Distribution Day accumulation (institutional selling)
  2. Minervini - Leading stock deterioration pattern
  3. 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.

Score interpretation

Treat the 0-100 composite as a heuristic risk score, not an estimated event probability. A score of 70 does not mean a 70% chance of a top. Risk-budget percentages are policy heuristics, not measured outcome frequencies. Historical patterns are retrospective estimates, not point-in-time evidence. Report no comparable episode when any component is unavailable/invalid or nearest-pattern weighted RMS exceeds 15 points. This tolerance is a predeclared heuristic, not an empirically validated similarity threshold. Follow the point-in-time evaluation protocol before making calibration claims. No measured calibration results are supplied.

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 risk 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:

  1. Fetch S&P 500, QQQ, VIX quotes and history from FMP API
  2. Fetch Leading ETF (ARKK, WCLD, IGV, XBI, SOXX, SMH, KWEB, TAN) data
  3. Fetch Sector ETF (XLU, XLP, XLV, VNQ, XLK, XLC, XLY) data
  4. Calculate all 6 components
  5. 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 Risk) 40-55% Aggressive profit-taking
81-100 Critical (Very High Risk) 20-35% Maximum defense, hedging

Exchange Calendar and Replay

Install requirements.txt before running the detector. Freshness uses XNYS sessions rather than weekdays. --as-of YYYY-MM-DD is accepted for the live evaluation date, but historical live replay fails closed because the current quote endpoints are not point-in-time sources.

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 retrospective illustrative estimates

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

Price-bar availability

Missing, non-finite or invalid OHLCV values are never replaced with zero. Price inputs must be positive finite numbers; actual volume zero is valid. Existing close-to-adjClose and high-to-close fallbacks apply only when the primary key is absent, never when its value is invalid. A gap in a used window makes that component unavailable with data_gaps diagnostics; bars are not compressed. Either index's gap invalidates the maximum DD comparison. Unavailable components have zero composite contribution and render as N/A. When no components remain, composite_score is null, the zone is Unavailable and budget is Not assessed. Exposure Coach treats that report as missing critical input; the strategy synthesizer refuses to generate an allocation from it. Normal-data formulas, weights and partial-fetch policies are unchanged.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert1d5 checks · Risk CRITICAL
  • Gen Agent Trust Hub2d

    The Market Top Detector skill evaluates tactical market risk using established financial methodologies (O'Neil, Minervini, and Monty). Investigations into automated malware alerts confirmed them to be false positives for legitimate data-fetching scripts. The skill adheres to security best practices, including robust API key redaction and strict input validation.

  • Socket1d

    No alerts

  • Snyk1d

    Risk: MEDIUM · 1 issue

  • Runlayer8mo

    3/36 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at f95e770. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 days ago

README badge

README badge for tradermonty/claude-trading-skills/market-top-detector