Sec Edgar Skill

SEC EDGAR Skill - Filing Analysis

Prerequisites

CRITICAL: Run this setup before ANY EdgarTools operations:

from edgar import set_identity
set_identity("Your Name your.email@example.com")  # SEC requires identification

This is a SEC legal requirement. Operations will fail without it.

---

Installation

EdgarTools must be installed:

pip install edgartools

---

Token Efficiency Strategy

ALWAYS use `.to_context()` first - it provides summaries with 56-89% fewer tokens:

Rule: Call .to_context() first to understand what's available, then drill down.

---

Three Ways to Access Filings

1. Published Filings - Bulk Cross-Company Analysis

from edgar import get_filings

# Get recent 10-K filings
filings = get_filings(form="10-K")

# Filter by date range
filings = get_filings(form="10-K", year=2024, quarter=1)

# Multiple form types
filings = get_filings(form=["10-K", "10-Q"])

2. Current Filings - Real-Time Monitoring

from edgar import get_current_filings

# Get today's filings from RSS feed
current = get_current_filings()

# Filter by form type
current_10k = get_current_filings().filter(form="10-K")

3. Company Filings - Single Entity Analysis

from edgar import Company

# By ticker
company = Company("AAPL")

# By CIK
company = Company("0000320193")

# Get company's filings
filings = company.get_filings(form="10-K")
latest_10k = filings.latest()

---

Financial Data Access

Method 1: Entity Facts API (Fast, Multi-Period)

Best for comparing trends across periods:

company = Company("AAPL")

# Get income statement for multiple periods
income = company.income_statement(periods=5)
print(income)  # Shows 5 years of data

# Get balance sheet
balance = company.balance_sheet(periods=3)

# Get cash flow
cashflow = company.cash_flow_statement(periods=3)

Method 2: Filing XBRL (Detailed, Single Period)

Best for comprehensive single-filing analysis:

company = Company("AAPL")
filing = company.get_filings(form="10-K").latest()

# Get XBRL data
xbrl = filing.xbrl()

# Access financial statements
statements = xbrl.statements
income_stmt = statements.income_statement
balance_sheet = statements.balance_sheet
cash_flow = statements.cash_flow_statement

---

Common Workflows

Workflow 1: Compare Revenue Across Companies

from edgar import Company

companies = ["AAPL", "MSFT", "GOOGL"]
for ticker in companies:
    company = Company(ticker)
    income = company.income_statement(periods=3)
    print(f"\n{ticker} Revenue Trend:")
    print(income)

Workflow 2: Analyze Latest 10-K

from edgar import Company

company = Company("NVDA")
filing = company.get_filings(form="10-K").latest()

# Get filing metadata
print(filing.to_context())

# Get full text (expensive - 50K+ tokens)
# text = filing.text()

# Get specific sections
# items = filing.items()  # Risk factors, MD&A, etc.

Workflow 3: Track Insider Trading

from edgar import Company

company = Company("TSLA")
insider_filings = company.get_filings(form="4")  # Form 4 = insider trades

for filing in insider_filings[:10]:
    print(filing.to_context())

Workflow 4: Monitor Recent Filings by Sector

from edgar import get_filings

# Get recent tech 10-Ks (use SIC codes)
# SIC 7370-7379 = Computer Programming, Data Processing
filings = get_filings(form="10-K", year=2024)
# Filter by company characteristics after retrieval

Workflow 5: Multi-Year Financial Trend

from edgar import Company

company = Company("AMZN")

# 5-year income statement
income = company.income_statement(periods=20)  # 20 quarters = 5 years

# 5-year balance sheet
balance = company.balance_sheet(periods=20)

print("Income Statement Trend:")
print(income)
print("\nBalance Sheet Trend:")
print(balance)

---

Search Within Filings

CRITICAL DISTINCTION:

filing = company.get_filings(form="10-K").latest()

# Search WITHIN the filing document (finds text in the 10-K)
results = filing.search("climate risk")

# Search API DOCUMENTATION (finds how to use EdgarTools)
docs_results = filing.docs.search("how to extract")

