us-watchlist-alerts

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.