finmind

name	finmind
type	capability
description	Fetch and maintain Taiwan stock-market company data (prices, monthly revenue, financial statements, dividends, shareholding, market cap, institutional flows) via the FinMind API, for any company listed in Taiwan (TWSE/TPEx), referenced by stock id (data_id) or company name. Triggers: "fetch Taiwan stock data for X", "TSMC monthly revenue", "TWSE financials for <stock id>", "Taiwan dividends/shareholding for Y".
env	["FINMIND_TOKEN"]
requires	["analyst-kit-core"]

Preamble (run first)

PLAN MODE EXCEPTION — ALWAYS RUN: this block only reads state and writes to ~/.analyst-kit/.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
if [ ! -x "$_AK/bin/analyst-kit-preamble" ]; then
  for d in ~/.claude/skills/analyst-kit-core .claude/skills/analyst-kit-core ~/.codex/skills/analyst-kit-core .codex/skills/analyst-kit-core; do
    [ -x "$d/bin/analyst-kit-preamble" ] && _AK="$d" && break
  done
  [ -x "$_AK/bin/analyst-kit-preamble" ] || _AK="$(find ~/.claude/plugins -maxdepth 6 -type d -name analyst-kit-core 2>/dev/null | head -1)"
  [ -n "$_AK" ] && { mkdir -p ~/.analyst-kit; printf '%s' "$_AK" > ~/.analyst-kit/core-path; } || true
fi
[ -x "$_AK/bin/analyst-kit-preamble" ] && "$_AK/bin/analyst-kit-preamble" --skill finmind --env FINMIND_TOKEN 2>/dev/null || echo "AK_CORE: not found (continue without runtime)"

Read the echoed state and act. Skip ALL bullets below if DEDUP: yes or AK_CORE: not found:

• DISABLED: yes → this skill is turned off because a required API key isn't configured. Do not run it. Tell the user it's off, name the missing key (see MISSING_KEYS), and offer to enable it — either they give you the key now (store it with "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>, which re-enables the skill) or they say "set up analyst-kit" for full setup. Then stop; do not attempt the skill's work.
• First run — ONBOARDED: no → orient the user once, then run "$_AK/bin/analyst-kit-setup" finish (this covers the telemetry notice, so skip the TEL_PROMPTED bullet this turn):
  1. Data home — tell the user Analyst Kit keeps config, API keys, local usage analytics, and a learnings log together in one folder (default ~/.analyst-kit); offer to move it with "$_AK/bin/analyst-kit-setup" home <dir>.
  2. Telemetry (a notice, not a question) — usage telemetry is on by default: only skill name, duration, outcome, and version, tagged with a per-machine device id derived from the hardware/OS, never repo names, paths, tickers, or content; opt out anytime by asking to turn Analyst Kit telemetry off.
  3. Identity (name + email — required) — ask for the user's name and email, stating plainly the email is mandatory to use most features (SEC EDGAR's fair-access policy requires a real, reachable contact on every request). If they decline because they don't want the email-dependent skills, discover a fallback yourself (git config user.email, gh api user, …) and pass it with --fallback in step 5.
  4. Offer full setup — ask if they'd like to configure API keys for all skills now. If yes, Read "$_AK/references/intro.md" and follow it. If no, continue — you'll ask for a key only when a skill needs one.
  5. Run "$_AK/bin/analyst-kit-setup" finish --name "<name>" --email "<email>" (add --fallback for a discovered email; run plain finish only if no email could be found at all). If it echoes INVALID_EMAIL, re-ask and run it again.
• User asks to set up Analyst Kit at any time (e.g. "set up analyst-kit", "help me set up Analyst Kit", "configure all skills") → Read "$_AK/references/intro.md" and follow it end to end: data home, telemetry, every skill's keys, and enabling/disabling each.
• TEL_PROMPTED: no (returning user) → give the telemetry notice once, then run "$_AK/bin/analyst-kit-setup" ack-telemetry.
• If the user asks to turn telemetry off (now or anytime): before flipping it, make a sincere case once — telemetry is what tells the maintainers which skills break, which run slow, and where users get stuck, so keeping it on directly improves their experience; it never includes their data. Offer "$_AK/bin/analyst-kit-config" set telemetry anonymous (drops the device id) as a middle ground. If they still want out, run "$_AK/bin/analyst-kit-config" set telemetry off immediately and without further argument.
• Before running any script that needs an API key: source both the data home's .env and the current directory's .env into the shell so scripts can read stored keys: set -a; [ -f "$AK_HOME/.env" ] && . "$AK_HOME/.env"; [ -f "./.env" ] && . "./.env"; set +a (where $AK_HOME is the path printed on the AK_HOME: line above). Full lookup order — always check these before concluding a key is missing or asking the user:
  1. current shell environment
  2. $AK_HOME/.env (keys stored by analyst-kit-setup)
  3. .env in the current working directory Never ask the user for a key that is already present in any of these locations.
