Detect and analyze trending market themes across sectors. Use when user asks about current market themes, trending sectors, sector rotation, thematic investing, what themes are hot or cold, or wants to identify bullish and bearish market narratives with lifecycle analysis.
82%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
This skill detects and ranks trending market themes by analyzing cross-sector momentum, volume, and breadth signals. It identifies both bullish (upward momentum) and bearish (downward pressure) themes, assesses lifecycle maturity (Emerging/Accelerating/Trending/Mature/Exhausting), and provides a confidence score combining quantitative data with narrative analysis.
3-Dimensional Scoring Model:
Key Features:
--scan-hits--history-fileExplicit Triggers:
Implicit Triggers:
When NOT to Use:
Required:
finvizfinance>=1.5.0.
pip install -r skills/theme-detector/requirements.txtCron / mixed-Python fallback: If the active python3 is older than 3.10, or a newer Hermes venv lacks the data-science dependencies, run the detector through uv with an explicit modern interpreter and temporary dependencies instead of editing the environment mid-cron:
uv run --python 3.12 \
--with requests --with beautifulsoup4 --with lxml \
--with pandas --with numpy --with yfinance \
--with 'finvizfinance>=1.5.0' --with PyYAML \
python skills/theme-detector/scripts/theme_detector.py \
--finviz-api-key "$FINVIZ_API_KEY" \
--fmp-api-key "$FMP_API_KEY" \
--output-dir reports/Use this as a setup workaround, not as evidence that the detector is broken; still report FINVIZ/FMP/API-data caveats separately.
Optional API Keys:
FINVIZ Elite (recommended for full industry coverage and speed):
export FINVIZ_API_KEY=your_finviz_elite_api_key_hereFMP API (optional, for P/E ratio valuation data):
export FMP_API_KEY=your_fmp_api_key_hereThe generated requirements retain core dependencies and the shared calendar pin.
finvizfinance>=1.5.0 is installed only on Python 3.10+; Python 3.9 skips
that optional package and supports Elite group export through requests. Public
group fetch is disabled on Python 3.9 even if an older scraper remains installed.
Without FINVIZ Elite, the skill uses public FINVIZ scraping (limited to ~20 stocks per industry, slower rate limits).
Check that API keys are configured (see Prerequisites):
# Verify FINVIZ Elite API key (optional but recommended)
test -n "${FINVIZ_API_KEY:-}" && echo "FINVIZ key configured"
# Verify FMP API key (optional)
echo $FMP_API_KEYRun the main detection script:
python3 skills/theme-detector/scripts/theme_detector.py \
--output-dir reports/Script Options:
# Full run (public FINVIZ mode, no API key required)
python3 skills/theme-detector/scripts/theme_detector.py \
--output-dir reports/
# With FINVIZ Elite API key
python3 skills/theme-detector/scripts/theme_detector.py \
--finviz-api-key $FINVIZ_API_KEY \
--output-dir reports/
# With FMP API key for enhanced stock data
python3 skills/theme-detector/scripts/theme_detector.py \
--fmp-api-key $FMP_API_KEY \
--output-dir reports/
# Custom limits
python3 skills/theme-detector/scripts/theme_detector.py \
--max-themes 5 \
--max-stocks-per-theme 10 \
--output-dir reports/
# Explicit FINVIZ mode
python3 skills/theme-detector/scripts/theme_detector.py \
--finviz-mode public \
--output-dir reports/
# Add Stockbee/Pradeep-style leadership evidence
python3 skills/theme-detector/scripts/theme_detector.py \
--scan-hits data/theme_scan_hits_YYYY-MM-DD.json \
--narrative-scores data/theme_narrative_scores_YYYY-MM-DD.json \
--history-file reports/theme_detector_history.json \
--as-of-date YYYY-MM-DD \
--output-dir reports/Scan-hit input contract: --scan-hits accepts JSON, JSONL, or CSV. Rows may be pre-labeled with scan_type / scan_types, or raw rows with fields such as symbol, return_5d, change_pct, volume, avg_volume_50d, relative_volume, true_range, atr_20, atr_expansion, close_location, industry, sector, and theme_guess. A raw row can expand into multiple hits when it satisfies multiple rules.
Initial scan rules:
five_day_20pct: return_5d >= 20ep9m: volume >= 9,000,000, relative_volume >= 2.0, and change_pct >= 4range_expansion: change_pct >= 4, true_range / atr_20 >= 1.5 or atr_expansion >= 1.5, and close_location >= 0.75new_high: explicit new_high / is_new_high, or 52-week high evidencehigh_rs: rs_rating >= 90 or normalized relative_strength >= 0.90Narrative-score input contract: --narrative-scores is an offline JSON input, not a live WebSearch call. It accepts either {"Theme Name": 82} or {"themes": {"Theme Name": {"narrative_keyword_score": 82}}}. Missing narrative input leaves narrative_keyword_score as null and reduces theme_match_coverage; it does not fail the run.
Expected Execution Time:
The script generates two output files:
theme_detector_YYYY-MM-DD_HHMMSS.json - Structured data for programmatic usetheme_detector_YYYY-MM-DD_HHMMSS.md - Human-readable reportRead the JSON output to understand quantitative results:
# Find the latest report
ls -lt reports/theme_detector_*.json | head -1
# Read the JSON output
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.jsonFor the top 5 themes (by Theme Heat score), execute WebSearch queries to confirm narrative strength:
Search Pattern:
"[theme name] stocks market [current month] [current year]"
"[theme name] sector momentum [current month] [current year]"Evaluate narrative signals:
Update Confidence levels based on findings:
Cross-reference detection results with knowledge bases:
Reference Documents to Consult:
references/cross_sector_themes.md - Theme definitions and constituent industriesreferences/thematic_etf_catalog.md - ETF exposure options by themereferences/theme_detection_methodology.md - Scoring model detailsreferences/finviz_industry_codes.md - Industry classification referenceAnalysis Framework:
For Hot Bullish Themes (Heat >= 70, Direction = Bullish):
For Hot Bearish Themes (Heat >= 70, Direction = Bearish):
For Emerging Themes (Heat 40-69, Lifecycle = Emerging):
For Exhausted Themes (Heat >= 60, Lifecycle = Exhausting):
Present the final report to the user using the report template structure:
# Theme Detection Report
**Date:** YYYY-MM-DD
**Mode:** FINVIZ Elite / Public
**Themes Analyzed:** N
**Data Quality:** [note any limitations]
## Theme Dashboard
[Top themes table with Heat, Direction, Lifecycle, Confidence]
## What Changed Today
[Newly emerging themes, largest heat acceleration, new EP9M clusters, fading themes]
## Leadership Evidence
[5D+20%, EP9M, range expansion, new highs, high-RS counts and leader symbols]
## Bullish Themes Detail
[Detailed analysis of bullish themes sorted by Heat]
## Bearish Themes Detail
[Detailed analysis of bearish themes sorted by Heat]
## All Themes Summary
[Complete theme ranking table]
## Industry Rankings
[Top performing and worst performing industries]
## Sector Uptrend Ratios
[Sector-level aggregation if uptrend data available]
## Methodology Notes
[Brief explanation of scoring model]Save the report to reports/ directory.
The skill generates two output files in the reports/ directory:
JSON Output (theme_detector_YYYY-MM-DD_HHMMSS.json):
{
"report_type": "theme_detector",
"generated_at": "2026-04-18 10:30:00",
"metadata": {
"generated_at": "2026-04-18 10:30:00",
"data_mode": "full",
"finviz_mode": "elite",
"fmp_available": true,
"max_themes": 14,
"max_stocks_per_theme": 5,
"data_sources": {
"finviz_industries": 152,
"yfinance_stocks": 68,
"etf_volume": 24
}
},
"summary": {
"total_themes": 14,
"bullish_count": 8,
"bearish_count": 6,
"top_bullish": "AI & Machine Learning",
"top_bearish": "Regional Banks"
},
"themes": {
"all": [
{
"name": "AI & Machine Learning",
"direction": "bullish",
"heat": 85.3,
"maturity": 42.1,
"stage": "Accelerating",
"confidence": "Medium",
"heat_label": "Hot",
"industries": ["Software - Infrastructure", "Semiconductors"],
"representative_stocks": ["NVDA", "MSFT"],
"stock_details": [{"symbol": "NVDA"}, {"symbol": "MSFT"}],
"proxy_etfs": ["BOTZ", "ROBO"],
"theme_match_score": 78.4,
"theme_match_components": {
"industry_match_score": 84.2,
"static_stock_hit_score": 80.0,
"proxy_etf_momentum_score": 70.0,
"narrative_keyword_score": null
},
"leader_candidates": [
{
"symbol": "NVDA",
"leader_score": 91.2,
"scan_types": ["ep9m", "range_expansion"],
"risk_bucket": "mega"
}
],
"theme_origin": "seed"
}
],
"bullish": [...],
"bearish": [...],
"match_ranked": [...]
},
"industry_rankings": {
"top": [...],
"bottom": [...]
},
"sector_uptrend": {...},
"data_quality": {...}
}Markdown Report (theme_detector_YYYY-MM-DD_HHMMSS.md):
Key Output Fields (per theme):
| Field | Description |
|---|---|
heat | 0-100 direction-neutral theme strength |
direction | "bullish" (LEAD) or "bearish" (LAG) |
stage | Emerging / Accelerating / Trending / Mature / Exhausting |
confidence | Low / Medium / High (script caps at Medium; WebSearch can elevate) |
representative_stocks | Top ticker symbols for the theme |
stock_details | Optional stock metric objects for the selected representatives |
proxy_etfs | Thematic ETF tickers (length = ETF count; higher = more crowded) |
theme_match_score | 0-100 evidence-quality score from industries, stock basket hits, proxy ETF confirmation, and optional narrative input |
theme_match_components | Inspectable sub-scores explaining the theme match |
leader_candidates | Evidence-ranked symbols for the theme; not entry/stop/invalidation guidance |
fresh_leadership_symbols | Current-run symbols with EP9M, range expansion, or new-high evidence |
extended_symbols | Current-run symbols with 5D+20% evidence; used as overextension evidence only |
theme_origin | "seed" (from YAML config) or "discovered" (auto-clustered) |
scripts/)Main Scripts:
theme_detector.py - Main orchestrator script
python3 theme_detector.py [options]theme_classifier.py - Maps industries to cross-sector themes
cross_sector_themes.mdfinviz_industry_scanner.py - FINVIZ industry data collection
calculators/lifecycle_calculator.py - Lifecycle maturity assessment
report_generator.py - Report output generation
references/)Knowledge Bases:
cross_sector_themes.md - Theme definitions with industries, ETFs, stocks, and matching criteriathematic_etf_catalog.md - Comprehensive thematic ETF catalog with counts per themefinviz_industry_codes.md - Complete FINVIZ industry-to-filter-code mappingtheme_detection_methodology.md - Technical documentation of the 3D scoring modelassets/)report_template.md - Markdown template for report generation with placeholder formatInstall requirements.txt before running the detector. --as-of-date is a
strict YYYY-MM-DD ceiling used by both uptrend freshness checks and provider
history windows. Because FINVIZ, quote, profile, and uptrend inputs are live
rather than PIT snapshots, a non-current --as-of-date fails closed. Freshness
counts XNYS sessions and excludes future-dated source rows.
With a configured FINVIZ_API_KEY or --finviz-api-key, industry and sector
performance prefer the authenticated Elite group CSV export. A non-200,
unreadable, empty or malformed export warns and falls back to the public
finvizfinance>=1.5.0 scraper on Python 3.10+. --finviz-mode public forces
public-only operation even when a key is configured. Without a key, public
scraping remains the normal path; provider blocking is still possible.
CSV percentage points, including values below 1%, are normalized to decimal
ratios at the client boundary and converted to percentage points once by the
pipeline. Missing, nonfinite or malformed required export data cannot appear as
a successful empty scan. If neither source supplies industry data, the CLI
exits 1 with upgrade/key/access guidance instead of producing a report. These
source failures do not print keys, response bodies, request URLs or raw exception
messages. Library callers retain the list-returning interface; an explicit
empty api_key selects public-only and an omitted key reads FINVIZ_API_KEY.
Dynamic representative-stock selection safely merges overlapping proxy ETF holdings, keeps both reasons, and retains the maximum available composite score; unscored ETF/static candidates use zero. This remains candidate research, with no broker execution or guarantee of provider access. The repair's regression fixtures are synthetic; a successful test is not live provider acceptance.
| Feature | Elite Mode | Public Mode |
|---|---|---|
| Industry coverage | All ~145 industries | All ~145 industries |
| Stocks per industry | Full universe | ~20 stocks (page 1) |
| Rate limiting | 0.5s between requests | 2.0s between requests |
| Data freshness | Real-time | 15-min delayed |
| API key required | Yes ($39.50/mo) | No |
| Execution time | ~2-3 minutes | ~5-8 minutes |
Theme direction is determined by majority vote of constituent industries' relative rank:
_majority_direction() counts bullish vs. bearish industries within each theme; the majority winsDisplay mapping: "bullish" → LEAD, "bearish" → LAG (see report_generator.py::_direction_label())
A LEAD theme indicates relative outperformance of its constituent industries. A LAG theme may still have positive absolute returns — it indicates relative underperformance, not a short signal.
This analysis is for educational and informational purposes only.
Version: 1.0 Last Updated: 2026-02-16 API Requirements: FINVIZ Elite (recommended) or public mode (free); FMP API optional Execution Time: ~2-8 minutes depending on mode Output Formats: JSON + Markdown Themes Covered: 14+ cross-sector themes
tradermonty/claude-trading-skills
163ceb4
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.