What the skill tells Claude

This is the skill's instruction file, SKILL.md, as Claude reads it.

Overview

This skill provides comprehensive access to SEC EDGAR database for retrieving and analyzing: - 13F-HR Filings: Institutional investment holdings reports (quarterly) - 10-K/10-Q Filings: Annual and quarterly financial statements with XBRL data - CUSIP-to-Ticker Mapping: Automatic ticker symbol resolution for holdings - Financial Statement Extraction: Income statements, balance sheets, and cash flow statements - Section Extraction: Systematically extracts Item 1 (Business), Item 1A (Risk Factors), Item 7 (MD&A), and Item 8 (Financials)

Use this skill when you need to: - Analyze institutional investor portfolios and holdings - Track changes in investment positions over time - Extract financial statements and metrics from company filings - Perform fundamental analysis using official SEC data - Research holdings across multiple quarters or years

Prerequisites

The skill uses the edgartools Python library and requires: - A user agent identifier ("Name (email)") for SEC API compliance - resolved as described in SEC Identity (Required) below - Company/fund identifier (ticker, fund name, investor name, or CIK) - CUSIP_Ticker.csv mapping file (included in skill package)

NEW: Smart CIK Lookup System You can reference companies and funds using natural identifiers: - Ticker symbols: "AAPL", "MSFT", "BRK-B" (12,000+ mappings) - Fund names: "Berkshire", "Citadel", "Bridgewater" (50+ top funds) - Investor names: "Warren Buffett", "Ray Dalio", "Ken Griffin" - Direct CIKs: "0001067983" (automatic padding if needed)

No need to remember CIK numbers! See references/cik_lookup_guide.md for complete lookup documentation.

Validation & Testing

✅ Production Ready: This skill has been comprehensively tested and validated on real SEC filings.

Test Coverage: - ✅ 10-K extraction: Apple (AAPL), Tesla (TSLA) - 100% success rate - ✅ 10-Q extraction: Microsoft (MSFT) - Risk factors extracted - ✅ Section extraction: Items 1, 1A, 7, 8 systematically isolated - ✅ Smart CIK lookup: Tickers, fund names, and pension plans resolved correctly - ✅ XBRL data: Financial statements extracted to CSV format

See examples/test_section_extraction.py for the complete validation suite.

How to Use

The user invokes:

/sec-edgar <filing type> <identifier> [options]

Interpret the input as: - Filing type: "13F", "10-K", "10-Q", or "holdings analysis" - Identifier: CIK (for 13F) or ticker symbol (for 10-K/10-Q) - Options: Number of periods, specific quarters, bulk operations

Examples: - /sec-edgar 13F holdings for Berkshire Hathaway - /sec-edgar Get latest 4 quarters of 10-Q for AAPL - /sec-edgar Analyze 13F filings for CIK 0001067983 - /sec-edgar Extract Item 1A from latest TSLA 10-K - /sec-edgar Get CalPERS 13F holdings

SEC Identity (Required)

The SEC requires every request to identify the requester ("Name (email)"). Resolve the identity in this order, and stop at the first that works:

  1. Provided in the request - the user gave a name and/or email in their message or earlier in the session.
  2. SEC_USER_AGENT environment variable - use its value as-is (format: Your Name (you@yourcompany.com)).
  3. Ask the user - if neither is available, stop and ask before making any SEC call, for example: "The SEC requires a contact name and email for EDGAR requests. What name and email should I use? (It is sent only to the SEC as a user-agent string.)"

Rules: - Never invent an identity or fall back to a placeholder such as your.email@example.com or contact@example.com. - If the user gives only an email, use it with a generic name such as "SEC EDGAR User (email)". - Reuse the identity for the rest of the session; do not ask again. - Pass it to EdgarLibrary("<identity>"), or to set_identity("<identity>") when using the scripts in scripts/edgartools/. - Do not echo the email back in reports or write it to output files.

