Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
tradermonty avatar

Us Market Bubble Detector

  • 931 installs
  • 2.5k repo stars
  • Updated July 26, 2026
  • tradermonty/claude-trading-skills

us-market-bubble-detector is a rules-based trading analysis skill that scores US equity bubble risk on a 16-point framework for developers building trading tools or sizing capital before market entry.

About

us-market-bubble-detector is a Claude trading skill from tradermonty/claude-trading-skills that runs objective, rules-based scans to detect when US equity markets are entering bubble territory. Version 2.1 removed subjective qualitative narrative adjustments that inflated scores in v2.0, restoring data-driven scoring where a quantitative Phase 2 score feeds a 16-point scale mapping to phases like Euphoria and corresponding risk-budget guidance. Developers reach for us-market-bubble-detector before committing capital, calibrating algo risk limits, or embedding macro regime checks into trading dashboards and alert pipelines. The skill emphasizes measurable inputs over media narrative impressions, reducing confirmation-bias drift in bubble assessments.

  • Stricter qualitative criteria in v2.1 limits narrative-driven adjustments to a maximum of +3 points
  • Social Penetration scoring now requires direct user reports, dated examples, and minimum 3 independent sources
  • Media/Search Trends demands both Google Trends 5x+ YoY and confirmed mainstream coverage with dates
  • Prevents double-counting of valuation metrics and confirmation bias in risk scoring
  • Outputs clear phase classification (Euphoria, Complacency, etc.) with risk-budget recommendations

Us Market Bubble Detector by the numbers

  • 931 all-time installs (skills.sh)
  • +49 installs in the week ending Jul 28, 2026 (Skillselion tracking)
  • Ranked #508 of 3,301 Productivity & Planning skills by installs in the Skillselion catalog
  • Security screen: MEDIUM risk (skills.sh audit)
  • Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/tradermonty/claude-trading-skills --skill us-market-bubble-detector

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs931
repo stars2.5k
Security audit2 / 3 scanners passed
Last updatedJuly 26, 2026
Repositorytradermonty/claude-trading-skills

How do you detect US stock market bubble risk objectively?

Run objective, rules-based scans that detect when US equity markets are entering bubble territory before committing capital or building trading products.

Who is it for?

Developers building trading systems or sizing portfolios who need rules-based US equity bubble regime checks before capital deployment.

Skip if: Developers seeking intraday trade signals, crypto-only analysis, or discretionary narrative market commentary without quantitative scoring.

When should I use this skill?

US equity exposure is being sized, a trading product needs macro regime guardrails, or bubble risk must be scored before capital commitment.

What you get

Quantitative bubble risk score, market phase label, and recommended risk-budget percentage for position sizing.

  • bubble risk score
  • phase classification
  • risk-budget recommendation

By the numbers

  • Uses a 16-point quantitative scoring framework
  • Version 2.1 released November 3, 2025

Files

SKILL.mdMarkdownGitHub ↗

US Market Bubble Detection Skill (Revised v2.1)

Key Revisions in v2.1

Critical Changes from v2.0: 1. ✅ Mandatory Quantitative Data Collection - Use measured values, not impressions or speculation 2. ✅ Clear Threshold Settings - Specific numerical criteria for each indicator 3. ✅ Two-Phase Evaluation Process - Quantitative evaluation → Qualitative adjustment (strict order) 4. ✅ Stricter Qualitative Criteria - Max +3 points (reduced from +5), requires measurable evidence 5. ✅ Confirmation Bias Prevention - Explicit checklist to avoid over-scoring 6. ✅ Granular Risk Phases - Added "Elevated Risk" phase (8-9 points) for nuanced risk management

---

When to Use This Skill

Use this skill when:

English:

  • User asks "Is the market in a bubble?" or "Are we in a bubble?"
  • User seeks advice on profit-taking, new entry timing, or short-selling decisions
  • User reports social phenomena (non-investors entering, media frenzy, IPO flood)
  • User mentions narratives like "this time is different" or "revolutionary technology" becoming mainstream
  • User consults about risk management for existing positions

