sec-filings

name	sec-filings
type	capability
description	Fetch and read U.S. SEC filings (10-K, 10-Q, 8-K, and any EDGAR form) for any public company — free, no API key — and extract the information that only lives inside filings: declared risk factors, MD&A, material events, segment data, insider transactions, and quarterly earnings press releases / shareholder letters (filed as 8-K exhibits, EX-99.1 or EX-99.2 — the authoritative source for non-GAAP KPIs like bookings, DAUs, and ARR that fundamentals APIs don't carry; one command lists the exhibit URLs for N quarters of earnings 8-Ks). Resolve a ticker to its filing entity (CIK), list filings by form, date, and 8-K item code, batch-list exhibits, and — for large filings — index the document and BM25-search it down to the few relevant sections, then extract from those sections with cheap sub-agents. Fetches are User-Agent-compliant by construction, so the common EDGAR 403 (and the WebFetch trap) never happen. Triggers: "get the 10-K for X", "latest 10-Q / annual report for Y", "any recent 8-K for Z", "material disclosures / recent filings for <company>", "what risks does <company> declare", "risk factors / MD&A from the latest 10-K", "what does <company>'s 10-K say about <topic>", "find the section on <topic> in <company>'s filing", "show <company>'s SEC filings", "did <company> file anything this week", "insider transactions for <ticker>", "earnings press release / shareholder letter for X", "quarterly bookings / DAU / KPI history for Y", "8-K exhibit / EX-99.1 for Z", "fetch a sec.gov URL without a 403".
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 sec-filings 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.

SEC filings — fetch & read from EDGAR

This skill answers four families of request, all backed by SEC EDGAR (the authoritative U.S. filing system — free, no API key, no account):

1. Explicit filing requests — "get the latest 10-K / 10-Q / 8-K for X."
2. Recent material disclosures — "did anything material happen at X lately?" (almost always an 8-K, occasionally a 10-Q/10-K item).
3. Information that only exists inside filings — declared risk factors, MD&A, segment breakdowns, legal proceedings, going-concern language, insider trading. This data is not in price/fundamentals APIs; you must read the filing.
4. Question-answering over a large filing — "what does the 10-K say about ?" A 10-K is 300+ pages; you cannot read it whole. Use the two-step parse pipeline (below) to find and read only the sections that matter.

Out of scope: 13F institutional-holdings filings have a dedicated skill (13f-analysis) — route "what does own", "latest 13F", "fund holdings" there. This skill is for corporate disclosure forms (10-K/10-Q/8-K, etc.) and insider Forms 3/4/5.

---

⛔ The one rule that prevents every "it doesn't work": how to fetch

Never fetch a *.sec.gov or efts.sec.gov URL with the WebFetch tool, and never with a bare curl. SEC's fair-access policy rejects any request without a User-Agent that names a contact — you get HTTP 403, every time. WebFetch cannot set that header, so it always 403s on SEC. This is the #1 reason naive attempts fail.

Instead, every SEC request goes through the bundled scripts, which always send the required header:

# from skills/sec-filings/scripts/  (Python 3, standard library only — no pip, no key)
python edgar.py cik AAPL                 # ticker -> CIK + title   (verified 200)
python edgar.py filings AAPL 10-K -n 5   # list filings of a form, newest first
python edgar.py doc AAPL 10-K            # primary-document URL of the latest 10-K

If you ever must hand-fetch, set the header yourself: curl -H "User-Agent: your-app [e-mail]" "https://data.sec.gov/...".

• Contact string: override the built-in default via export SEC_EDGAR_UA="your-app your-name [e-mail]" (optional — a valid default ships, so no .env key is required and this skill declares no env:).
• Rate limit: stay under ~10 req/sec. The scripts self-throttle (a short sleep per call); still self-pace on bulk pulls.

---

The two-step parse pipeline (for reading large filings)

A 10-K/10-Q is far too large to read into context, and "paginate the whole thing" buries the answer in boilerplate. Split the job:

Step 1 — index & BM25-search to find the right sections (scripts/parse_filing.py). It fetches the primary document (UA-compliant), strips the iXBRL/HTML to clean prose (keeping visible inline facts, dropping the hidden ix:header metadata), chunks it into section-sized windows tagged with their Item label, and ranks chunks against your query with pure-Python Okapi BM25 (no embeddings, no network, no LLM — deterministic and dependency-free). It writes the top sections to small files for step 2.

Why this is the token-efficiency play (measured on Apple's FY2025 10-K): raw iXBRL HTML is 441,509 tokens; the strip alone → 44,274 tokens (10×); the top-5 BM25 sections for one query → ~6,000 tokens (73× vs raw). The strip wins by deleting iXBRL plumbing (hidden ix:header facts, scripts, styles), not by rendering tables — so for numbers, use the XBRL facts API (Scenario 3), not the stripped text. Full converter decision + landscape: references/sec-xbrl-and-attachments.md.

# from skills/sec-filings/scripts/
python parse_filing.py AAPL --form 10-K \
    --query "supply chain concentration and single-source suppliers risk" --top 5
# -> writes sec-output/<accession>/sec_01.txt … sec_NN.txt  + results.json
#    and prints a ranked table with the Item label and a snippet per section.

# BM25 is lexical — REPEAT --query with 2-4 rephrasings; results are rank-fused
# (RRF), so a section that any one phrasing finds still surfaces. One pass, same cost:
python parse_filing.py AAPL --form 10-K --top 5 \
    --query "supply chain concentration single-source suppliers" \
    --query "manufacturing outsourcing partners dependence" \
    --query "component shortages supplier risk"

python parse_filing.py AAPL --accession 0000320193-25-000079 --query "segment revenue"
python parse_filing.py --url https://www.sec.gov/Archives/.../aapl-20250927.htm --query "MD&A liquidity"
python parse_filing.py AAPL --form 10-K          # no --query -> print the section map only

Step 2 — extract the precise answer with a cheap Haiku sub-agent per section. Each sec_NN.txt is ~6 KB (one section). For each top section, spawn a sub-agent pinned to the cheapest model, claude-haiku-4-5, scoped to that one section. This is cheap, parallel, and accurate — and it keeps the 300-page filing out of your context.

In Claude Code, use the Task/Agent tool with model: haiku, one per section file, e.g.:

Spawn (model claude-haiku-4-5): "You are reading one section of <COMPANY>'s <FORM> (file: sec-output/<acc>/sec_03.txt). Read it, then answer only from that text: <the user's question>. Quote the exact sentence(s) and cite the Item number. If the answer is not in this section, reply exactly NOT IN THIS SECTION."

Run them in parallel, drop the NOT IN THIS SECTION replies, and synthesize the surviving answers into one response, citing Item + filing date. (Portability note: if the host has no sub-agent tool — e.g. Codex — just read the top 1–2 sec_NN.txt files directly. The win is the same: BM25 already narrowed 300 pages to the right 6 KB.)

Why this shape? BM25 is the right tool for "find the section" (keywords, names, defined terms — exactly how filings are written), and Haiku is the right tool for "read this one section and answer" (cheapest model, tiny input). Splitting them keeps the whole thing fast, cheap, and free of any external indexer or embedding service.

---

Step 0 — Resolve the company to a CIK (every path starts here)

EDGAR is keyed by CIK (Central Index Key), not ticker. edgar.py does this for you (python edgar.py cik <ticker>, or resolve_cik() in code). Identity edge cases it already handles — and that bite if you resolve by hand:

• Dotted tickers are stored dash-form. BRK.B is listed as BRK-B — normalize . → -. (Verified: BRK.B → Berkshire CIK 0001067983.)
• Multi-class tickers share one CIK. GOOGL and GOOG both map to 1652044 — the company files once; the share class is not a separate filer.
• Padding matters. data.sec.gov 404s on an unpadded CIK in the path; pad to 10 (320193 → CIK0000320193). edgar.py pads automatically; the efts full-text API accepts unpadded CIKs.
• Not found: a bogus CIK returns HTTP 404.

---

Scenario 1 — "Get the 10-K / 10-Q / 8-K for X"

python edgar.py filings AAPL 10-K -n 5     # newest-first; exact-form match
python edgar.py doc AAPL 10-K              # -> the primary-document URL

Under the hood the submissions feed (data.sec.gov/submissions/CIK….json) is the spine: filings.recent is column-oriented (parallel arrays zipped by index — edgar.py does the zipping). To read or QA the document, hand its URL to parse_filing.py (above) rather than fetching it raw — that gets you the search pipeline for free.

Form cheat-sheet: 10-K = annual; 10-Q = quarterly; 8-K = current (material event); /A suffix = amendment (10-K/A); 20-F/40-F = foreign annual; DEF 14A = proxy; 4 = insider transaction. Form matching is exact and case/space-sensitive ("10-K" must not match "10-K/A"; "DEF 14A" has a space).

The 1000-filing recent cap: filings.recent holds at most ~1000 filings; older history lives in overflow files. Pass --history to edgar.py filings (or include_history=True) to walk them. If you only read recent, you silently miss anything older — for an active filer that can be < 1 year.

---

Scenario 2 — "Recent material disclosures / did anything material happen?"

Material events are Form 8-K, usually filed within 4 business days. Each 8-K carries one or more item codes (in the items column) that classify the event — the fastest materiality triage without reading prose.

python edgar.py filings AAPL 8-K -n 10     # the `items=` field decodes via the table below

Item	Meaning	Why it's material
1.01 / 1.02	Entry into / termination of a material agreement	M&A, big contracts
2.01	Completion of acquisition or disposition	Deal closed
2.02	Results of operations (earnings release)	Quarterly numbers
2.03 / 2.04	New debt / triggering of debt acceleration	Leverage, covenant breach
3.01	Delisting / failure to satisfy listing rule	Going-concern signal
4.01 / 4.02	Auditor change / non-reliance on prior financials	Restatement red flag
5.01	Change in control
5.02	Departure/appointment of directors or officers	CEO/CFO change
7.01 / 8.01	Reg FD disclosure / Other events	Catch-all
9.01	Financial statements & exhibits	Almost always present (the attachments)

Worked example (verified): AAPL's latest 8-K had items = "2.02,9.01" → an earnings release (2.02) with exhibits (9.01).

Read the 8-K and its attachments. An 8-K is a bundle: the cover-page .htm plus exhibits. List them, then read the right one:

python edgar.py exhibits    AAPL 8-K   # just the exhibit URLs, labeled (EX-99.1, EX-99.2, …)
python edgar.py attachments AAPL 8-K   # the whole accession folder, incl. XBRL members
python edgar.py cover       AAPL 8-K   # the dei cover-page facts (an 8-K's ONLY XBRL)

• On an Item 2.02 earnings 8-K, the numbers live in EX-99.1 or EX-99.2 — some companies (e.g. Roblox) file the press release as 99.1 and the shareholder letter that carries the KPI tables as 99.2 (verified). List both and pick by content, never by number alone. The tables are plain HTML, not XBRL (verified): feed the exhibit URL to parse_filing.py --url ….
• ⛔ Never construct an exhibit URL from a guessed filename. Exhibit names are arbitrary and era-dependent (ex991-q12026earningsshar.htm, q225shletterex992.htm, a05-09330pmq123sharehold.htm are all real Roblox exhibits). A 404 on a hand-built URL means list the folder (exhibits --accession <acc>) — it is never a reason to fall back to WebFetch (sec.gov 403s it).
• python edgar.py cover extracts the cover-page XBRL — but note an 8-K has no financial XBRL, only dei: cover facts (document type, period, registrant, item flags, registered securities). Don't expect an income statement from filing.xbrl() on an 8-K.

(When the MCP server is connected, analyze_8k decodes items into described events — see Optional accelerator below.) Full details: references/sec-xbrl-and-attachments.md.

---

Scenario 2b — a KPI time series from earnings releases (bookings, DAUs, ARR, …)

Non-GAAP KPIs are not in any fundamentals API and not in XBRL — they only exist in the quarterly earnings exhibits. Getting "metric X for the last N quarters" is a three-step batch job, not N rounds of discovery:

1. One call for every exhibit URL (item 2.02 = earnings release):

python edgar.py exhibits RBLX 8-K --items 2.02 -n 17   # one labeled EX-99.x URL set per quarter

2. BM25-narrow each exhibit to the sections that carry the metric (each quarterly release restates the year-ago figure, so every other quarter is enough when budget-bound). Use 2–3 query phrasings — companies move KPIs between a "highlights" block, a "reconciliation" table, and a "key metrics" table across quarters, and one phrasing won't match all eras:

python parse_filing.py --url <exhibit-url> \
    --query "<metric> three months ended" \
    --query "reconciliation of revenue to <metric>" \
    --query "key metrics highlights <metric> growth"
# -> sec-output/<slug>/sec_01.txt … (one section each, ~6 KB, rank-fused across queries)

3. Extract with a Haiku sub-agent per section — do NOT read the sections yourself. Reading sec_NN.txt files in your own context burns premium-model tokens on table boilerplate; this is exactly Step 2 of the parse pipeline (above). Spawn one sub-agent (model claude-haiku-4-5) per exhibit, e.g.:

Spawn (model claude-haiku-4-5): "Read the section files sec-output/<slug>/sec_0*.txt from <COMPANY>'s <period> earnings exhibit. Return ONLY a JSON object {"period": "YYYY-MM-DD", "<metric>": <absolute USD number>} using the three-months-ended column (not six/nine-months YTD). Use null if absent — never guess."

Run them in parallel and assemble the array. The YTD-column trap is the #1 wrong-answer source here: shareholder letters print "Three Months Ended" next to "Six Months Ended" — the sub-agent prompt must pin the column.

This is the highest-value case, and exactly what the parse pipeline is for:

1. python parse_filing.py <ticker> --form 10-K --query "<topic>" --query "<rephrasing>" → top sections (repeat --query 2–4× with different vocabulary; rank-fused).
2. Haiku sub-agent per section → precise, quoted answer (Step 2 above).

Where the topic maps in a 10-K/10-Q (useful as a query hint or to read the section map):

• Risk Factors = 10-K Item 1A (updates in 10-Q Part II Item 1A)
• MD&A = Item 7 (10-K) / Part I Item 2 (10-Q)
• Business = Item 1; Legal Proceedings = Item 3 / Part II Item 1

Full-text search across all filers (you don't know which filing) — efts.sec.gov, fetched via edgar.http_get (UA-compliant), not WebFetch:

https://efts.sec.gov/LATEST/search-index?q=%22material+weakness%22&forms=8-K&startdt=2024-01-01&enddt=2024-03-31

Returns Elasticsearch-shaped JSON: hits.total.value (capped at 10000 when relation:"gte"), hits.hits[] (100/page; paginate &from=100), each _source with display_names, form, file_date, items, ciks; _id = "{accession}:{filename}". Verified gotchas: the params are startdt/enddt (there is no dateRange=custom — it returns HTTP 500); full-text search only covers filings 2001-present.

Structured financials (XBRL): for numbers (revenue, segments, EPS) rather than prose, use SEC's pre-computed facts API — it has already applied scale/sign/units, so you skip the iXBRL parsing traps:

python edgar.py facts   AAPL --grep Revenue   # DISCOVER the company's real tags first
python edgar.py concept AAPL RevenueFromContractWithCustomerExcludingAssessedTax

Trap (verified): the GAAP tag for revenue is company-specific — Apple's is RevenueFromContractWithCustomerExcludingAssessedTax (113 facts) and SalesRevenueNet (210), while Revenues has just 11 stale facts. Discover, never hardcode. And the same concept returns both YTD and quarter facts for one period-end — disambiguate by the context's period length, not just the end date. Details + the full gotcha catalog (scale, sign, nil, dimensions): references/sec-xbrl-and-attachments.md.

---

The big edge cases (the ones that silently produce wrong answers)

1. 403 without a User-Agent — and WebFetch can't send one. Use the scripts. (Verified.)
2. The 1000-filing recent cap. Older history needs the overflow files (--history).
3. Form matching is exact and case/space-sensitive ("10-K" != "10-K/A").
4. filingDate vs reportDate vs acceptanceDateTime. filingDate = when filed; reportDate = the period covered (the one you usually want for "Q3 2024"); acceptanceDateTime = exact timestamp (use for "today's filings").
5. iXBRL hidden facts. Modern filings embed machine-only facts in a hidden ix:header/display:none block; parse_filing.py drops these but keeps the visible inline facts (ix:nonFraction/ix:nonNumeric). Don't index the raw HTML yourself.
6. XBRL tag drift. Same concept, different tags across companies/years. Discover, don't assume.
7. No automatic rate limiting beyond the scripts' per-call sleep. Self-throttle on bulk.
8. Exhibit filenames are arbitrary — never build one from a pattern; list them (edgar.py exhibits). And the earnings exhibit may be EX-99.1 or EX-99.2.

Full, verified catalog: references/sec-edgar-direct-http.md.

---

Optional accelerator — the sec-edgar-mcp MCP server

If (and only if) the sec-edgar-mcp server is connected, it offers ergonomic conveniences: get_company_info, get_recent_filings, analyze_8k (decodes item codes into events), get_filing_sections, get_insider_transactions, XBRL helpers. Use it opportunistically for those conveniences — but it is not required and not the spine:

• It needs the user to have configured the server with SEC_EDGAR_USER_AGENT (in the MCP launch config; the server refuses to start without it). That setup step is exactly what makes it unreliable in practice.
• The bundled scripts are always available and need no setup, so they are the default path. Treat MCP as a speedup when present; verify or fall back to the scripts.

Full tool inventory: references/sec-edgar-mcp-tools.md.

---

References

• references/sec-edgar-direct-http.md — the raw HTTP layer the scripts are built on: every endpoint on data.sec.gov, www.sec.gov/Archives, and efts.sec.gov, with verified request/response shapes and the exhaustive edge-case catalog.
• references/sec-xbrl-and-attachments.md — filing→text conversion decision (with measured token wins + the converter landscape), the accession-folder/exhibit map, the verified "8-K = dei cover page only, EX-99.1 = plain HTML" finding, the dei taxonomy, the facts-API-vs-raw-instance call, and the XBRL parsing gotchas (scale/sign/nil/contexts/dims).
• references/sec-edgar-mcp-tools.md — complete inventory of the optional MCP tools (names, parameters, return shapes, the SEC endpoint each maps to).

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