Steps (STRICT)

For 13F-HR Holdings

  1. Parse Request: Extract identifier (ticker, fund name, investor name, or CIK) from user input
  2. Smart CIK Lookup: Use cik_lookup.smart_cik_lookup() to resolve identifier to 10-digit CIK
  3. Confirm Match: Show user the matched fund/company name for verification
  4. Initialize Library: Resolve the SEC identity (see SEC Identity (Required)), then create the EdgarLibrary instance with it
  5. Fetch Filings: Call get_13f_filings(cik, num_latest)
  6. Process Data: Library automatically aggregates, adjusts values, calculates prices, and maps tickers
  7. Save Output: Write holdings to CSV file named <FundName>_13f_holdings.csv
  8. Report Results: Summarize key holdings, total value, and top positions

For 10-K/10-Q Financials

  1. Parse and Validate: Extract ticker symbol and form type from user input
  2. Initialize Library: Resolve the SEC identity (see SEC Identity (Required)), then create the EdgarLibrary instance with it
  3. Fetch Filings: Call get_10kq_filings(ticker, form_name, num_latest)
  4. Extract Statements: Library retrieves income statement, balance sheet, and cash flow via XBRL
  5. Extract Sections: Use section_extractor.extract_sections() to systematically isolate: - Item 1: Business - Company operations, products, and strategy - Item 1A: Risk Factors - Comprehensive risk analysis - Item 7: Management's Discussion and Analysis - Performance and outlook - Item 8: Financial Statements - Audited financials with notes
  6. Save Output: Results saved to <form_name>/ directory: - Full filing markdown: <Ticker>_<FormType>_<Date>.md - Extracted sections: <Ticker>_<FormType>_item_<section>.txt - Financial statements: <Ticker>_<FormType>_<Statement>_<Date>.csv
  7. Report Results: Summarize key financial metrics, filing dates, and sections extracted with character counts

For Combined Analysis

  1. Fetch 13F Holdings: Get institutional positions using CIK
  2. Extract Tickers: Get unique ticker list from holdings (excluding "Not Found")
  3. Batch Fetch Financials: Call get_13f_filings_and_10q_for_holdings(cik, num_latest)
  4. Save All Data: Holdings CSV + individual 10-Q files per ticker
  5. Generate Summary: Cross-reference holdings with financial performance

Output Format (STRICT)

13F Holdings Output

File: <FundName>_13f_holdings.csv

Columns: - FundName: Institution name - as_of_date: Report date (YYYY-MM-DD) - Cusip: 9-character CUSIP identifier - Ticker: Stock symbol or "Not Found" - Issuer: Company name - Shares: Number of shares held - Value: Position value in USD - SharePrice: Calculated share price - Class, Type, InvestmentDiscretion, PutCall - SoleVoting, SharedVoting, NonVoting: Voting authority

Summary Report: - Total portfolio value - Number of positions - Top 10 holdings by value - Sector breakdown (if available) - Quarter-over-quarter changes

10-K/10-Q Output

Files Created: 1. <form_name>/<Ticker>_<FormType>_<Date>.md - Full filing text in markdown 2. <form_name>/<Ticker>_<FormType>_item_1_business.txt - Item 1: Business (operations, products, strategy) 3. <form_name>/<Ticker>_<FormType>_item_1a_risk.txt - Item 1A: Risk Factors (comprehensive risk analysis) 4. <form_name>/<Ticker>_<FormType>_item_7_mda.txt - Item 7: MD&A (performance analysis and outlook) 5. <form_name>/<Ticker>_<FormType>_item_8_financials.txt - Item 8: Financial Statements (audited data with notes) 6. <form_name>/<Ticker>_<FormType>_<Statement>_<Date>.csv - XBRL financial statements (Income, Balance, CashFlow)