Japanese:

  • ユーザーが「今の相場はバブルか?」と尋ねる
  • 投資の利確・新規参入・空売りのタイミング判断を求める
  • 社会現象(非投資家の参入、メディア過熱、IPO氾濫)を観察し懸念を表明
  • 「今回は違う」「革命的技術」などの物語が主流化している状況を報告
  • 保有ポジションのリスク管理方法を相談

---

Evaluation Process (Strict Order)

Phase 1: Mandatory Quantitative Data Collection

CRITICAL: Always collect the following data before starting evaluation

1.1 Market Structure Data (Highest Priority)
□ Put/Call Ratio (CBOE Equity P/C)
  - Source: CBOE DataShop or web_search "CBOE put call ratio"
  - Collect: 5-day moving average

□ VIX (Fear Index)
  - Source: Yahoo Finance ^VIX or web_search "VIX current"
  - Collect: Current value + percentile over past 3 months

□ Volatility Indicators
  - 21-day realized volatility
  - Historical position of VIX (determine if in bottom 10th percentile)
1.2 Leverage & Positioning Data
□ FINRA Margin Debt Balance
  - Source: web_search "FINRA margin debt latest"
  - Collect: Latest month + Year-over-Year % change

□ Breadth (Market Participation)
  - % of S&P 500 stocks above 50-day MA
  - Source: web_search "S&P 500 breadth 50 day moving average"
1.3 IPO & New Issuance Data
□ IPO Count & First-Day Performance
  - Source: Renaissance Capital IPO or web_search "IPO market 2025"
  - Collect: Quarterly count + median first-day return

⚠️ CRITICAL: Do NOT proceed with evaluation without Phase 1 data collection

---

Phase 2: Quantitative Evaluation (Quantitative Scoring)

Score mechanically based on collected data using the following criteria:

Indicator 1: Put/Call Ratio (Market Sentiment)
Scoring Criteria:
- 2 points: P/C < 0.70 (excessive optimism, call-heavy)
- 1 point: P/C 0.70-0.85 (slightly optimistic)
- 0 points: P/C > 0.85 (healthy caution)

Rationale: P/C < 0.7 is historically characteristic of bubble periods
Indicator 2: Volatility Suppression + New Highs
Scoring Criteria:
- 2 points: VIX < 12 AND major index within 5% of 52-week high
- 1 point: VIX 12-15 AND near highs
- 0 points: VIX > 15 OR more than 10% from highs

Rationale: Extreme low volatility + highs indicates excessive complacency
Indicator 3: Leverage (Margin Debt Balance)
Scoring Criteria:
- 2 points: YoY +20% or more AND all-time high
- 1 point: YoY +10-20%
- 0 points: YoY +10% or less OR negative

Rationale: Rapid leverage increase is a bubble precursor
Indicator 4: IPO Market Overheating
Scoring Criteria:
- 2 points: Quarterly IPO count > 2x 5-year average AND median first-day return +20%+
- 1 point: Quarterly IPO count > 1.5x 5-year average
- 0 points: Normal levels

Rationale: Poor-quality IPO flood is characteristic of late-stage bubbles
Indicator 5: Breadth Anomaly (Narrow Leadership)
Scoring Criteria:
- 2 points: New high AND < 45% of stocks above 50DMA (narrow leadership)
- 1 point: 45-60% above 50DMA (somewhat narrow)
- 0 points: > 60% above 50DMA (healthy breadth)

Rationale: Rally driven by few stocks is fragile
Indicator 6: Price Acceleration
Scoring Criteria:
- 2 points: Past 3-month return exceeds 95th percentile of past 10 years
- 1 point: Past 3-month return in 85-95th percentile of past 10 years
- 0 points: Below 85th percentile

Rationale: Rapid price acceleration is unsustainable