Do NOT mix these up!

---

Key Objects Reference

Company

company = Company("AAPL")
company.to_context()  # Summary with available actions
company.name          # Company name
company.cik           # CIK number
company.sic           # SIC code
company.industry      # Industry description
company.get_filings() # Access filings

Filing

filing.to_context()   # Summary
filing.form           # Form type (10-K, 10-Q, etc.)
filing.filing_date    # Date filed
filing.accession_number
filing.text()         # Full document text (EXPENSIVE)
filing.markdown()     # Markdown format
filing.xbrl()         # XBRL financial data
filing.items()        # Document sections

XBRL (Financial Data)

xbrl = filing.xbrl()
xbrl.to_context()     # Summary
xbrl.statements       # All financial statements
xbrl.facts            # Individual facts/metrics

Statement (Financial Statement)

stmt = xbrl.statements.income_statement
print(stmt)           # ASCII table format
stmt.to_dataframe()   # Pandas DataFrame

---

Anti-Patterns (Avoid These)

DON'T: Parse financials from raw text

# BAD - expensive and error-prone
text = filing.text()
# try to regex parse revenue from text...

DO: Use structured XBRL data

# GOOD - structured and accurate
income = company.income_statement(periods=3)

DON'T: Load full filing when you only need metadata

# BAD - wastes tokens
text = filing.text()  # 50K+ tokens

DO: Use context first

# GOOD - minimal tokens
print(filing.to_context())  # ~50 tokens

---

Form Types Quick Reference

---

Error Handling

from edgar import Company

try:
    company = Company("INVALID")
except Exception as e:
    print(f"Company not found: {e}")

# Check if filings exist
filings = company.get_filings(form="10-K")
if len(filings) == 0:
    print("No 10-K filings found")

---

Performance Tips

1. Filter before retrieving: Use form type, date filters 2. Use Entity Facts API for trends: Faster than parsing multiple filings 3. Batch operations: Process multiple companies in loops 4. Cache results: Store frequently accessed data

---

Reference Documentation

For detailed documentation, see:

• EdgarTools workflows
• Object reference
• Form types reference

Or use the built-in docs:

from edgar import Company
company = Company("AAPL")
company.docs.search("how to get revenue")

Financial Skill - SEC Filing Analysis

A Claude Code skill for SEC filing analysis powered by EdgarTools.

Quick Start

1. Install EdgarTools

pip install edgartools

2. Set SEC Identity (Required)

from edgar import set_identity
set_identity("Your Name your.email@example.com")

3. Start Analyzing

from edgar import Company

company = Company("AAPL")
income = company.income_statement(periods=4)
print(income)

What This Skill Enables

• Query SEC filings (10-K, 10-Q, 8-K, etc.)
• Extract financial statements (income, balance sheet, cash flow)
• Compare companies and track trends
• Monitor insider trading (Form 4)
• Track institutional holdings (13F)
• Analyze IPO registrations (S-1)

Key Features

Token-Efficient Design

Always use .to_context() first - saves 60-90% tokens vs full output.

Three Filing Access Methods

1. Published Filings - Bulk cross-company analysis 2. Current Filings - Real-time monitoring 3. Company Filings - Single entity analysis

Two Financial Data Methods

1. Entity Facts API - Fast multi-period trends 2. Filing XBRL - Detailed single-period analysis

Example Queries

"Analyze Apple's revenue trend over the last 4 quarters"
"Compare Microsoft and Google's profit margins"
"Show me recent 8-K filings for Tesla"
"Find insider trading activity for NVDA"
"Get Amazon's latest 10-K financial statements"

File Structure

financial-skill/
├── SKILL.md                    # Main skill definition
├── README.md                   # This file
├── requirements.txt            # Dependencies
└── reference/
    ├── workflows.md            # Common analysis workflows
    ├── objects.md              # Object reference
    └── form-types.md           # SEC form types guide

Documentation

• EdgarTools GitHub
• EdgarTools Documentation
• SEC EDGAR

License

MIT (via EdgarTools dependency)

