From 95260407002819d98962c6f4859eae22bd2caa52 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Sun, 10 May 2026 22:24:41 -0700
Subject: [PATCH] chore(skills/stocks): tighten SKILL.md to modern format

---
 optional-skills/finance/stocks/SKILL.md | 95 ++++++++++++++-----------
 1 file changed, 54 insertions(+), 41 deletions(-)

diff --git a/optional-skills/finance/stocks/SKILL.md b/optional-skills/finance/stocks/SKILL.md
index 48d54b35499..347b0c5972c 100644
--- a/optional-skills/finance/stocks/SKILL.md
+++ b/optional-skills/finance/stocks/SKILL.md
@@ -1,44 +1,51 @@
 ---
 name: stocks
-description: Real-time stock quotes, price history, company search, multi-stock compare, and crypto prices via Yahoo Finance. No API key required.
-version: 1.0.0
-author: Mibayy
+description: Stock quotes, history, search, compare, crypto via Yahoo.
+version: 0.1.0
+author: Mibay (Mibayy), Hermes Agent
 license: MIT
+platforms: [linux, macos, windows]
 metadata:
   hermes:
-    tags: [stocks, finance, market, trading, crypto, yahoo-finance, investing]
+    tags: [Stocks, Finance, Market, Crypto, Investing]
     category: finance
-    requires_toolsets: [terminal]
+    related_skills: [dcf-model, comps-analysis, lbo-model]
 ---
 
-# Stocks & Finance Skill
+# Stocks Skill
 
-Real-time stock market data via Yahoo Finance.
-5 commands: quote, search, history, compare, crypto.
-
-No API key needed. Python stdlib only.
-
----
+Read-only market data via Yahoo Finance. Five commands: `quote`, `search`,
+`history`, `compare`, `crypto`. Python stdlib only — no API key, no pip
+installs. Yahoo's endpoint is unofficial and may rate-limit or change.
 
 ## When to Use
-- User asks for a stock price (AAPL, TSLA, MSFT...)
-- User wants to look up a company by name
-- User wants price history or performance over time
-- User wants to compare multiple stocks side by side
-- User asks for a crypto price (BTC, ETH, SOL...)
 
----
+- User asks for a current stock price (AAPL, TSLA, MSFT, ...)
+- User wants to look up a ticker by company name
+- User wants OHLCV history or performance over a date range
+- User wants to compare several tickers side by side
+- User asks for a crypto price (BTC, ETH, SOL, ...)
 
 ## Prerequisites
-Python 3.8+ stdlib only. No pip installs.
-Script path: `~/.hermes/skills/finance/scripts/stocks_client.py`
 
----
+Python 3.8+ stdlib only. Optional: set `ALPHA_VANTAGE_KEY` to enrich
+`market_cap`, `pe_ratio`, and 52-week levels when Yahoo's crumb-protected
+fields come back null. Free key: https://www.alphavantage.co/support/#api-key
+
+## How to Run
+
+Invoke through the `terminal` tool. Once installed:
+
+```
+SCRIPT=~/.hermes/skills/finance/stocks/scripts/stocks_client.py
+python3 $SCRIPT quote AAPL
+```
+
+All output is JSON on stdout — pipe through `jq` if you want to slice it.
 
 ## Quick Reference
 
 ```
-SCRIPT=~/.hermes/skills/finance/scripts/stocks_client.py
 python3 $SCRIPT quote AAPL
 python3 $SCRIPT quote AAPL MSFT GOOGL TSLA
 python3 $SCRIPT search "Tesla"
@@ -47,36 +54,42 @@ python3 $SCRIPT compare AAPL MSFT GOOGL
 python3 $SCRIPT crypto BTC ETH SOL
 ```
 
----
-
 ## Commands
 
-### quote SYMBOL [SYMBOL2...]
+### `quote SYMBOL [SYMBOL2 ...]`
+
 Current price, change, change%, volume, 52-week high/low.
 
-### search QUERY
-Find stocks by company name. Returns top 5: symbol, name, exchange, type.
+### `search QUERY`
 
-### history SYMBOL [--range RANGE]
-Price history. Ranges: 1mo, 3mo, 6mo, 1y, 5y (default: 1mo).
-Returns OHLCV per day + stats (min, max, avg, total_return_pct).
+Find tickers by company name. Returns top 5: symbol, name, exchange, type.
 
-### compare SYMBOL1 SYMBOL2 [...]
-Side-by-side: price, change%, 52w performance.
+### `history SYMBOL [--range RANGE]`
 
-### crypto SYMBOL [SYMBOL2...]
-Crypto prices. Pass BTC not BTC-USD (appended automatically).
+Daily OHLCV plus stats (min, max, avg, total return %). Ranges: `1mo`,
+`3mo`, `6mo`, `1y`, `5y`. Default: `1mo`.
 
----
+### `compare SYMBOL1 SYMBOL2 [...]`
+
+Side-by-side: price, change%, 52-week performance.
+
+### `crypto SYMBOL [SYMBOL2 ...]`
+
+Crypto prices. Pass `BTC` (the script appends `-USD` automatically).
 
 ## Pitfalls
-- Yahoo Finance API is unofficial and may change without notice.
-- market_cap and pe_ratio may return null (require session crumb).
-- Rate limits: add delays between bulk requests.
 
----
+- Yahoo Finance's API is unofficial. Endpoints can change or rate-limit
+  without notice — if requests start failing, that's why.
+- `market_cap` and `pe_ratio` may return null on `quote` when Yahoo's
+  crumb session isn't established. Set `ALPHA_VANTAGE_KEY` to backfill.
+- Add a small delay between bulk requests to avoid rate-limiting.
+- This is read-only — no order placement, no account integration.
 
 ## Verification
-```bash
-python3 ~/.hermes/skills/finance/scripts/stocks_client.py quote AAPL
+
 ```
+python3 ~/.hermes/skills/finance/stocks/scripts/stocks_client.py quote AAPL
+```
+
+Returns a JSON object with `symbol: "AAPL"` and a numeric `price` field.