---

Phase 3: Qualitative Adjustment (REVISED v2.1)

Limit: +3 points maximum (REDUCED from +5 in v2.0)

⚠️ CONFIRMATION BIAS PREVENTION CHECKLIST:

Before adding ANY qualitative points:
□ Do I have concrete, measurable data? (not impressions)
□ Would an independent observer reach the same conclusion?
□ Am I avoiding double-counting with Phase 2 scores?
□ Have I documented specific evidence with sources?
Adjustment A: Social Penetration (0-1 points, STRICT CRITERIA)
+1 point: ALL THREE criteria must be met:
  ✓ Direct user report of non-investor recommendations
  ✓ Specific examples with names/dates/conversations
  ✓ Multiple independent sources (minimum 3)

+0 points: Any criteria missing

⚠️ INVALID EXAMPLES:
- "AI narrative is prevalent" (unmeasurable)
- "I saw articles about retail investors" (not direct report)
- "Everyone is talking about stocks" (vague, unverified)

✅ VALID EXAMPLE:
"My barber asked about NVDA (Nov 1), dentist mentioned AI stocks (Nov 2),
Uber driver discussed crypto (Nov 3)"
Adjustment B: Media/Search Trends (0-1 points, REQUIRES MEASUREMENT)
+1 point: BOTH criteria must be met:
  ✓ Google Trends showing 5x+ YoY increase (measured)
  ✓ Mainstream coverage confirmed (Time covers, TV specials with dates)

+0 points: Search trends <5x OR no mainstream coverage

⚠️ CRITICAL: "Elevated narrative" without data = +0 points

HOW TO VERIFY:
1. Search "[topic] Google Trends 2025" and document numbers
2. Search "[topic] Time magazine cover" for specific dates
3. Search "[topic] CNBC special" for episode confirmation

✅ VALID EXAMPLE:
"Google Trends: 'AI stocks' at 780 (baseline 150 = 5.2x).
Time cover 'AI Revolution' (Oct 15, 2025).
CNBC 'AI Investment Special' (3 episodes Oct 2025)."

⚠️ INVALID EXAMPLE:
"AI/technology narrative seems elevated" (unmeasurable)
Adjustment C: Valuation Disconnect (0-1 points, AVOID DOUBLE-COUNTING)
+1 point: ALL criteria must be met:
  ✓ P/E >25 (if NOT already counted in Phase 2 quantitative)
  ✓ Fundamentals explicitly ignored in mainstream discourse
  ✓ "This time is different" documented in major media

+0 points: P/E <25 OR fundamentals support valuations

⚠️ SELF-CHECK QUESTIONS (if ANY is YES, score = 0):
- Is P/E already in Phase 2 quantitative scoring?
- Do companies have real earnings supporting valuations?
- Is the narrative backed by fundamental improvements?

✅ VALID EXAMPLE for +1:
"S&P P/E = 35x (vs historical 18x).
CNBC article: 'Earnings don't matter in AI era' (Oct 2025).
Bloomberg: 'Traditional metrics obsolete' (Nov 2025)."

⚠️ INVALID EXAMPLE:
"P/E 30.8 but companies have real earnings and AI has fundamental backing"
(fundamentals support = +0 points)

Phase 3 Total: Maximum +3 points

---

Phase 4: Final Judgment (REVISED v2.1)

Final Score = Phase 2 Total (0-12 points) + Phase 3 Adjustment (0 to +3 points)
Range: 0 to 15 points

Judgment Criteria (with Risk Budget):
- 0-4 points: Normal (Risk Budget: 100%)
- 5-7 points: Caution (Risk Budget: 70-80%)
- 8-9 points: Elevated Risk (Risk Budget: 50-70%) ⚠️ NEW in v2.1
- 10-12 points: Euphoria (Risk Budget: 40-50%)
- 13-15 points: Critical (Risk Budget: 20-30%)

