market-top-detector
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
Install / Use
npx skills add tradermonty/claude-trading-skills --skill market-top-detectorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of market-top-detector
market-top-detector scores 91/100 on our quality scale, 1051st of 4,700 Development & Engineering skills we index (top 23%).
Its SKILL.md is 8.4 KB long, well organised into 22 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
With 2,885 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so market-top-detector is actively maintained.
- Our last check on 2026-10-29 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
market-top-detector compared with similar skills
All 4 of these similar skills score higher than market-top-detector; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| market-top-detector (this skill)by tradermonty | 91 | 2.9k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install market-top-detector?
- Run
npx skills add tradermonty/claude-trading-skills --skill market-top-detector. The install tabs above show the steps for each supported agent. - Which AI agents does market-top-detector work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is market-top-detector safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is market-top-detector still maintained?
- The repository was last updated about 2 months ago, so market-top-detector is actively maintained.
Skill content
View source on GitHubname: market-top-detector description: Detects market top probability 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.
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_KEYenvironment 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 |
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 calibration data
When to Load References
- First use: Load
market_top_methodology.mdfor 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
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
