> **Windows:** use `.venv\Scripts\python3` instead of `.venv/bin/python3`.

## AGNOSTIC OS / One-shot Design ( Goals )
- This skill is designed to be agnostic to OS and execution environment.
- It loads only essential context on first use and uses a single-shot interaction pattern for reliability.
- Basic usage pattern provided in TOOLS.md and the All Functions list in SKILL.md body.

## Quotation / Command Execution Reliability (common pitfall)
- If a command invocation uses complex shell quoting, it may fail in various environments. Use a here-doc style or a tiny helper script to avoid escaping issues.
- **Crucially, ensure you are executing Python scripts using the interpreter from the skill's virtual environment.** Simply calling `python3` might not use the correct interpreter if the venv is not activated, leading to `ModuleNotFoundError`.
- **Always use the full path to the venv's Python interpreter** for execution, e.g.:
  `/home/openclaw/.openclaw/venv/stocks/bin/python3`
- Ensure that all necessary packages (like `pydantic` for `yfinance-ai`) are installed within this specific venv using its associated `pip` command:
  `/home/openclaw/.openclaw/venv/stocks/bin/pip install <package_name>`
- Example robust pattern using a here-doc:

- If complex inline scripts are problematic, wrap the call in a small Python script file in the workspace (e.g., in `scripts/`) and execute that script using the venv's Python interpreter.

## Agent Quick-Start

After setup, copy the template below into your agent's `TOOLS.md` (or whichever file your framework injects into every session). This is the single most important step — if the agent can see the invocation pattern, it will work every time.

**Replace `SKILL_DIR`** with the absolute path to this skill's directory (e.g. where `scripts/` and `.venv/` live).

Replace METHOD(ARGS) with any call below. Suppress stderr (2>/dev/null) to hide warnings.

## Common Calls

| Need | Method |
|---|---|
| Stock price | `get_stock_price(ticker='AAPL')` |
| Key ratios (P/E, ROE, margins) | `get_key_ratios(ticker='AAPL')` |
| Company overview | `get_company_overview(ticker='AAPL')` |
| Full deep-dive | `get_complete_analysis(ticker='AAPL')` |
| Compare stocks | `compare_stocks(tickers='AAPL,MSFT,GOOGL')` |
| Crypto | `get_crypto_price(symbol='BTC')` |
| Forex | `get_forex_rate(pair='EURUSD')` |
| Commodities | `get_commodity_price(commodity='gold')` |
| News | `get_stock_news(ticker='AAPL')` |
| Market indices | `get_market_indices()` |
| Dividends | `get_dividends(ticker='AAPL')` |
| Earnings | `get_earnings_history(ticker='AAPL')` |
| Analyst recs | `get_analyst_recommendations(ticker='AAPL')` |
| Options chain | `get_options_chain(ticker='SPY')` |
| Market open/closed | `get_market_status()` |

## Routing

- Price / quote → `get_stock_price`
- Ratios / valuation → `get_key_ratios`
- "Tell me about" → `get_company_overview`
- Deep dive → `get_complete_analysis`
- Compare → `compare_stocks`
- Crypto → `get_crypto_price`
- Forex → `get_forex_rate`
- Commodities → `get_commodity_price`
- News → `get_stock_news`

/home/openclaw/.openclaw/venv/stocks/bin/python3 - << 'PY'
import asyncio, sys
sys.path.insert(0, '.')
from yfinance_ai import Tools

t = Tools()
async def main():
    r = await t.get_key_ratios(ticker='UNH')
    print(r)
asyncio.run(main())
PY

# Stocks Skill

## Usage