Section File Format: Each extracted section includes: - Header with company name, ticker, and filing type - Character count for length awareness - Clean markdown formatting with preserved tables and structure - Section-specific content (typically 15-100KB per section)

CSV Structure (XBRL Financial Data): - Line item names (e.g., "Revenue", "Net Income", "Total Assets") - end_value: Most recent period value - begin_value: Previous period value
- end_date: End date of reporting period - begin_date: Start date of reporting period - Ticker: Stock symbol

Summary Report: - Filing metadata (date, form type, period covered) - Section extraction results with character counts - Revenue and earnings trends from XBRL data - Key balance sheet metrics - Cash flow highlights - Year-over-year or quarter-over-quarter changes

edgartools API & XBRL Reference

Beyond the EdgarLibrary workflows above (13F holdings, 10-K/10-Q bulk extraction, CIK lookup), this skill includes general edgartools coverage for any form type (10-K, 10-Q, 8-K, proxy, Form 4, etc.) and direct XBRL processing. Read the relevant guide before using these features.

Guides (references/edgartools/): - common-api-usage.md - Read first. Correct latest(), Company() and filing-method usage. - core-api.md - identity setup, company search and CIK lookup, retrieving and downloading filings, date-range queries, XML parsing, pandas analysis, common gotchas and a quick reference. - extracting-financial-statements.md - balance sheet, income statement and cash flow from any filing via xbrl().statements. - financial-statements.md - advanced statement analysis and parsing techniques. - xbrl-processing.md - direct XBRL processing (instance documents, taxonomies, facts) for advanced use.

Scripts (scripts/edgartools/): search_company.py, retrieve_filings.py, download_filing.py, parse_filing.py, xml_parsing_helper.py, financial_analysis.py, safe_financial_analysis.py, safe_numeric_formatting.py, get_10q_financials.py. These call set_identity(...) with a placeholder contact; always replace it with the identity resolved per SEC Identity (Required).

Which to use: for 13F holdings, ticker/fund-name lookup, CUSIP mapping and 10-K section extraction, use EdgarLibrary (above). For other form types, ad-hoc filings or raw XBRL, use the edgartools guides.

Constraints

  • CIK Lookup Coverage: 12,000+ ticker mappings, 50+ top institutional investors, 20+ pension plans
  • CIK Format: Automatically padded to 10 digits if needed (e.g., "1067983" → "0001067983")
  • Rate Limiting: SEC limits to 10 requests/second - batch operations handle automatically
  • User Agent Required: The SEC requires a real name and email on every request. Never use a placeholder; resolve it per SEC Identity (Required)
  • Ticker Validation: 1-5 uppercase alphanumeric characters (supports symbols like "BRK-B")
  • Historical Coverage: Not all companies have complete filing history
  • CUSIP Mapping: ~65,000 mappings included; some securities may show "Not Found"
  • Directory Creation: Skill creates 10-K/ and 10-Q/ directories for output
  • Memory Usage: Large bulk operations (100+ tickers) may require significant memory
  • Form Types: Only supports "10-K" and "10-Q" (case-insensitive)
  • Value Adjustment: Pre-Q3 2022 values automatically multiplied by 1000
  • Section Extraction: Optimized for 10-K filings; 10-Q structure differs (see references)
  • Section Size Limits: Each extracted section capped at 100KB to manage memory
  • Lookup Limitations: Not all companies/funds are in lookup tables - provide CIK directly if not found
  • Fuzzy Matching: Pension plan lookups use fuzzy matching with 80% similarity threshold

Error Handling

Invalid CIK: - Check format: digits only, max 10 characters - Add leading zeros if needed: "1067983" → "0001067983" - Raise InvalidCIKError with helpful message

Invalid Ticker: - Validate 1-5 alphanumeric pattern - Convert to uppercase automatically - Raise InvalidTickerError if format wrong

Filing Not Found: - Verify company exists in SEC database - Check CIK/ticker spelling - Suggest using SEC company search - Raise FilingNotFoundError with clear message

