US Watchlist Alerts
Overview
Keeps a US stock/ETF watchlist in a local JSON file, checks it for price alerts, and writes a short morning or after-close brief. It uses Python 3 standard library scripts and free public quotes, so no API key is needed. Alerts follow NYSE market hours and holidays and are de-duplicated between runs. The full scripts live in the upstream repository eli-alvarado/us-watchlist-alerts; this skill explains how to install and use them.
When to Use This Skill
- Use when the user asks to add, remove, tag or list tickers on a watchlist ("add NVDA to my watchlist", "set a stop on AAPL at 210").
- Use when the user asks "any alerts?" or wants a scheduled check of price levels, daily % moves, 52-week highs/lows, moving-average crosses, RSI or earnings dates.
- Use when the user asks for a morning brief or a recap of how their watchlist did today.
How It Works
Step 1: Install the upstream skills
Ask the user before installing. Then run from the project root:
npx skills add eli-alvarado/us-watchlist-alerts
This installs three skills (watchlist-manager, price-alerts, watchlist-brief) with their scripts/ folders into .claude/skills/ or .agents/skills/. Requires Python 3.10+.
Step 2: Create or edit the watchlist
python3 .claude/skills/watchlist-manager/scripts/watchlist.py init
python3 .claude/skills/watchlist-manager/scripts/watchlist.py add NVDA
The file is $WATCHLIST_FILE if set, else ./watchlist.json, else ~/.config/us-watchlist-alerts/watchlist.json. init --preset offers starter lists (mega-cap tech, index ETFs, sector ETFs, dividend staples). add checks that the ticker exists; --no-verify skips that check offline.
Step 3: Check alerts
python3 .claude/skills/price-alerts/scripts/alerts.py --dry-run --format json
Only new alerts are reported. Outside market hours the last regular close is used and labeled as such.
Step 4: Write a brief
python3 .claude/skills/watchlist-brief/scripts/brief.py --kind morning
Use --kind close after 16:05 ET. On weekends and NYSE holidays, say the market is closed and give the next session.
Examples
Example 1: Add a ticker with a stop
User: "Add AAPL to my watchlist with a stop at 210."
Run watchlist.py add AAPL, then set the stop with the watchlist-manager update command and confirm the saved values back to the user.
Example 2: Morning check
User: "Anything I should know before the open?"
Run alerts.py --dry-run --format json and brief.py --kind morning, then summarize the table and any alerts in a few lines.
Best Practices
- ✅ Run scripts from the project root by path; do not
cd into the skill folder.
- ✅ Report the quote timestamp and source; free quotes can be delayed, stale or unavailable. Do not promise a fixed 15-minute delay without provider evidence.
- ❌ Do not place, modify or cancel orders, even if a broker tool is connected.
- ❌ Do not present alerts or briefs as financial advice or trade signals.
Limitations
- US markets only (NYSE/Nasdaq hours and holidays).
- The default quote source is the unofficial Yahoo Finance chart endpoint, which can be delayed or rate-limited.
- This skill does not replace environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.
Security & Safety Notes
- Installing runs
npx skills add, which downloads files from GitHub; ask the user before running it and let them review the scripts.
- The scripts make outbound HTTPS requests for quotes only. Optional ntfy/Slack/webhook delivery sends alert text to the configured endpoint; only enable it when the user sets it up.
- Optional providers (Alpaca, Finnhub, Alpha Vantage) read keys from environment variables. Never print or log those keys.
- The skill only edits the local watchlist and alert-state files. It never trades.