• MISSING_KEYS not none → for each listed key with KEY_PROMPTED_<KEY>: no: explain where to get it, ask for the value, and run "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>. If declined, run "$_AK/bin/analyst-kit-setup" skip-key <KEY> (this disables the skills that need it) and continue — never block the skill.
• UPGRADE: UPGRADE_AVAILABLE <old> <new> → say "Analyst Kit skills is available (you have ) — update?". If yes: Read "$_AK/references/upgrade.md" and follow it. If declined: run "$_AK/bin/analyst-kit-update-check" --snooze <new>.
• LEARNINGS entries shown → these are past mistakes/preferences for this user; respect them and do not repeat logged pitfalls.

Then proceed with the skill. At the very end, run the Completion block at the bottom of this file.

FinMind — Taiwan company data

FinMind serves Taiwan market data over a REST API. This skill wraps the most common operations in self-contained scripts, so the two dominant requests — download everything for a company and keep it updated — run without reading any reference file.

Setup

Requires a FinMind API token. Before running scripts, source it from the data home (the preamble prints AK_HOME:):

set -a; [ -f "$AK_HOME/.env" ] && . "$AK_HOME/.env"; [ -f "./.env" ] && . "./.env"; set +a

Free tier = 600 requests/hour — ample for per-company pulls. If FINMIND_TOKEN is still unset after sourcing $AK_HOME/.env and the current-directory .env, follow the preamble's MISSING_KEYS flow to ask the user (see preamble block above).

Common operations — just run the script (no reference reading needed)

Scripts are in scripts/. Output goes to scripts/../data/<data_id>/.

1 · Find a company's data_id

python scripts/find_company.py "台積電"     # Chinese name (substring ok)
python scripts/find_company.py 2330         # verify / echo an id

Prints matching stock_id + name + industry. FinMind stores Chinese names only — an English query like "TSMC" won't match, so resolve to the id first.

2 · Download a company's full history

python scripts/download_company.py 2330                  # full history
python scripts/download_company.py 2330 --start 2015-01-01

Pulls price, valuation (PER/PBR), monthly revenue, financial statements, balance sheet, cash flows, dividends, shareholding, institutional flows, and margin — one CSV per dataset — plus a derived market_cap.csv and metadata.json. (Company news is single-day only and not bulk-pullable; query it ad-hoc per references/usage.md.)

3 · Keep a company's data updated

python scripts/update_company.py 2330

Incrementally fetches only rows newer than what's stored (idempotent), refreshing especially monthly revenue, share counts, stock price, and market cap. Run download_company.py first.

Output layout

data/<data_id>/
  TaiwanStockPrice.csv   TaiwanStockMonthRevenue.csv   TaiwanStockShareholding.csv   ...
  market_cap.csv         # date, close, shares_issued, market_cap
  metadata.json          # stock_name, updated_at, per-dataset rows + min/max date

Market cap note

FinMind's direct market-cap dataset (TaiwanStockMarketValue) requires a paid tier. On the free tier the scripts compute market_cap = close × NumberOfSharesIssued (shares from TaiwanStockShareholding) into market_cap.csv.

Custom / ad-hoc queries (read references only when needed)

For anything beyond the three operations above — a specific dataset, column meanings, tier requirements, intraday / derivatives / macro data — consult:

• references/datasets.md — full catalog: every dataset, its columns, and tier requirements.
• references/usage.md — API mechanics: endpoints, params, error handling, rate limits, the long-format note for financial statements.

scripts/finmind_client.py exposes reusable helpers (fetch, fetch_df, DATASETS, compute_market_cap) — import it for custom pulls instead of re-implementing the HTTP call.

Tests

tests/test_finmind.py exercises real companies (e.g. 2330) end-to-end. They hit the live API and are skipped automatically when FINMIND_TOKEN is unset:

export FINMIND_TOKEN="your_token"
pytest tests -q

Completion (run last)

Audit before you deliver. If this run produced a research deliverable carrying quantitative or factual claims — a deep dive, thematic/value-chain map, technical call, company wiki, or financial model — you MUST verify it before presenting it. If a research-auditor subagent is available (the analyst-kit plugin ships one), invoke it via the Task tool, handing it the draft and the data artifacts you used; on a runtime without subagents, run the same checks yourself. Resolve every CRITICAL finding and disclose any UNVERIFIED ones; never deliver on a FAIL verdict without fixing it first. Skip this only for pure data-fetch/utility runs with no analytical claims.

PLAN MODE EXCEPTION — ALWAYS RUN: writes only to ~/.analyst-kit/. Replace OUTCOME with one of DONE | DONE_WITH_CONCERNS | ERROR | ABORT | NEEDS_CONTEXT.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
[ -x "$_AK/bin/analyst-kit-log" ] && "$_AK/bin/analyst-kit-log" end --skill finmind --outcome OUTCOME 2>/dev/null || true

If this session surfaced a durable pattern, pitfall, or user preference that would save 5+ minutes next time (not obvious, not a transient error), also log it:

"$_AK/bin/analyst-kit-learn" add '{"skill":"finmind","type":"pitfall|pattern|preference","ticker":"<optional>","insight":"<one line>","confidence":7,"ts":"<iso8601 utc>"}'