Guide · Agent skill
How to use the SEC EDGAR Filings Fetcher agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The sec-edgar skill teaches an AI agent how to fetch official U.S. company data from the Securities and Exchange Commission's free EDGAR system. Once it is installed, you can ask the agent for a company's recent filings, such as annual 10-K or quarterly 10-Q reports, with links to the source documents, or for reported figures like revenue over time. This guide covers what agent skills are, how to install this one, how to phrase requests, what it needs to run, and where its limits are.
SEC EDGAR Filings FetcherHKUDS/Vibe-Trading · MIT Download the skill Quick start
- 1Download the ZIP. Download the sec-edgar skill ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
- 3Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill there.
- 4Check the requirements. Confirm you have a Python environment with the Vibe-Trading backtest package and internet access to sec.gov.
- 5Make a request. Ask for a company's filings by ticker, for example the last five 10-K filings for AAPL.
- 6Check the output. Review the returned filing rows and document links, and confirm the form and dates match what you asked for.
What is an agent skill, and what does this one do?
An agent skill is a folder of instructions and optional scripts that an AI agent loads when a task matches the skill's description. This one is named sec-edgar and is documented in a SKILL.md file. It tells the agent how to use the bundled sec_edgar_client transport and the get_sec_filings tool to read data from sec.gov.
The skill covers three jobs: resolving a U.S. ticker such as AAPL to its SEC Central Index Key (CIK), listing recent filings with primary-document URLs, and pulling XBRL companyfacts series for a us-gaap concept such as Revenues or NetIncomeLoss. It is a data-retrieval guide, not an analysis method. Reading a 10-K or scoring insider activity is covered by a separate methodology skill, edgar-sec-filings.
Install the sec-edgar skill
Download the skill ZIP from this page and unzip it into one of two locations. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project. After unzipping, the sec-edgar folder should contain SKILL.md, the references/ folder and the scripts/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: ~/.claude/skills/sec-edgar/
- Project: .claude/skills/sec-edgar/ inside your project
- Claude apps: Settings → Capabilities → Skills
Ask the agent for filings in plain language
You do not need to type a command. Describe what you want and name the company by its ticker. The agent will choose the get_sec_filings tool when the request matches this skill. Useful requests include asking for the latest 10-K for a ticker, the last few 10-Qs, recent 8-K filings, or the revenue history for a company.
The tool accepts a ticker, an optional form type and an optional XBRL metric. Under the hood, a request for recent annual reports looks like this:
- Latest annual reports for a company: "List the last 5 10-K filings for AAPL."
- Financial history: "Pull Microsoft's Revenues series for the last 8 reported values."
{ "ticker": "AAPL", "form": "10-K", "limit": 5 }Use the Python client for raw data
If you are building a tool or need fields the tool does not return, such as a company's address, call the client directly. The bundled example script shows the full flow from ticker to CIK to recent 10-K filings to a metric series.
The client returns decoded JSON as a Python dict. Filing document URLs are assembled from the accession number and primary document name, and the CIK is zero-padded to 10 digits for the submissions and companyfacts endpoints.
- cik_for returns the padded CIK, or None if the ticker is not in the SEC table
- get_submissions returns the recent-filings index and company metadata
- get_company_facts returns all reported XBRL concepts
from backtest.loaders.sec_edgar_client import cik_for, get_submissions, get_company_facts
cik = cik_for("AAPL")
submissions = get_submissions(cik)
facts = get_company_facts(cik)Know the requirements and identifiers
The skill needs a Python environment with the Vibe-Trading backtest package, since it imports sec_edgar_client and backtest.loaders._http. It also needs internet access to sec.gov. No API key is required. You can optionally set the VIBE_TRADING_SEC_UA environment variable to a contact User-Agent. The client ships a default that is meant to be compliant, and this variable overrides it.
Forms are case-insensitive, such as 10-K, 10-Q, 8-K, DEF 14A or 4. Metrics are case-sensitive because they are exact us-gaap taxonomy names, so use Revenues rather than revenues.
- Python environment with the Vibe-Trading backtest package
- Internet access to sec.gov
- Optional: VIBE_TRADING_SEC_UA for a contact User-Agent
- No API key
Safety notes: scripts and network access
This skill runs scripts and uses the network. The example script and client send requests to www.sec.gov and data.sec.gov. Requests go through the shared throttle in backtest.loaders._http under the "sec" bucket, with a spacing floor of about 0.12 seconds that can be changed with VIBE_TRADING_SEC_MIN_INTERVAL. The SEC blocks clients that burst requests or send no contact User-Agent, so do not write your own raw request loops that bypass this throttle.
Read the scripts before running them in an environment you care about, and treat the data as research material, not investment advice.
- Requests go to sec.gov and data.sec.gov only, as documented in the endpoint reference
- Do not bypass the shared throttle with raw requests loops
- The SEC throttles by IP address, so repeated bursts can get your address blocked temporarily
Tips for better results
Name the form you need. Asking for all recent filings returns every form type, which can be noisy. Limit the count when you only need a few rows. Remember that filings appear after a company submits them, and XBRL data trails the filing, so the newest figures may not be in the data yet.
If a ticker returns an error, check that it is a U.S.-listed equity. Non-U.S. symbols do not resolve to a CIK.
- Set form to 10-K or 10-Q to keep results focused
- Use the exact us-gaap metric name, for example NetIncomeLoss
- Set VIBE_TRADING_SEC_UA to your own contact address when you use the client heavily
What people use it for
- Pull the last several 10-K annual reports for a U.S.-listed company to find primary-document links.
- List recent 10-Q quarterly reports to track interim filings across a set of tickers.
- Scan recent 8-K current reports for material events such as executive changes or guidance updates.
- Retrieve a us-gaap series such as Revenues or NetIncomeLoss to compare reported figures over time.
- Build a research tool on the Vibe-Trading agent that uses a throttled EDGAR client.
Frequently asked questions
Is the SEC EDGAR filings skill free?
EDGAR is a public, free system and the skill requires no API key. The skill documentation states the data is for research and is not investment advice. Check the MIT licence on this page for the terms on the skill itself.
What do I need to install the sec-edgar skill?
You need the skill folder placed in ~/.claude/skills/ or a project's .claude/skills/ folder, or uploaded under Settings, Capabilities, Skills in the Claude apps. To run its scripts you also need a Python environment with the Vibe-Trading backtest package and internet access to sec.gov.
Does the skill need an API key?
No. The SEC endpoints are public and need no authentication. The only setting it asks for is an optional VIBE_TRADING_SEC_UA environment variable to set a contact User-Agent.
Does it work for non-U.S. stocks like Hong Kong or A-shares?
No. EDGAR covers only U.S. reporting companies, so a non-U.S. symbol will not resolve to a CIK. The skill points you to other data sources for those markets.
Why does my request get throttled or blocked?
The SEC limits requests per IP address and can temporarily block clients that burst requests or send no contact User-Agent. The skill routes every request through a shared throttle with a spacing floor of about 0.12 seconds. Avoid raw request loops that skip this throttle.
How is this different from reading filings with an AI tool directly?
This skill handles data retrieval: it resolves tickers, lists filings with document links, and pulls XBRL series. Interpretation, such as how to read a 10-K or interpret insider activity, belongs to the separate edgar-sec-filings methodology skill.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you need recent SEC filings, document links or reported financial series for a U.S.-listed company and you are comfortable running a small Python environment. Pick something else if you need non-U.S. markets, live prices or ready-made investment analysis, since the skill covers none of those.
Download the skill