# Trader Screener

The Stock Screener.

- Repository: https://github.com/Jakeschincariol/trader-skill (1074 stars)
- Category: Marketing
- License: MIT
- Last updated: 2026-10-14
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add Jakeschincariol/trader-skill --skill trader-screener -g -a claude-code -y`
Codex: `npx skills add Jakeschincariol/trader-skill --skill trader-screener -g -a codex -y`
Cursor: `npx skills add Jakeschincariol/trader-skill --skill trader-screener -g -a cursor -y`
Gemini CLI: `npx skills add Jakeschincariol/trader-skill --skill trader-screener -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Jakeschincariol/trader-skill`

## Description

The Stock Screener. Checks a list of companies against the user's own rules (revenue growth, margins, EPS, P/E, earnings yield, sector, anything in the metrics file), says exactly which rule each company passes or fails and by how much, and ranks the ones that pass into a shortlist. Reads the metrics /trader-analyst writes from SEC filings, or any CSV. Use when the user says "screen for stocks", "find me companies that", "filter my watchlist", "which of these pass my rules", "shortlist candidates", "rank these stocks", or "growing companies under 30 times earnings".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# trader-screener

A screen turns "I want profitable companies that are still growing and not
too expensive" into rules a computer can check, and shows its work: every
pass and every fail comes with the number and the threshold.

Tool in this folder (standard library Python, no network):

```bash
python3 "${CLAUDE_SKILL_DIR}/screen.py" --help
```

## What it reads and writes

- Metrics: `trader/metrics.json` from `/trader-analyst` (`facts.py --metrics`),
  or any JSON list or CSV with a `ticker` column. CSV numbers may carry `$`,
  `%` and commas.
- Prices (optional): `trader/prices.json` (`{"prices": {"AAPL": 341.27}}`,
  any source; `/trader-alerts` writes it). With prices it adds `price`, `pe`
  (price / trailing EPS, only when EPS is positive) and `earnings_yield`.
- Rules: a JSON file, `rules.example.json` in this folder to start from.
- Writes `trader/shortlist.json` with `--out`: who passed, their score and
  why, who failed and why.

## The rules file

```json
{"name": "Growing, profitable, not priced for perfection",
 "rules": [{"metric": "revenue_growth_yoy", "op": ">=", "value": 10},
           {"metric": "operating_margin", "op": ">=", "value": 25},
           {"metric": "pe", "op": "<=", "value": 35}],
 "rank":  [{"metric": "revenue_growth_yoy", "order": "desc", "weight": 2},
           {"metric": "pe", "order": "asc", "weight": 1}],
 "missing": "fail"}
```

Ops: `>`, `>=`, `<`, `<=`, `==`, `!=`, `between` ([low, high]), `in` and
`not in` (a list, for tickers or sectors to leave out). `"missing": "fail"`
fails a company that lacks a metric a rule needs (banks have no operating
margin in SEC's facts); `"skip"` ignores that rule for it and says so.
Ranking scores each passing company 0 to 1 per rank metric and takes the
weighted average.

## Steps

The rest: https://github.com/Jakeschincariol/trader-skill/blob/HEAD/trader-screener/SKILL.md