watchlist-manager

Original：🇺🇸 English

Translated

9 scripts

Manage a US stock/ETF watchlist file - add, remove, update, list and validate tickers with thesis, entry, price targets, stop, tags, and per-ticker alert rules. Use when the user says things like "add NVDA to my watchlist", "set a stop on AAPL at 210", "what's on my watchlist", "remove TSLA", or "tag these as semis".

4installs

Sourceeli-alvarado/us-watchlist-alerts

Added on2026-10-16

NPX Install

npx skill4agent add eli-alvarado/us-watchlist-alerts watchlist-manager

SKILL.md Content

View Translation Comparison →

Watchlist Manager (US markets)

Maintains a single source-of-truth watchlist file that the

price-alerts

and

watchlist-brief

skills read. Informational tool only. Never place, modify, or cancel a trade. Editing the watchlist is not trading.

File location

```
$WATCHLIST_FILE
```
if set, else
```
./watchlist.json
```
in the working directory (YAML
```
watchlist.yaml
```
works if PyYAML is installed).
If none exists, create it from
```
examples/watchlist.json
```
structure with an empty
```
tickers
```
list. Ask before overwriting an existing file.

Schema (version 1)

json

{
  "version": 1,
  "settings": { "cooldown_minutes": 240, "rearm_pct": 0.5, "sessions": ["regular"],
                "volume_spike_multiple": 2.0, "near_52w_pct": 2.0, "earnings_days": 3,
                "max_alerts_per_run": 20, "extra_closures": [], "stale_after_seconds": 900 },
  "tickers": [{
    "symbol": "NVDA",            // required, uppercase; class shares as BRK.B or BRK-B
    "side": "long",              // long | short | watch
    "added": "2026-10-15",
    "thesis": "AI datacenter capex",
    "entry": 160.0, "targets": [190.0, 220.0], "stop": 140.0,
    "tags": ["ai", "semis"],
    "alerts": [ {"type": "price_below", "value": 150, "cooldown_minutes": 60} ],
    "notes": ""
  }]
}

Alert

type

values and their

value

meaning are documented in

skills/price-alerts/SKILL.md

. A

stop

implies a

stop_hit

alert and

targets

imply

target_hit

automatically.

Operations (prefer the script; it validates and writes atomically)

scripts/

ships next to this SKILL.md after

npx skills add

. Run from this skill folder, or from a git clone (root

scripts/

is the same files):

bash

python3 scripts/watchlist.py init
python3 scripts/watchlist.py init --empty
python3 scripts/watchlist.py add NVDA --thesis "AI capex" --entry 160 --target 190 --target 220 --stop 140 --tag ai --tag semis --alert price_below:150
python3 scripts/watchlist.py add NVDA --file swing.json --alert price_below:150
python scripts/watchlist.py update NVDA --stop 145
python scripts/watchlist.py update NVDA --tag megacap --alert rsi_above:75 --append
python scripts/watchlist.py remove NVDA
python scripts/watchlist.py list [--tag semis]
python scripts/watchlist.py show NVDA
python scripts/watchlist.py validate

If Python is unavailable, edit the JSON by hand following the schema and the validation rules below.

Workflow

Resolve the ticker. Uppercase it. If the user gives a company name, confirm the symbol (e.g. "Alphabet" -> GOOGL or GOOG?). Reject non-US listings or say they are unsupported by default data.
Sanity-check with a live quote:
```
python scripts/quotes.py NVDA
```
. If the user's stop is above price for a long (or target below), point it out and ask.
Capture the why. If no thesis is given, ask once for a one-line reason; store
```
""
```
if they decline. Don't invent a thesis.
Suggest, don't impose, alerts. Reasonable defaults to offer: stop/target levels,
```
earnings_within: 3
```
,
```
pct_move: 5
```
(last vs prior close). If they want a drop that trades through a % and then recovers, offer opt-in
```
intraday_low_pct
```
/
```
intraday_extreme_pct
```
and say those use session low/high, not last. Mention
```
iv_above
```
/
```
intraday_range_pct
```
only if they ask about vol or today's range — ATM IV is unofficial Yahoo, not IV rank. Only add what they agree to.
Write, validate, confirm. Show the resulting entry (symbol, entry, stop, targets, alerts) in one compact line.

Validation rules

Symbol matches
```
^[A-Z]{1,5}([.-][A-Z]{1,2})?$
```
; no duplicates.
```
entry
```
,
```
stop
```
,
```
targets[]
```
are numbers. For
```
side: long
```
, stop < entry; for
```
side: short
```
, stop > entry.
```
settings.sessions
```
if present is a non-empty list of
```
regular
```
/
```
pre
```
/
```
after
```
.
```
settings.extra_closures
```
if present is ISO dates (
```
YYYY-MM-DD
```
) for unscheduled full-day closures.
Every alert
```
type
```
is a known type.

Listing format

Don'ts

Don't delete tickers without explicit instruction; for "clean up my list" propose removals first.
Don't give buy/sell recommendations. You may describe levels and risk (e.g. "stop is 12% below entry").