| 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):
- 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>.
- 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.
- 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.
- 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.
- 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:
- current shell environment
$AK_HOME/.env (keys stored by analyst-kit-setup).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 "台積電"
python scripts/find_company.py 2330
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
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>"}'