Key Change in v2.1:

  • Added "Elevated Risk" phase (8-9 points) for more nuanced positioning
  • 9 points is no longer extreme defensive zone (was 40% risk budget)
  • Now allows 50-70% risk budget at 8-9 point level
  • More gradual transition from Caution to Euphoria phases

---

Data Sources (Required)

US Market

  • Put/Call: https://www.cboe.com/tradable_products/vix/
  • VIX: Yahoo Finance (^VIX) or https://www.cboe.com/
  • Margin Debt: https://www.finra.org/investors/learn-to-invest/advanced-investing/margin-statistics
  • Breadth: https://www.barchart.com/stocks/indices/sp/sp500?viewName=advanced
  • IPO: https://www.renaissancecapital.com/IPO-Center/Stats

Japanese Market

  • Nikkei Futures P/C: https://www.barchart.com/futures/quotes/NO*0/options
  • JNIVE: https://www.investing.com/indices/nikkei-volatility-historical-data
  • Margin Debt: JSF (Japan Securities Finance) Monthly Report
  • Breadth: https://en.macromicro.me/series/31841/japan-topix-index-200ma-breadth
  • IPO: https://www.pwc.co.uk/services/audit/insights/global-ipo-watch.html

---

Implementation Checklist

Verify the following when using:

□ Have you collected all Phase 1 data?
□ Did you apply each indicator's threshold mechanically?
□ Did you keep qualitative evaluation within +5 point limit?
□ Are you NOT assigning points based on news article impressions?
□ Does your final score align with other quantitative frameworks?

---

Important Principles (Revised)

1. Data > Impressions

Ignore "many news reports" or "experts are cautious" without quantitative data.

2. Strict Order: Quantitative → Qualitative

Always evaluate in this order: Phase 1 (Data Collection) → Phase 2 (Quantitative) → Phase 3 (Qualitative Adjustment).

3. Upper Limit on Subjective Indicators

Qualitative adjustment has a total limit of +5 points. It cannot override quantitative evaluation.

4. "Taxi Driver" is Symbolic

Do not readily acknowledge mass penetration without direct recommendations from non-investors.

---

Common Failures and Solutions (Revised)

Failure 1: Evaluating Based on News Articles

❌ "Many reports on Takaichi Trade" → Media saturation 2 points ✅ Verify Google Trends numbers → Evaluate with measured values

Failure 2: Overreaction to Expert Comments

❌ "Warning of overheating" → Euphoria zone ✅ Judge with measured values of Put/Call, VIX, margin debt

Failure 3: Emotional Reaction to Price Rise

❌ 4.5% rise in 1 day → Price acceleration 2 points ✅ Verify position in 10-year distribution → Objective evaluation

Failure 4: Judgment Based on Valuation Alone

❌ P/E 17 → Valuation disconnect 2 points ✅ P/E + narrative dependence + other quantitative indicators for comprehensive judgment

---

Recommended Actions by Bubble Stage (REVISED v2.1)

Normal (0-4 points)

Risk Budget: 100%

  • Continue normal investment strategy
  • Set ATR 2.0× trailing stop
  • Apply stair-step profit-taking rule (+20% take 25%)

Short-Selling: Not Allowed

  • Composite conditions not met (0/7 items)

Caution (5-7 points)

Risk Budget: 70-80%

  • Begin partial profit-taking (20-30% reduction)
  • Tighten ATR to 1.8×
  • Reduce new position sizing by 50%

Short-Selling: Not Recommended

  • Wait for clearer reversal signals

Elevated Risk (8-9 points) ⚠️ NEW in v2.1

Risk Budget: 50-70%

  • Increase profit-taking (30-50% reduction)
  • Tighten ATR to 1.6×
  • New positions: highly selective, quality only
  • Begin building cash reserves for future opportunities

Short-Selling: Consider Cautiously

  • Only after confirming at least 2/7 composite conditions
  • Small exploratory positions (10-15% of normal size)
  • Strict stop-loss (ATR 2.0×)

