13f-analysis

name	13f-analysis
type	capability
description	Fetch and read U.S. institutional 13F-HR filings (quarterly long-equity holdings) for any fund manager from SEC EDGAR — free, no API key. Resolve a fund to its filing entity (CIK), pull the latest or a historical quarter's holdings as a ranked CSV with values normalized to whole dollars and positions rolled up by issuer, and interpret them without the common traps. Triggers: "get the 13F for X", "latest 13F holdings of Y", "what does <fund> own", "pull <manager>'s 13F", "find the CIK for <fund>", "who filed this 13F", "13F analysis of Z".
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 13f-analysis 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.

13F analysis — institutional holdings from SEC EDGAR

13F-HR is the quarterly filing where large U.S. managers (≥ $100M) disclose their long positions in U.S.-listed equities. SEC EDGAR is the free, authoritative source — no API key, no account. This skill wraps the two dominant requests — find a fund's filing entity and pull its holdings — into self-contained scripts that run without reading any reference file.

Setup

• Runtime: Python 3 (standard library only — no pip install, no key).
• Be a good citizen: SEC's fair-access policy asks for a User-Agent that identifies you with a contact email. Set one (optional; a default is built in):

  export SEC_EDGAR_UA="your-app your-name [e-mail]"
  

  Stay under ~10 requests/sec (the scripts self-throttle).

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

Scripts are in scripts/. Run them from there (they import edgar.py).

1 · Simplest path — get a fund's latest 13F by CIK

The most reliable input is the CIK. Verified CIKs for a roster of well-known funds are in references/known-funds.md.

python fetch_13f.py 0001067983          # Berkshire Hathaway — latest quarter

Prints a ranked holdings table and writes 13f-output/<filer>_<period>.csv (rank, issuer, CUSIP, value_usd, % of portfolio, shares, derivative flag). Values are normalized to whole dollars and rolled up by issuer.

2 · Don't know the registered name? Search for the filer

python find_fund.py "pershing square"   # -> CIK + registered name + latest 13F
python find_fund.py "tiger"             # broad term -> lists every match

Searches by filer name (the right way — see the note below), then feed the CIK it prints to fetch_13f.py. You can also pass a name straight to fetch_13f.py "Pershing Square Capital Management"; if the name is ambiguous it lists the candidate CIKs and asks you to pick one.

Why filer-name search, not full-text search? EDGAR full-text search matches the contents of filings. A manager whose name is also a popular holding (e.g. "Berkshire Hathaway") will return every fund that holds it, not the filer. find_fund.py uses the filer-name index and avoids that trap. Caveat: it prefix-matches the firm name — search "Duquesne", not "Druckenmiller".

3 · A specific past quarter (e.g. to diff quarter-over-quarter)

python fetch_13f.py 0001067983 --period 2025-12-31

Pull two consecutive periods and compare share counts to see new buys, adds, trims, and exits — that change is where the real signal is (not the dollar value, which also moves with price).

Output layout

13f-output/
  BERKSHIRE_HATHAWAY_INC_2026-03-31.csv   # ranked, normalized, rolled-up holdings
  ...                                     # one CSV per fund/period

Reading the results correctly — don't skip this

A 13F is a delayed (≤45 days), long-only, U.S.-equity, self-reported snapshot. Before drawing conclusions, read references/reading-13f.md. The two mistakes that most often produce wrong conclusions:

1. The data is not clean / not guaranteed accurate. Unit confusion (values in thousands vs. whole dollars), fat-finger share counts, bad CUSIPs, and superseding amendments are all common. fetch_13f.py auto-detects and normalizes units (and flags when it does) — but still sanity-check outliers (value ÷ shares should ≈ the real share price).
2. It shows only longs — no shorts, no hedges. No short positions, cash, bonds, FX, commodities, foreign-listed shares, or private holdings. And long puts/calls are included but invert the meaning — a Put row (see the derivative column) is usually bearish/a hedge. So a 13F can badly misrepresent a hedged or macro fund's true book; it's far more reliable for concentrated long-only managers.

References (read only when you need them)

• references/known-funds.md — verified CIKs and direct EDGAR links for a roster of well-known funds (Berkshire, Pershing, Duquesne, Appaloosa, Third Point, Trian, Fairholme, Greenlight/DME, Icahn, Baupost, TCI, Viking, Tiger Global, Himalaya, Coatue, Lone Pine, Praetorian), plus the entity-resolution traps (e.g. Greenlight files under DME Capital; Kuppy under Praetorian PR; Citrini files no 13F).
• references/reading-13f.md — how to read the information table and the full list of mistakes to avoid.

scripts/edgar.py exposes reusable helpers (resolve_cik, find_filers, latest_13f, parse_infotable, aggregate, submissions_summary) — import them for custom pulls (cross-fund overlap, quarter-over-quarter diffs) instead of re-implementing the HTTP and XML parsing.

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 13f-analysis --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":"13f-analysis","type":"pitfall|pattern|preference","ticker":"<optional>","insight":"<one line>","confidence":7,"ts":"<iso8601 utc>"}'