SEC Form Types Reference

Most Common Forms

Annual & Quarterly Reports

Current Events

Proxy & Governance

Insider & Institutional Ownership

Registration & Offerings

Other Important Forms

---

Form Categories for Filtering

Earnings/Financial Analysis

filings = get_filings(form=["10-K", "10-Q"])

Material Events

filings = get_filings(form="8-K")

Insider Activity

filings = get_filings(form=["3", "4", "5"])

Institutional Holdings

filings = get_filings(form=["13F-HR", "13D", "13G"])

IPO/Offerings

filings = get_filings(form=["S-1", "S-1/A", "424B"])

Proxy/Governance

filings = get_filings(form=["DEF 14A", "DEFA14A"])

---

Filing Timing Reference

Filer Categories:

• Large Accelerated: >$700M public float
• Accelerated: $75M-$700M public float
• Non-Accelerated: <$75M public float

---

Common Use Cases by Form

Due Diligence on a Company

# Comprehensive view
forms = ["10-K", "10-Q", "8-K", "DEF 14A"]
filings = company.get_filings(form=forms)

Track Insider Sentiment

# Watch for insider buying/selling
insider_forms = ["3", "4", "5"]
filings = company.get_filings(form=insider_forms)

Monitor M&A Activity

# M&A related forms
ma_forms = ["8-K", "S-4", "DEFM14A"]
filings = company.get_filings(form=ma_forms)

Find New IPOs

# IPO registrations
ipo_forms = ["S-1", "S-1/A", "F-1"]
filings = get_filings(form=ipo_forms, year=2024)

Hedge Fund Holdings

# 13F filings (institutional managers)
filings = get_filings(form="13F-HR", year=2024, quarter=4)

EdgarTools Objects Reference

Core Objects Overview

---

Company Object

Creation

from edgar import Company

# By ticker
company = Company("AAPL")

# By CIK
company = Company("0000320193")

# By name (fuzzy match)
company = Company("Apple Inc")

Properties

company.name           # "Apple Inc."
company.cik            # "0000320193"
company.tickers        # ["AAPL"]
company.sic            # "3571"
company.sic_description # "Electronic Computers"
company.industry       # Industry classification
company.state          # State of incorporation
company.exchanges      # ["NASDAQ"]

Methods

# Get filings
filings = company.get_filings()           # All filings
filings = company.get_filings(form="10-K") # Specific form

# Financial statements (Entity Facts API - fast)
income = company.income_statement(periods=4)
balance = company.balance_sheet(periods=4)
cashflow = company.cash_flow_statement(periods=4)

# Context for AI
company.to_context()  # Token-efficient summary

---

Filing Object

Access

# From company
filing = company.get_filings(form="10-K").latest()

# From global search
from edgar import get_filings
filings = get_filings(form="10-K", year=2024)
filing = filings[0]

Properties

filing.form             # "10-K"
filing.filing_date      # datetime
filing.accession_number # "0000320193-24-000081"
filing.company          # Company name
filing.cik              # CIK number

Methods

# Summaries
filing.to_context()    # Token-efficient summary

# Full content (EXPENSIVE - 50K+ tokens)
filing.text()          # Plain text
filing.markdown()      # Markdown format

# Structured data
filing.xbrl()          # XBRL financial data
filing.items()         # Document sections

# Search within filing
filing.search("climate risk")  # Find text in document

---

Filings Collection

Filtering

filings = company.get_filings()

# Filter by form
filings_10k = filings.filter(form="10-K")
filings_quarterly = filings.filter(form=["10-K", "10-Q"])

# Filter by date
filings_2024 = filings.filter(date="2024-01-01:")
filings_range = filings.filter(date="2023-01-01:2024-01-01")

# Get latest
latest = filings.latest()

# Get specific count
recent_5 = filings[:5]

Properties

len(filings)          # Count
filings.to_context()  # Summary for AI

---

XBRL Object

Access

filing = company.get_filings(form="10-K").latest()
xbrl = filing.xbrl()

Properties