Missing XBRL Data: - Log warning for incomplete statements - Continue processing available data - Note missing sections in report

Data Processing Failures: - Catch and log all exceptions - Provide partial results when possible - Include error details in summary

Examples

Example 1: Recent Berkshire Hathaway 13F Holdings (Using Fund Name)

User: /sec-edgar Get the last 4 quarters of 13F holdings for Berkshire Hathaway

Expected workflow: 1. Smart Lookup: "Berkshire Hathaway" → Found: CIK 0001067983 (Warren Buffett) 2. Confirm: "Analyzing Berkshire Hathaway Inc. (Warren Buffett)" 3. Call edgar.get_13f_filings("0001067983", 4) 4. Save to BERKSHIRE HATHAWAY INC_13f_holdings.csv 5. Report: "Retrieved 4 quarters of holdings (Q4 2023 - Q3 2024). Portfolio contains 45 positions worth $350B. Top holdings: Apple ($150B), Bank of America ($35B), Coca-Cola ($25B)."

Alternative using investor name: User: /sec-edgar Show me Warren Buffett's latest holdings → Same result via person name lookup

Example 2: Apple 10-Q Financials

User: /sec-edgar Fetch latest 10-Q financial statements for AAPL

Expected workflow: 1. Validate ticker: "AAPL" 2. Call edgar.get_10kq_filings("AAPL", form_name='10-Q', num_latest=1) 3. Save markdown and CSV to 10-Q/ directory 4. Report: "Retrieved Q1 2024 10-Q for Apple Inc. Revenue: $119.6B (+4.3% YoY), Net Income: $33.9B, EPS: $2.18."

Example 3: Section Extraction from 10-K

User: /sec-edgar Extract risk factors and business description from Tesla's latest 10-K

Expected workflow: 1. Call edgar.get_10kq_filings("TSLA", form_name='10-K', num_latest=1) 2. Filing fetched and sections automatically extracted 3. Save 4 section files to 10-K/ directory: - TSLA_10-K_item_1_business.txt (45KB - products, operations, strategy) - TSLA_10-K_item_1a_risk.txt (84KB - comprehensive risk analysis) - TSLA_10-K_item_7_mda.txt (64KB - management discussion) - TSLA_10-K_item_8_financials.txt (100KB - audited statements) 4. Report: "Retrieved 2025 10-K for Tesla Inc. Extracted 4 sections totaling 293KB. Key risks include AI development, production ramp, supply chain."

Example 4: Combined Holdings Analysis

User: /sec-edgar Analyze Berkshire's holdings and get financials for all portfolio companies

Expected workflow: 1. Call edgar.get_13f_filings_and_10q_for_holdings("0001067983", 1) 2. Fetch 13F holdings 3. Extract 43 valid tickers (2 show "Not Found") 4. Batch fetch 10-Q for all 43 tickers 5. Report: "Analyzed 45 holdings. Retrieved financials for 43 companies. 2 tickers not found: [CUSIP list]. Files saved to workspace."

Available Functions

Use the EdgarLibrary.py script in scripts/ directory. Key functions:

get_13f_filings(cik: str, num_latest: int) -> pd.DataFrame

Retrieves institutional holdings from 13F-HR filings.

get_10kq_filings(ticker: str, form_name: str, num_latest: int) -> pd.DataFrame

Retrieves financial statements from 10-K or 10-Q filings.

get_10kq_filings_bulk(tickers: Union[Set[str], List[str]], form_name: str, num_latest: int) -> pd.DataFrame

Batch fetch financials for multiple tickers.

get_13f_filings_and_10q_for_holdings(cik: str, num_latest: int) -> None

Combined workflow: fetch 13F holdings + 10-Q financials for all positions.

See references/api_reference.md for complete function documentation.

Shared as is, with no warranty. Not investment, legal or tax advice. See Disclosures.