stocks-query/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a stock query skill for Taiwan stock market data. Python scripts in scripts/ fetch data from Yahoo Finance Taiwan using a Browserless headless browser service, then output concise Chinese summaries.

Environment Variables

All *-browserless.py scripts require these environment variables (loaded from .env):

• BROWSERLESS_ENDPOINT - Browserless service URL (e.g., http://192.168.42.124:13000)
• BROWSERLESS_TOKEN - Authentication token for Browserless

The .env file is searched first in current directory, then at workspace root (3 levels up from scripts).

Architecture

Scripts fall into two categories:

1. Browserless Scripts (Dynamic Content Scraping)

Use Browserless to fetch Yahoo pages that require JavaScript rendering:

Script	Purpose
yahoo-quote-browserless.py	Individual stock quote (price, OHLC, volume, bid/ask)
yahoo-institutional-browserless.py	Three major institutional investors (foreign, trust, dealer)
yahoo-technical-browserless.py	Technical indicators (RSI14, ATR14, KD, Bollinger Bands, 5-day K-line)
yahoo-market-browserless.py	TAIEX weighted index (^TWII) market summary
yahoo-dividend-browserless.py	Dividend history (cash/stock dividend, ex-date, yield)
yahoo-broker-trading-browserless.py	Top broker buy/sell rankings

2. Direct API Scripts (No Browserless Required)

Use Yahoo Finance Chart API directly:

Script	Purpose
yahoo-etf-holdings.py	ETF holdings (top 10, industry distribution, asset allocation)
yahoo-ma-signal.py	Moving averages (MA5/10/20/60) and 20-day bias
yahoo-macd-signal.py	MACD indicator (DIF, DEA, histogram)

3. TWSE Public API Scripts (No Browserless Required)

Use TWSE open data API directly:

Script	Purpose
twse-margin-trading.py	Margin trading balance (融資融券餘額)
twse-day-trading.py	Day trading statistics (當沖交易統計)
twse-foreign-holdings.py	Foreign investor holdings ratio (外資持股比例)

Common Commands

Query individual stock (full analysis)

# Three scripts are typically run together for complete picture
python3 skills/stocks-query/scripts/yahoo-institutional-browserless.py 2330
python3 skills/stocks-query/scripts/yahoo-quote-browserless.py 2330
python3 skills/stocks-query/scripts/yahoo-technical-browserless.py 2330

Query ETF (with holdings)

python3 skills/stocks-query/scripts/yahoo-quote-browserless.py 0050
python3 skills/stocks-query/scripts/yahoo-etf-holdings.py 0050

Query market index

python3 skills/stocks-query/scripts/yahoo-market-browserless.py

MA/MACD signals (direct API, no Browserless)

python3 skills/stocks-query/scripts/yahoo-ma-signal.py 2330
python3 skills/stocks-query/scripts/yahoo-macd-signal.py 2330

Dividend / Broker trading (Browserless)

python3 skills/stocks-query/scripts/yahoo-dividend-browserless.py 2330
python3 skills/stocks-query/scripts/yahoo-broker-trading-browserless.py 2330

TWSE data (margin, day-trading, foreign holdings)

python3 skills/stocks-query/scripts/twse-margin-trading.py 2330
python3 skills/stocks-query/scripts/twse-day-trading.py 2330
python3 skills/stocks-query/scripts/twse-foreign-holdings.py 2330

Script Patterns

• All scripts accept stock symbol as first command-line argument (default provided)
• Browserless scripts use urllib or subprocess with curl to POST to Browserless /content endpoint
• HTML parsing uses regex patterns (not BeautifulSoup) to minimize dependencies
• Output format is Chinese text summaries with bullet points
• Error handling exits with code 1 and prints error message to stderr

Stock Number Format

• Taiwan stocks: 4-digit number (e.g., 2330, 3481)
• ETFs: Typically start with 00 (e.g., 0050, 00922)
• Yahoo suffix: .TW is appended automatically in URLs

Skill Integration

This directory is registered as a skill (see SKILL.md). When users input a stock number or ask about "大盤" (market), the scripts should be executed in sequence and results synthesized into a concise Chinese summary with plain-language interpretation of technical indicators.