xbrl.statements       # Access to all statements
xbrl.facts            # Individual XBRL facts
xbrl.fiscal_year_end  # Fiscal year end date
xbrl.period_end       # Reporting period end

Statements Access

statements = xbrl.statements

# Core financial statements
income = statements.income_statement
balance = statements.balance_sheet
cashflow = statements.cash_flow_statement

# Other statements (if available)
equity = statements.stockholders_equity
comprehensive = statements.comprehensive_income

---

Statement Object

Display

stmt = xbrl.statements.income_statement

# Print as ASCII table
print(stmt)

# Get as DataFrame
df = stmt.to_dataframe()

Properties

stmt.period           # Reporting period
stmt.line_items       # List of line items

Line Item Access

# Access specific metrics
revenue = stmt.get("Revenue")
net_income = stmt.get("NetIncome")

---

MultiPeriodStatement Object

Returned by Entity Facts API methods:

income = company.income_statement(periods=4)

# This is a MultiPeriodStatement
print(income)  # Shows 4 periods side-by-side

# Convert to DataFrame
df = income.to_dataframe()

---

Token Optimization Guide

Always Start with Context

# GOOD - see what's available first
print(company.to_context())   # ~75 tokens
print(filing.to_context())    # ~50 tokens
print(xbrl.to_context())      # ~275 tokens

# Then drill down if needed

Avoid Full Text Unless Necessary

# BAD - expensive
text = filing.text()  # 50,000+ tokens

# GOOD - get what you need
xbrl = filing.xbrl()  # Structured data
income = xbrl.statements.income_statement  # ~400 tokens

Use Entity Facts for Trends

# GOOD - single API call, multiple periods
income = company.income_statement(periods=12)

# BAD - parsing 12 separate filings
for q in range(12):
    filing = filings[q]
    xbrl = filing.xbrl()  # 12 XBRL parses

---

Documentation Access

Every object has .docs for built-in documentation:

company.docs                      # Full docs
company.docs.search("revenue")    # Search docs

filing.docs
filing.docs.search("items")

xbrl.docs
xbrl.docs.search("statements")

EdgarTools Workflows Reference

Workflow 1: Compare Revenue Across Competitors

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

# Define competitors
competitors = ["AAPL", "MSFT", "GOOGL", "META", "AMZN"]

# Compare revenue trends
for ticker in competitors:
    company = Company(ticker)
    income = company.income_statement(periods=4)  # 4 quarters
    print(f"\n{'='*50}")
    print(f"{company.name} ({ticker})")
    print(f"{'='*50}")
    print(income)

---

Workflow 2: Monitor Recent 10-K/10-Q Filings

from edgar import get_current_filings, set_identity

set_identity("Your Name email@example.com")

# Get today's quarterly/annual reports
current = get_current_filings()

# Filter to 10-K and 10-Q only
earnings_filings = current.filter(form=["10-K", "10-Q"])

print(f"Found {len(earnings_filings)} earnings filings today:")
for filing in earnings_filings[:20]:
    print(f"  {filing.company} - {filing.form} - {filing.filing_date}")

---

Workflow 3: Deep Dive Single Company Financials

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

company = Company("NVDA")

# Get latest 10-K
filing = company.get_filings(form="10-K").latest()
print(f"Analyzing: {filing.to_context()}")

# Get XBRL financial data
xbrl = filing.xbrl()

# Access all statements
statements = xbrl.statements

# Income Statement
print("\n=== INCOME STATEMENT ===")
print(statements.income_statement)

# Balance Sheet
print("\n=== BALANCE SHEET ===")
print(statements.balance_sheet)

# Cash Flow Statement
print("\n=== CASH FLOW STATEMENT ===")
print(statements.cash_flow_statement)

---

Workflow 4: Extract Filing Sections (MD&A, Risk Factors)

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

company = Company("TSLA")
filing = company.get_filings(form="10-K").latest()

# Get document items/sections
items = filing.items()

# Common 10-K sections:
# Item 1 - Business
# Item 1A - Risk Factors
# Item 7 - MD&A (Management Discussion & Analysis)
# Item 8 - Financial Statements

