Macro Regime Detector

Macro Regime Detector

Detect structural macro regime transitions using monthly-frequency cross-asset ratio analysis. This skill identifies 1-2 year regime shifts that inform strategic portfolio positioning.

When to Use

• User asks about current macro regime or regime transitions
• User wants to understand structural market rotations (concentration vs broadening)
• User asks about long-term positioning based on yield curve, credit, or cross-asset signals
• User references RSP/SPY ratio, IWM/SPY, HYG/LQD, or other cross-asset ratios
• User wants to assess whether a regime change is underway

Workflow

1. Load reference documents for methodology context:

• references/regime_detection_methodology.md
• references/indicator_interpretation_guide.md

1. Execute the main analysis script:

``bash python3 skills/macro-regime-detector/scripts/macro_regime_detector.py `` This fetches 600 days of data for 9 ETFs + Treasury rates (10 API calls total).

1. Read the generated Markdown report and present findings to user.

1. Provide additional context using references/historical_regimes.md when user asks about historical parallels.

Prerequisites

• FMP API Key (required): Set FMP_API_KEY environment variable or pass --api-key
• Free tier (250 calls/day) is sufficient (script uses ~10 calls)

6 Components

| # | Component | Ratio/Data | Weight | What It Detects | |---|-----------|------------|--------|-----------------| | 1 | Market Concentration | RSP/SPY | 25% | Mega-cap concentration vs market broadening | | 2 | Yield Curve | 10Y-2Y spread | 20% | Interest rate cycle transitions | | 3 | Credit Conditions | HYG/LQD | 15% | Credit cycle risk appetite | | 4 | Size Factor | IWM/SPY | 15% | Small vs large cap rotation | | 5 | Equity-Bond | SPY/TLT + correlation | 15% | Stock-bond relationship regime | | 6 | Sector Rotation | XLY/XLP | 10% | Cyclical vs defensive appetite |

5 Regime Classifications

• Concentration: Mega-cap leadership, narrow market
• Broadening: Expanding participation, small-cap/value rotation
• Contraction: Credit tightening, defensive rotation, risk-off
• Inflationary: Positive stock-bond correlation, traditional hedging fails
• Transitional: Multiple signals but unclear pattern

Output

• macro_regime_YYYY-MM-DD_HHMMSS.json — Structured data for programmatic use
• macro_regime_YYYY-MM-DD_HHMMSS.md — Human-readable report with:

1. Current Regime Assessment
2. Transition Signal Dashboard
3. Component Details
4. Regime Classification Evidence
5. Portfolio Posture Recommendations

Relationship to Other Skills

| Aspect | Macro Regime Detector | Market Top Detector | Market Breadth Analyzer | |--------|----------------------|--------------------|-----------------------| | Time Horizon | 1-2 years (structural) | 2-8 weeks (tactical) | Current snapshot | | Data Granularity | Monthly (6M/12M SMA) | Daily (25 business days) | Daily CSV | | Detection Target | Regime transitions | 10-20% corrections | Breadth health score | | API Calls | ~10 | ~33 | 0 (Free CSV) |

Script Arguments

python3 macro_regime_detector.py [options]

Options:
  --api-key KEY       FMP API key (default: $FMP_API_KEY)
  --output-dir DIR    Output directory (default: current directory)
  --days N            Days of history to fetch (default: 600)

Resources

• references/regime_detection_methodology.md — Detection methodology and signal interpretation
• references/indicator_interpretation_guide.md — Guide for interpreting cross-asset ratios
• references/historical_regimes.md — Historical regime examples for context

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xonevn-ai
• Source: xonevn-ai/xone-trading-skills
• License: MIT
• Homepage: https://xone.vn

Install and usage instructions live in the source repository linked above.