| name | analyst-kit-core |
| type | capability |
| description | Shared runtime for Analyst Kit skills: the ~/.analyst-kit data home, config store, local usage analytics with opt-in telemetry, daily update checks, and a per-user learnings log every skill reads and appends to. Loaded automatically as a dependency of every other skill. Triggers: "set up analyst-kit", "help me set up Analyst Kit", "configure all skills", "analyst-kit config", "enable/disable a skill", "check for analyst-kit updates", "upgrade analyst-kit skills", "show my analyst-kit learnings", "turn analyst-kit telemetry on/off", "show my analyst-kit usage".
|
Analyst Kit Core — shared runtime
Every Analyst Kit skill depends on this one. Skills run the Preamble block at start and the
Completion block at end (both injected by scripts/sync-preamble.js in the source
repo); this file documents the machinery behind those blocks, and is what you should
read when the user explicitly asks about Analyst Kit setup, config, telemetry, updates, usage,
or learnings.
The ~/.analyst-kit/ data home
Default per-user location for everything Analyst Kit persists. Resolution order:
explicit $AK_HOME → the ~/.analyst-kit/home-path pointer (written when the user relocates
their data during onboarding) → ~/.analyst-kit. ~/.analyst-kit always remains as a fixed bootstrap
that holds the core-path / home-path pointers even after the data is relocated:
| Path | Purpose |
|---|
config | key=value settings (analyst-kit-config get/set/list) |
.env | API keys (FMP_API_KEY=...), chmod 600, shared across projects |
device-id | stable anonymous id, created only for community telemetry |
analytics/skill-usage.jsonl | local usage log: start/end events with outcome + duration |
analytics/.pending-* | open-session markers; stale ones finalize as CRASH |
sessions/ | per-agent-session dedupe markers (one prompt round per session) |
learnings.jsonl | per-user learnings log (patterns / pitfalls / preferences) |
last-update-check, update-snoozed | update-check cache (1 day) and snooze (7 days) |
.onboarded, .telemetry-prompted, .env-prompted-<KEY> | once-ever prompt markers |
disabled | skill names turned off because a required API key is missing/declined |
core-path | (bootstrap) cached location of this skill on disk |
home-path | (bootstrap) absolute path to the relocated data home, if the user moved it |
install-manifest.jsonl | what analyst-kit install installed (drives guided upgrades) |
Scripts (bin/)
analyst-kit-config get <key> | set <key> <value> | list — config store. Defaults:
telemetry=off, update_check=true. Optional: posthog_key, posthog_host.analyst-kit-preamble --skill <name> [--env K1,K2] — echoes DEDUP, AK_VERSION,
TELEMETRY, TEL_PROMPTED, ONBOARDED, MISSING_KEYS (+ per-key
KEY_PROMPTED_*), UPGRADE, LEARNINGS, then logs the start event.analyst-kit-log start|end --skill <name> [--outcome <O>] — appends local JSONL events and,
when telemetry is on, fires the remote event in the background.analyst-kit-update-check [--force | --snooze <version>] — prints
UPGRADE_AVAILABLE <local> <remote> or nothing. Max one network fetch per day,
curl --max-time 3.analyst-kit-learn add '<one-line-json>' | recent [--skill S] [--topic T] [--limit N] —
learnings log.analyst-kit-setup status | home <dir> | set-key <K> <V> | skip-key <K> | disable <skill> | enable <skill> | reconcile | ack-telemetry | finish
— onboarding + setup backend. status reports the data home, which installed skills need
which API keys, and each skill's enable/disable state; home relocates the ~/.analyst-kit data
home (migrating data + writing the home-path pointer); set-key writes a key (and
re-enables any now-complete skill); skip-key records a decline (and disables the skills
that need that key); disable/enable toggle a skill; reconcile enables every skill
whose keys are all present and disables the rest; finish writes the onboarding +
telemetry markers. Non-interactive by design — the agent drives the conversation and
calls these to persist. _analyst-kit-home.sh (sourced by every script) resolves the data home;
references/api-keys.tsv maps each key to a description + signup URL; the full setup
playbook the agent follows lives in references/intro.md.
All scripts are defensive: they never exit non-zero from the skill's point of view,
never block on the network, and a total failure of this runtime must never stop a
skill from doing its actual job.
Full setup & disabling skills
When the user asks to set up Analyst Kit (e.g. "set up analyst-kit", "help me set up Analyst Kit",
"configure all skills"), Read references/intro.md and follow it — it walks the data
home, the telemetry notice, and every installed skill's API keys in one pass. (A
single skill's preamble, by contrast, only handles that one skill's key on demand — the
lazy path.)
A skill whose required key the user doesn't provide is disabled: its name is recorded
in ~/.analyst-kit/disabled, its preamble then echoes DISABLED: yes, and the agent must refuse
to run it and point the user at "set up analyst-kit" (or simply accept the key, which re-enables it
via analyst-kit-setup set-key). This is a soft disable — channel-agnostic and reversible, with
no file surgery on installed skills — so it behaves identically across the plugin,
installer, and codex channels (the install-time routing table still lists the skill; the
runtime preamble is what gates it).
Telemetry tiers
Local analytics/skill-usage.jsonl is always written — it is the user's own machine
and powers crash detection and usage review. The remote leg (PostHog) is gated by
analyst-kit-config get telemetry:
community (default) — {skill, version, outcome, duration_s, platform} plus a
stable random device-id so usage counts deduplicate.anonymous — same event, no identifier of any kind.off — nothing leaves the machine.
Telemetry is on by default with explicit opt-out. Remote events never include
repo names, file paths, tickers, file content, or API keys. The local log records a
sanitized repo slug for the user's own reference; it is never uploaded.
When the user asks to opt out: make a sincere case once before changing anything —
telemetry is what tells the maintainers which skills break, which run slow, and where
users get stuck, so keeping it on directly improves their own experience, and it never
contains their data. Offer anonymous as a middle ground. If they still want out, run
analyst-kit-config set telemetry off immediately and respect the decision — never re-litigate
it in later sessions.
Completion statuses
Every skill ends its Completion block with one outcome:
DONE | DONE_WITH_CONCERNS | ERROR | ABORT | NEEDS_CONTEXT.
Report the same status to the user honestly — DONE_WITH_CONCERNS lists the concerns.
Learnings protocol
Log with analyst-kit-learn add only durable discoveries that would save 5+ minutes in a
future session: a data-source quirk, a per-user preference, a pitfall that produced a
wrong number. Types: pattern (reusable approach), pitfall (what not to do),
preference (user stated). Include "ticker" or "topic" when the learning is
scoped, "confidence" 1–10 (user-stated preference = 10; verified observation = 8–9;
inference = 4–5), and an ISO-8601 "ts". Never log obvious facts, one-time transient
errors, or anything secret. The preamble surfaces recent relevant entries — treat them
as ground truth about this user unless contradicted in-session.
Upgrades
The preamble surfaces UPGRADE_AVAILABLE <old> <new> at most once per day, snoozed
7 days on decline. The guided flow lives in references/upgrade.md (plugin channel →
/plugin marketplace update; installer channel → fetch GitHub tarball, re-run
node bin/analyst-kit.js install for everything in install-manifest.jsonl).
