vcp-screener
Screen S&P 500 stocks for Mark Minervini's Volatility Contraction Pattern (VCP). Identifies Stage 2 uptrend stocks forming tight bases with contracting volatility near breakout pivot points. Use when user requests VCP screening, Minervini-style setups, tight base patterns, volatility contraction breakout candidates, or Stage 2 momentum stock scanning.
How do I install this agent skill?
npx skills add https://github.com/mphinance/alpha-skills --skill vcp-screenerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The vcp-screener skill is a legitimate financial tool for screening stocks using the Volatility Contraction Pattern (VCP). It follows security best practices for handling API credentials and communicates with a well-known financial data provider.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
VCP Screener - Minervini Volatility Contraction Pattern
Screen S&P 500 stocks for Mark Minervini's Volatility Contraction Pattern (VCP), identifying Stage 2 uptrend stocks with contracting volatility near breakout pivot points.
When to Use
- User asks for VCP screening or Minervini-style setups
- User wants to find tight base / volatility contraction patterns
- User requests Stage 2 momentum stock scanning
- User asks for breakout candidates with defined risk
Prerequisites
- FMP API key (set
FMP_API_KEYenvironment variable or pass--api-key) - Free tier (250 calls/day) is sufficient for default screening (top 100 candidates)
- Paid tier recommended for full S&P 500 screening (
--full-sp500)
Workflow
Step 1: Prepare and Execute Screening
Run the VCP screener script:
# Default: S&P 500, top 100 candidates
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts
# Custom universe
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts
# Full S&P 500 (paid API tier)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts
Strict Mode (Minervini pure setup)
Only return stocks with valid_vcp=True AND execution_state in (Pre-breakout, Breakout):
python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/
Advanced Tuning (for backtesting)
Adjust VCP detection parameters for research and backtesting:
python3 skills/vcp-screener/scripts/screen_vcp.py \
--min-contractions 3 \
--t1-depth-min 12.0 \
--breakout-volume-ratio 2.0 \
--trend-min-score 90 \
--atr-multiplier 1.5 \
--output-dir reports/
| Parameter | Default | Range | Effect |
|---|---|---|---|
--min-contractions | 2 | 2-4 | Higher = fewer but higher-quality patterns |
--t1-depth-min | 10.0% | 1-50 | Higher = excludes shallow first corrections |
--breakout-volume-ratio | 1.5x | 0.5-10 | Higher = stricter volume confirmation |
--trend-min-score | 85 | 0-100 | Higher = stricter Stage 2 filter |
--atr-multiplier | 1.5 | 0.5-5 | Lower = more sensitive swing detection |
--contraction-ratio | 0.70 | 0.1-1 | Lower = requires tighter contractions |
--min-contraction-days | 5 | 1-30 | Higher = longer minimum contraction |
--lookback-days | 120 | 30-365 | Longer = finds older patterns |
--max-sma200-extension | 50.0% | — | SMA200 distance threshold for Overextended state and penalty |
--wide-and-loose-threshold | 15.0% | — | Final contraction depth above which wide-and-loose flag triggers |
--strict | off | — | Minervini strict mode: only Pre-breakout or Breakout with valid VCP |
Step 2: Review Results
- Read the generated JSON and Markdown reports
- Load
references/vcp_methodology.mdfor pattern interpretation context - Load
references/scoring_system.mdfor score threshold guidance
Step 3: Present Analysis
For each top candidate, present:
- Quality (
composite_score/ rating) — how well-formed is the VCP pattern? - Execution State (
execution_state) — is it buyable now? (Pre-breakout / Breakout = actionable) - Pattern Type (
pattern_type) — Textbook VCP / VCP-adjacent / Post-breakout / Extended Leader / Damaged ★marker if a State Cap was applied (raw score was downgraded)- Contraction details (T1/T2/T3 depths and ratios)
- Trade setup: pivot price, stop-loss, risk percentage
- Volume dry-up ratio and breakout_volume_score
- Relative strength rank
Step 4: Provide Actionable Guidance
By Execution State (primary filter):
- Pre-breakout / Breakout: Pattern is in the active entry window — apply rating-based sizing
- Early-post-breakout: Breakout underway but above ideal entry — reduced size or wait for pullback
- Extended / Overextended: Trade missed — add to watchlist for next base
- Damaged / Invalid: Setup invalidated — do not enter
By Rating (secondary, after state confirms actionability):
- Textbook VCP (90+): Buy at pivot with aggressive sizing (1.5-2x)
- Strong VCP (80-89): Buy at pivot with standard sizing (1x)
- Good VCP (70-79): Buy on volume confirmation above pivot (0.75x)
- Developing (60-69): Add to watchlist, wait for tighter contraction
- Weak/No VCP (<60): Monitor only or skip
3-Phase Pipeline
- Pre-Filter - Quote-based screening (price, volume, 52w position) ~101 API calls
- Trend Template - 7-point Stage 2 filter with 260-day histories ~100 API calls
- VCP Detection - Pattern analysis, scoring, report generation (no additional API calls)
Output
vcp_screener_YYYY-MM-DD_HHMMSS.json- Structured resultsvcp_screener_YYYY-MM-DD_HHMMSS.md- Human-readable report
Resources
references/vcp_methodology.md- VCP theory and Trend Template explanationreferences/scoring_system.md- Scoring thresholds and component weightsreferences/fmp_api_endpoints.md- API endpoints and rate limits
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/mphinance/alpha-skills/vcp-screener">View vcp-screener on skillZs</a>