Rationale for NEW phase: This zone represents heightened caution without extreme defensiveness. Market shows warning signs but not imminent collapse. Maintain exposure to quality positions while building flexibility.

Euphoria (10-12 points)

Risk Budget: 40-50%

  • Accelerate stair-step profit-taking (50-60% reduction)
  • Tighten ATR to 1.5×
  • No new long positions except on major pullbacks

Short-Selling: Active Consideration

  • After confirming at least 3/7 composite conditions
  • Small positions (20-25% of normal size)
  • Defined risk only (options, tight stops)

Critical (13-15 points)

Risk Budget: 20-30%

  • Major profit-taking or full hedge implementation
  • ATR 1.2× or fixed stop-loss
  • Cash preservation mode - prepare for major dislocation

Short-Selling: Recommended

  • After confirming at least 5/7 composite conditions
  • Scale in with small positions, pyramid on confirmation
  • Tight stop-loss (ATR 1.5× or higher)
  • Consider put options for defined risk

---

Composite Conditions for Short-Selling (7 Items)

Only consider shorts after confirming at least 3 of the following:

1. Weekly chart shows lower highs
2. Volume peaks out
3. Leverage indicators drop sharply (margin debt decline)
4. Media/search trends peak out
5. Weak stocks start to break down first
6. VIX surges (spike above 20)
7. Fed/policy shift signals

---

Output Format

Evaluation Report Structure (v2.1)

# [Market Name] Bubble Evaluation Report (Revised v2.1)

## Overall Assessment
- Final Score: X/15 points (v2.1: max reduced from 16)
- Phase: [Normal/Caution/Elevated Risk/Euphoria/Critical]
- Risk Level: [Low/Medium/Medium-High/High/Extremely High]
- Evaluation Date: YYYY-MM-DD

## Quantitative Evaluation (Phase 2)

| Indicator | Measured Value | Score | Rationale |
|-----------|----------------|-------|-----------|
| Put/Call | [value] | [0-2] | [reason] |
| VIX + Highs | [value] | [0-2] | [reason] |
| Margin YoY | [value] | [0-2] | [reason] |
| IPO Heat | [value] | [0-2] | [reason] |
| Breadth | [value] | [0-2] | [reason] |
| Price Accel | [value] | [0-2] | [reason] |

**Phase 2 Total: X/12 points**

## Qualitative Adjustment (Phase 3) - STRICT CRITERIA

**⚠️ Confirmation Bias Check:**
- [ ] All qualitative points have measurable evidence
- [ ] No double-counting with Phase 2
- [ ] Independent observer would agree

### A. Social Penetration (0-1 points)
- Evidence: [REQUIRED: Direct user reports with dates/names]
- Score: [+0 or +1]
- Justification: [Must meet ALL three criteria]

### B. Media/Search Trends (0-1 points)
- Google Trends Data: [REQUIRED: Measured numbers, YoY multiplier]
- Mainstream Coverage: [REQUIRED: Specific Time covers, TV specials with dates]
- Score: [+0 or +1]
- Justification: [Must have 5x+ search AND mainstream confirmation]

### C. Valuation Disconnect (0-1 points)
- P/E Ratio: [Current value]
- Fundamental Backing: [Yes/No - if Yes, score = 0]
- Narrative Analysis: [REQUIRED: Specific media quotes ignoring fundamentals]
- Score: [+0 or +1]
- Justification: [Must show fundamentals actively ignored]

**Phase 3 Total: +X/3 points (max reduced from +5 in v2.0)**

## Recommended Actions

**Risk Budget: X%** (Phase: [Normal/Caution/Elevated Risk/Euphoria/Critical])
- [Specific action 1]
- [Specific action 2]
- [Specific action 3]

**Short-Selling: [Not Allowed/Consider Cautiously/Active/Recommended]**
- Composite conditions: X/7 met
- Minimum required: [0/2/3/5] for current phase