# Access specific sections
for item in items:
    print(f"{item.name}: {len(item.text)} characters")

---

Workflow 5: Historical IPO Analysis

from edgar import get_filings, set_identity

set_identity("Your Name email@example.com")

# Find S-1 filings (IPO registrations) from 2024
s1_filings = get_filings(form="S-1", year=2024)

print(f"Found {len(s1_filings)} S-1 filings in 2024")

# List recent IPO registrations
for filing in s1_filings[:15]:
    print(f"{filing.company} - Filed: {filing.filing_date}")

---

Workflow 6: 5-Year Financial Trend Analysis

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

company = Company("AMZN")

# Get 5 years of data (20 quarters)
print("=== 5-YEAR INCOME STATEMENT ===")
income = company.income_statement(periods=20)
print(income)

print("\n=== 5-YEAR BALANCE SHEET ===")
balance = company.balance_sheet(periods=20)
print(balance)

print("\n=== 5-YEAR CASH FLOW ===")
cashflow = company.cash_flow_statement(periods=20)
print(cashflow)

---

Workflow 7: Track Insider Trading Activity

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

company = Company("AAPL")

# Form 4 = Insider trading reports
insider_filings = company.get_filings(form="4")

print(f"Recent insider transactions for {company.name}:")
for filing in insider_filings[:10]:
    print(f"  {filing.filing_date}: {filing.to_context()}")

---

Workflow 8: Institutional Holdings (13F)

from edgar import get_filings, set_identity

set_identity("Your Name email@example.com")

# 13F = Institutional investment manager holdings
# Filed quarterly by funds with >$100M AUM

filings_13f = get_filings(form="13F-HR", year=2024, quarter=3)

print(f"Found {len(filings_13f)} 13F filings for Q3 2024")

# Look at specific fund
for filing in filings_13f[:10]:
    print(f"{filing.company}: Filed {filing.filing_date}")

---

Workflow 9: Compare Companies Side-by-Side

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

def get_key_metrics(ticker):
    """Extract key financial metrics for a company."""
    company = Company(ticker)
    income = company.income_statement(periods=4)
    balance = company.balance_sheet(periods=1)

    return {
        "ticker": ticker,
        "name": company.name,
        "industry": company.industry,
        # Add specific metrics from statements
    }

# Compare chip companies
tickers = ["NVDA", "AMD", "INTC"]
for ticker in tickers:
    metrics = get_key_metrics(ticker)
    print(f"\n{metrics['name']} ({ticker})")
    print(f"  Industry: {metrics['industry']}")

---

Error Handling Patterns

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

def safe_get_financials(ticker):
    """Safely retrieve financials with error handling."""
    try:
        company = Company(ticker)
    except Exception as e:
        print(f"Could not find company: {ticker}")
        return None

    filings = company.get_filings(form="10-K")
    if len(filings) == 0:
        print(f"No 10-K filings for {ticker}")
        return None

    try:
        filing = filings.latest()
        xbrl = filing.xbrl()
        return xbrl.statements
    except Exception as e:
        print(f"Could not parse XBRL for {ticker}: {e}")
        return None

# Usage
statements = safe_get_financials("AAPL")
if statements:
    print(statements.income_statement)

---

Performance Optimization

from edgar import Company, get_filings, set_identity

set_identity("Your Name email@example.com")

# TIP 1: Use Entity Facts API for trends (faster than parsing filings)
company = Company("MSFT")
income = company.income_statement(periods=12)  # 12 quarters, single API call

# TIP 2: Filter early, retrieve late
filings = get_filings(form="10-K", year=2024)  # Pre-filtered
# vs
# filings = get_filings()  # All filings, then filter - SLOW

# TIP 3: Use .to_context() before diving deep
filing = company.get_filings(form="10-K").latest()
print(filing.to_context())  # ~50 tokens, see what's available
# Only then: filing.text() if you really need full text

# TIP 4: Batch company lookups
tickers = ["AAPL", "MSFT", "GOOGL"]
companies = [Company(t) for t in tickers]  # Load all at once