| name | screen-stocks |
| description | Undervalued stock screening. EquityQuery-based screening without a predefined stock list. Searches for undervalued stocks across 60+ regions including Japan, US, ASEAN, Hong Kong, Korea, and Taiwan using P/E, P/B, dividend yield, ROE, and more. |
| argument-hint | [region] [preset] [--sector SECTOR] e.g.: japan value, us high-dividend, asean quality, hk value --sector Technology |
| allowed-tools | Bash(python3 *) |
Undervalued Stock Screening Skill
Parse $ARGUMENTS to determine region, preset, and sector, then run the following command.
Execution Command
python3 /Users/kikuchihiroyuki/stock-skills/.claude/skills/screen-stocks/scripts/run_screen.py --region <region> --preset <preset> [--sector <sector>] [--theme <theme>] [--top <N>] [--mode <query|legacy>]
Natural Language Routing
For natural language → skill selection, see .claude/rules/intent-routing.md.
Available Region Codes (yfinance EquityQuery)
Major regions: jp, us, sg, th, my, id, ph, hk, kr, tw, cn, gb, de, fr, in, au, br, ca, etc. (~60 regions)
Available Exchange Codes
| Exchange | Code |
|---|
| Tokyo Stock Exchange | JPX |
| NASDAQ | NMS |
| NYSE | NYQ |
| Singapore Exchange | SES |
| Stock Exchange of Thailand | SET |
| Bursa Malaysia | KLS |
| Indonesia Stock Exchange | JKT |
| Philippine Stock Exchange | PHS |
| Hong Kong Stock Exchange | HKG |
| Korea Stock Exchange | KSC/KOE |
| Taiwan Stock Exchange | TAI |
Theme Screening (KIK-439)
Use --theme <theme> in combination with any preset to narrow screening to a specific theme.
trending/pullback/alpha presets do not support --theme.
| Theme Key | Description | Target Industries (excerpt) |
|---|
ai | AI & Semiconductors | Semiconductors, Software—Infrastructure, Electronic Components |
ev | EV & Next-Gen Vehicles | Auto Manufacturers, Electrical Equipment & Parts |
cloud-saas | Cloud & SaaS | Software—Application, Software—Infrastructure |
cybersecurity | Cybersecurity | Software—Infrastructure (security-focused) |
biotech | Biotech & Drug Development | Biotechnology, Drug Manufacturers |
renewable-energy | Renewable Energy | Solar, Utilities—Renewable |
fintech | Fintech | Software—Application (finance-focused), Capital Markets |
defense | Defense & Aerospace | Aerospace & Defense |
healthcare | Healthcare & Medical Devices | Medical Devices, Health Information Services |
Theme definitions are managed in config/themes.yaml.
Trend Theme Auto-Detection (KIK-440)
Use --auto-theme to automatically detect trending themes via the Grok API (X/Web search) and run screening for each theme sequentially.
Pipeline
- Grok API detects 3–5 trending themes from X/Web (with confidence scores)
- Cross-reference with keys in
themes.yaml; only supported themes are executed (unsupported themes show a skip notice)
- Run the specified preset screening for each theme
Constraints
--auto-theme and --theme are mutually exclusive
- Cannot be combined with
trending/pullback/alpha presets
XAI_API_KEY required (exits with error if not set)
Difference from trending Preset
| --preset trending | --auto-theme |
|---|
| Detection target | Trending individual stocks on X | Trending themes / sectors |
| Granularity | Stock-level | Theme-level |
| Screening | Fundamental evaluation | Any preset within each theme |
Execution Examples
python3 .../run_screen.py --region japan --preset value --auto-theme
python3 .../run_screen.py --region us --preset high-growth --auto-theme
python3 .../run_screen.py --preset value --auto-theme
Screening Modes
--mode query (default): EquityQuery mode. Uses yfinance's EquityQuery API to search for qualifying stocks directly without a predefined list. Works across all regions. Fast.
--mode legacy: Stock list mode. Uses the legacy ValueScreener. Fetches and evaluates stocks from a predefined list (Nikkei 225, S&P 500, etc.) one by one. Japan/US/ASEAN only.
--with-pullback: Add pullback filter. Applies technical pullback detection on top of any preset (value, high-dividend, etc.). No need to combine with --preset pullback (pullback preset takes priority). Output uses the same column format as Pullback mode.
Presets
value: Traditional value investing (low P/E, low P/B, ROE ≥ 5%)
high-dividend: High-dividend stocks (dividend yield ≥ 3%)
growth: Pure growth stocks (high ROE ≥ 15%, revenue growth ≥ 10%; no P/E constraint; selected by growth strength regardless of valuation)
growth-value: Growth-value blend (growth potential + undervaluation)
deep-value: Deep value (very low P/E and P/B)
quality: Quality value (ROE ≥ 15% + undervaluation; stricter ROE threshold than value at 5% → 15%; limited to highly profitable undervalued stocks)
pullback: Pullback entry (temporary correction during an uptrend; 3-stage pipeline: EquityQuery → technical → SR; takes longer to run)
alpha: Alpha signal (3-axis integration: undervaluation + change quality + pullback; 4-stage pipeline: EquityQuery → change quality → pullback detection → 2-axis scoring; takes longer to run)
trending: X-trending stocks (discover trending stocks on X via Grok API → evaluate fundamentals via Yahoo Finance; --theme filtering available; XAI_API_KEY required)
long-term: Long-term investment suitability (ROE ≥ 15%, EPS growth ≥ 10%, dividend ≥ 2%, P/E ≤ 25, P/B ≤ 3, market cap ≥ ¥100B; searches for stable growth stocks suitable for long-term holding)
shareholder-return: Shareholder return focus (ranked by total return rate: dividend yield + buyback yield; with stability assessment: ✅Stable/📈Increasing/⚠️Temporary/📉Declining)
high-growth: High-growth stocks (profit-agnostic; revenue growth ≥ 20%, recent quarterly revenue growth ≥ 10%, PSR ≤ 20, gross margin ≥ 20%; includes unprofitable growth companies; uses PSR instead of P/E to prevent bubble selection) (KIK-432)
small-cap-growth: Small-cap high-growth (market cap ≤ ¥100B; revenue growth ≥ 20%, PSR ≤ 15, gross margin ≥ 20%; targets 10x candidates undiscovered by institutions; auto-adjusts market cap threshold by region; Risk ★★★★) (KIK-437)
contrarian: Contrarian candidates (technically oversold × valuationally cheap × fundamentally sound; 3-axis 100-point scoring; detects "market overreaction," the opposite of value traps) (KIK-504)
momentum: Momentum surge stocks (4-axis scoring: RSI/MACD/momentum rate/volume surge; detects stocks in uptrends; --submode selects stable acceleration vs. surge) (KIK-506)
Momentum Screening Details (KIK-506)
3-Stage Momentum Classification
| Classification | Condition | Description |
|---|
| 🟢 Accelerating | Score 40–69 | Steady upward momentum; high continuity with no overheating |
| 🟡 Surging | Score 70–89 | Rapid price rise; high short-term attention but watch for correction |
| 🔴 Overheated | Score 90–100 | Overheated state; high return potential but elevated correction risk |
--submode Parameter
Use --submode to filter by classification.
| Value | Shows | Recommended Use Case |
|---|
stable (default) | 🟢 Accelerating only | When you want stable uptrend stocks |
surge | 🟡 Surging + 🔴 Overheated | When you also want short-term surge stocks |
4-Axis Scoring
| Axis | Max | Condition |
|---|
| RSI strength | 25 | RSI ≥ 60 |
| MACD cross | 25 | MACD > signal line (bullish cross) |
| Momentum rate | 25 | 20-day price change rate exceeds threshold |
| Volume surge | 25 | 5-day avg volume / 20-day avg volume ≥ 1.3 |
Total score ≥ 40 qualifies as a momentum stock.
Output
Display results in Markdown table format. EquityQuery mode adds a Sector column.
EquityQuery Mode Columns
Rank / Symbol / Sector / Price / P/E / P/B / Div Yield / ROE / Score
Legacy Mode Columns
Rank / Symbol / Price / P/E / P/B / Div Yield / ROE / Score
Pullback Mode Columns
Rank / Symbol / Price / P/E / Pullback% / RSI / Volume Ratio / SMA50 / SMA200 / Score
Alpha Mode Columns
Rank / Symbol / Price / P/E / P/B / Underval / Change / Total / Pullback / α / Accel / FCF / ROE Trend
Growth Mode Columns
Rank / Symbol / Sector / Price / P/E / P/B / EPS Growth / Revenue Growth / ROE
Trending Mode Columns
Rank / Symbol / Trending Reason / Price / P/E / P/B / Div Yield / ROE / Score / Judgment
Contrarian Mode Columns
Rank / Symbol / Price / P/E / P/B / RSI / SMA200 Dev / Tech / Val / Fund / Total / Judgment
Momentum Mode Columns
Rank / Symbol / Price / P/E / RSI / MACD / Momentum Rate / Volume Ratio / Momentum Score / Total Score / Classification
Shareholder Return Mode Columns
Rank / Symbol / Price / Div Yield / Buyback Yield / Total Return / Stability / ROE / P/E
Execution Examples
python3 .../run_screen.py --region japan --preset value
python3 .../run_screen.py --region us --preset high-dividend --sector Technology
python3 .../run_screen.py --region hk --preset value
python3 .../run_screen.py --region asean --preset growth-value
python3 .../run_screen.py --region us --preset value --mode legacy
python3 .../run_screen.py --region japan --preset pullback
python3 .../run_screen.py --region japan --preset alpha
python3 .../run_screen.py --region us --preset alpha
python3 .../run_screen.py --region japan --preset value --with-pullback
python3 .../run_screen.py --region us --preset high-dividend --with-pullback
python3 .../run_screen.py --region japan --preset trending
python3 .../run_screen.py --region us --preset trending --theme "AI"
python3 .../run_screen.py --region japan --preset trending --theme "semiconductors"
python3 .../run_screen.py --region japan --preset long-term
python3 .../run_screen.py --region us --preset long-term
python3 .../run_screen.py --region japan --preset growth
python3 .../run_screen.py --region us --preset growth
python3 .../run_screen.py --region japan --preset shareholder-return
python3 .../run_screen.py --region us --preset shareholder-return
python3 .../run_screen.py --region us --preset high-growth
python3 .../run_screen.py --region japan --preset high-growth
python3 .../run_screen.py --region us --preset value --theme ai
python3 .../run_screen.py --region us --preset high-growth --theme ai
python3 .../run_screen.py --region us --preset value --theme defense
python3 .../run_screen.py --region us --preset growth --theme ev
python3 .../run_screen.py --region us --preset high-growth --theme biotech
python3 .../run_screen.py --region japan --preset small-cap-growth
python3 .../run_screen.py --region us --preset small-cap-growth
python3 .../run_screen.py --region us --preset small-cap-growth --theme ai
python3 .../run_screen.py --region japan --preset contrarian
python3 .../run_screen.py --region us --preset contrarian
python3 .../run_screen.py --region japan --preset contrarian --sector Technology
python3 .claude/skills/screen-stocks/scripts/run_screen.py --preset momentum --region japan --top 10
python3 .claude/skills/screen-stocks/scripts/run_screen.py --preset momentum --region us --top 5 --submode surge
python3 .../run_screen.py --region japan --preset momentum --sector Technology
Annotation Features (KIK-418/419)
Screening results are automatically annotated with markers based on investment notes and trade history.
Marker Legend
| Marker | Meaning | Trigger |
|---|
| ⚠️ | Has concern note | Investment note type=concern |
| 📝 | Has lesson note | Investment note type=lesson |
| 👀 | On watch | Investment note type=observation + keywords like "pass", "waiting" |
Auto-Exclusion of Sold Stocks
Stocks sold within the last 90 days are automatically excluded from screening results. The exclusion count is shown in a message.
Data Sources
- Neo4j knowledge graph (preferred)
- JSON files (fallback when Neo4j is not connected)
Knowledge Integration Rules (KIK-466)
When get_context.py output contains the following, integrate with screening results:
- Recurring stocks (SURFACED 3+ times): "Top 3 consecutive screenings → consistently rated undervalued; detailed report recommended"
- Held stocks: If screening results include held stocks, "Currently held: consider as additional investment material"
- Concern notes: If a result stock has a concern note, append "⚠️ Has concern note"
- Sold stocks: If a previously sold stock reappears at the top, "Previously sold → consider re-entry"