## Key Changes in v2.1
- Stricter qualitative criteria (max +3, down from +5)
- Added "Elevated Risk" phase for 8-9 points
- Confirmation bias prevention checklist
- All qualitative points require measurable evidence

---

Reference Documents

references/implementation_guide.md (English) - RECOMMENDED FOR FIRST USE

  • Step-by-step evaluation process with mandatory data collection
  • NG examples vs OK examples
  • Self-check quality criteria (4 levels)
  • Red flags during review
  • Best practices for objective evaluation

references/bubble_framework.md (Japanese)

  • Detailed theoretical framework
  • Explanation of Minsky/Kindleberger model
  • Behavioral psychology elements

references/historical_cases.md (Japanese)

  • Analysis of past bubble cases
  • Dotcom, Crypto, Pandemic bubbles
  • Common pattern extraction

references/quick_reference.md (Japanese)

references/quick_reference_en.md (English)

  • Daily checklist
  • Emergency 3-question assessment
  • Quick scoring guide
  • Key data sources

When to Load References

  • First use or need detailed guidance: Load implementation_guide.md
  • Need theoretical background: Load bubble_framework.md
  • Need historical context: Load historical_cases.md
  • Daily operations: Load quick_reference.md (Japanese) or quick_reference_en.md (English)

---

Summary: Essence of v2.1 Revision

v2.0 Problem (Identified Nov 2025):

  • Qualitative adjustment too loose (+5 max)
  • "AI narrative elevated" → +1 point (no data)
  • "P/E 30.8" → +1 point (double-counting with quantitative)
  • Result: 11/16 points - overly bearish without evidence

v2.1 Solution:

  • Qualitative adjustment stricter (+3 max)
  • "AI narrative elevated" → 0 points (unmeasured)
  • "P/E 30.8 but AI has fundamental backing" → 0 points (fundamentals support)
  • Result: 9/15 points - balanced, data-driven assessment

Key Improvements: 1. Confirmation Bias Prevention: Explicit checklist before adding qualitative points 2. Measurable Evidence Required: No points without concrete data (Google Trends, media coverage) 3. Double-Counting Prevention: Valuation must not duplicate Phase 2 quantitative 4. Granular Risk Phases: Added "Elevated Risk" (8-9 points) for nuanced positioning 5. Balanced Risk Budgets: 9 points = 50-70% (not 40% extreme defensive)

Core Principle:

"In God we trust; all others must bring data." - W. Edwards Deming

2025 Lesson: Even data-driven frameworks can be undermined by subjective qualitative adjustments. v2.1 requires MEASURABLE evidence for ALL qualitative points. Independent observers must be able to verify each adjustment.

---

Version History:

  • v2.0 (Oct 27, 2025): Mandatory quantitative data collection
  • v2.1 (Nov 3, 2025): Stricter qualitative criteria, confirmation bias prevention, granular risk phases

Reason for v2.1 Revision: Prevent over-scoring through unmeasured "narrative" assessments and double-counting. Ensure all bubble risk evaluations are independently verifiable and free from confirmation bias.

Related skills

How it compares

Use us-market-bubble-detector for rules-based macro bubble scoring rather than discretionary sentiment reads or single-indicator valuation checks.

FAQ

What changed in us-market-bubble-detector v2.1?

us-market-bubble-detector v2.1 fixed v2.0's subjective qualitative adjustments—such as unmeasured media narrative boosts—that inflated bubble scores; scoring now relies on objective Phase 2 quantitative inputs on a 16-point scale.

What output does us-market-bubble-detector produce?

us-market-bubble-detector returns a quantitative bubble risk score on a 16-point framework, a market phase label such as Euphoria, and a recommended risk-budget percentage to guide defensive position sizing.

Is Us Market Bubble Detector safe to install?

skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Productivity & Planningresearchautomation

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.