earnings-calendar
This skill retrieves upcoming earnings announcements for US stocks using the Financial Modeling Prep (FMP) API. Use this when the user requests earnings calendar data, wants to know which companies are reporting earnings in the upcoming week, or needs a weekly earnings review.
Install / Use
npx skills add tradermonty/claude-trading-skills --skill earnings-calendarInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of earnings-calendar
earnings-calendar scores 95/100 on our quality scale, 137th of 1,153 Content & Media skills we index (top 12%).
Its SKILL.md is 22 KB long, well organised into 55 sections with 26 code examples: a thorough specification that gives an agent plenty to work with.
With 2,885 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so earnings-calendar is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
earnings-calendar compared with similar skills
All 4 of these similar skills score higher than earnings-calendar; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| earnings-calendar (this skill)by tradermonty | 95 | 2.9k | 53d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
| crawl4aiby unclecode | 100 | 87.4k | 3d ago | MCP Server |
Frequently asked questions
- How do I install earnings-calendar?
- Run
npx skills add tradermonty/claude-trading-skills --skill earnings-calendar. The install tabs above show the steps for each supported agent. - Which AI agents does earnings-calendar work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is earnings-calendar safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is earnings-calendar still maintained?
- The repository was last updated about 2 months ago, so earnings-calendar is actively maintained.
Skill content
View source on GitHubname: earnings-calendar description: This skill retrieves upcoming earnings announcements for US stocks using the Financial Modeling Prep (FMP) API. Use this when the user requests earnings calendar data, wants to know which companies are reporting earnings in the upcoming week, or needs a weekly earnings review. The skill focuses on mid-cap and above companies (over $2B market cap) that have significant market impact, organizing the data by date and timing in a clean markdown table format. Supports multiple environments (CLI, Desktop, Web) with flexible API key management.
Earnings Calendar
Overview
This skill retrieves upcoming earnings announcements for US stocks using the Financial Modeling Prep (FMP) API. It focuses on companies with significant market capitalization (mid-cap and above, over $2B) that are likely to impact market movements. The skill generates organized markdown reports showing which companies are reporting earnings over the next week, grouped by date and timing (before market open, after market close, or time not announced).
Key Features:
- Uses FMP API for reliable, structured earnings data
- Filters by market cap (>$2B) to focus on market-moving companies
- Includes EPS and revenue estimates
- Multi-environment support (CLI, Desktop, Web)
- Flexible API key management
- Organized by date, timing, and market cap
Prerequisites
FMP API Key
This skill requires a Financial Modeling Prep API key.
Get Free API Key:
- Visit: https://site.financialmodelingprep.com/developer/docs
- Sign up for free account
- Receive API key immediately
- Free tier: 250 API calls/day (sufficient for weekly earnings calendar)
API Key Setup by Environment:
Claude Code (CLI):
export FMP_API_KEY="your-api-key-here"
Claude Desktop: Set environment variable in system or configure MCP server.
Claude Web: API key will be requested during skill execution (stored only for current session).
Core Workflow
Step 1: Get Current Date and Calculate Target Week
CRITICAL: Always start by obtaining the accurate current date.
Retrieve the current date and time:
- Use system date/time to get today's date
- Note: "Today's date" is provided in the environment (<env> tag)
- Calculate the target week: Next 7 days from current date
Date Range Calculation:
Current Date: [e.g., November 2, 2025]
Target Week Start: [Current Date + 1 day, e.g., November 3, 2025]
Target Week End: [Current Date + 7 days, e.g., November 9, 2025]
Why This Matters:
- Earnings calendars are time-sensitive
- "Next week" must be calculated from the actual current date
- Provides accurate date range for API request
Format dates in YYYY-MM-DD for API compatibility.
Step 2: Load FMP API Guide
Before retrieving data, load the comprehensive FMP API guide:
Read: references/fmp_api_guide.md
This guide contains:
- FMP API endpoint structure and parameters
- Authentication requirements
- Market cap filtering strategy (via Company Profile API)
- Earnings timing conventions (BMO, AMC, TAS)
- Response format and field descriptions
- Error handling strategies
- Best practices and optimization tips
Step 3: API Key Detection and Configuration
Detect API key availability based on environment.
Multi-Environment API Key Detection:
3.1 Check Environment Variable (CLI/Desktop)
if [ ! -z "$FMP_API_KEY" ]; then
echo "✓ API key found in environment"
API_KEY=$FMP_API_KEY
fi
If environment variable is set, proceed to Step 4.
3.2 Prompt User for API Key (Desktop/Web)
If environment variable not found, use AskUserQuestion tool:
Question Configuration:
Question: "This skill requires an FMP API key to retrieve earnings data. Do you have an FMP API key?"
Header: "API Key"
Options:
1. "Yes, I'll provide it now" → Proceed to 3.3
2. "No, get free key" → Show instructions (3.2.1)
3. "Skip API, use manual entry" → Jump to Step 8 (fallback mode)
3.2.1 If user chooses "No, get free key":
Provide instructions:
To get a free FMP API key:
1. Visit: https://site.financialmodelingprep.com/developer/docs
2. Click "Get Free API Key" or "Sign Up"
3. Create account (email + password)
4. Receive API key immediately
5. Free tier includes 250 API calls/day (sufficient for daily use)
Once you have your API key, please select "Yes, I'll provide it now" to continue.
3.3 Request API Key Input
If user has API key, request input:
Prompt:
Please paste your FMP API key below:
(Your API key will only be stored for this conversation session and will be forgotten when the session ends. For regular use, consider setting the FMP_API_KEY environment variable.)
Store API key in session variable:
API_KEY = [user_input]
Confirm with user:
✓ API key received and stored for this session.
Security Note:
- API key is stored only in current conversation context
- Not saved to disk or persistent storage
- Will be forgotten when session ends
- Do not share this conversation if it contains your API key
Proceeding with earnings data retrieval...
Step 4: Retrieve Earnings Data via FMP API
Use the Python script to fetch earnings data from FMP API.
Script Location:
scripts/fetch_earnings_fmp.py
Execution:
Option A: With Environment Variable (CLI):
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09
Option B: With Session API Key (Desktop/Web):
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}"
Script Workflow (automatic):
- Validates API key and date parameters
- Calls FMP Earnings Calendar API for date range
- Fetches company profiles (market cap, sector, industry)
- Filters companies with market cap >$2B
- Normalizes timing (BMO/AMC/TAS)
- Sorts by date → timing → market cap (descending)
- Outputs JSON to stdout
Expected Output Format (JSON):
[
{
"symbol": "AAPL",
"companyName": "Apple Inc.",
"date": "2025-11-04",
"timing": "AMC",
"marketCap": 3000000000000,
"marketCapFormatted": "$3.0T",
"sector": "Technology",
"industry": "Consumer Electronics",
"epsEstimated": 1.54,
"revenueEstimated": 123400000000,
"fiscalDateEnding": "2025-09-30",
"exchange": "NASDAQ"
},
...
]
Save to file (recommended for use with report generator):
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}" > earnings_data.json
Or capture to variable:
earnings_data=$(python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}")
Error Handling:
If script returns errors:
- 401 Unauthorized: Invalid API key → Verify key or re-enter
- 429 Rate Limit: Exceeded 250 calls/day → Wait or upgrade plan
- Empty Result: No earnings in date range → Expand date range or note in report
- Connection Error: Network issue → Retry or use cached data if available
Step 5: Process and Organize Data
Once earnings data is retrieved (JSON format), process and organize it:
5.1 Parse JSON Data
Load JSON data from script output:
import json
earnings_data = json.loads(earnings_json_string)
Or if saved to file:
with open('earnings_data.json', 'r') as f:
earnings_data = json.load(f)
5.2 Verify Data Structure
Confirm data includes required fields:
- ✓ symbol
- ✓ companyName
- ✓ date
- ✓ timing (BMO/AMC/TAS)
- ✓ marketCap
- ✓ sector
5.3 Group by Date
Group all earnings announcements by date:
- Sunday, [Full Date] (if applicable)
- Monday, [Full Date]
- Tuesday, [Full Date]
- Wednesday, [Full Date]
- Thursday, [Full Date]
- Friday, [Full Date]
- Saturday, [Full Date] (if applicable)
5.4 Sub-Group by Timing
Within each date, create three sub-sections:
- Before Market Open (BMO)
- After Market Close (AMC)
- Time Not Announced (TAS)
Data is already sorted by timing from the script, so maintain this order.
5.5 Within Each Timing Group
Companies are already sorted by market cap descending (script output):
- Mega-cap (>$200B) first
- Large-cap ($10B-$200B) second
- Mid-cap ($2B-$10B) third
This prioritization ensures the most market-moving companies are listed first.
5.6 Calculate Summary Statistics
Compute:
- Total Companies: Count of all companies in dataset
- Mega/Large Cap Count: Count where marketCap >= $10B
- Mid Cap Count: Count where marketCap between $2B and $10B
- Peak Day: Day of week with most earnings announcements
- Sector Distribution: Count by sector (Technology, Healthcare, Financial, etc.)
- Highest Market Cap Companies: Top 5 companies by market cap
Step 6: Generate Markdown Report
Use the report generation script to create a formatted markdown report from the JSON data.
Script Location:
scripts/generate_report.py
Execution:
Option A: Output to stdout:
python scripts/generate_report.py earnings_data.json
Option B: Save to file:
python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md
What the script does:
- Loads earnings data from JSON file
- Groups by date and timing (BMO/AMC/TAS)
- Sorts by market cap within each group
- Calculates summary statistics
- Generates formatted markdown report
- Outputs to stdout or saves to file
The script automatically handles all formatting including:
- Proper markdown table structure
- Date grouping and day names
- Market cap sorting
- EPS and revenue formatting
- Summary statistics calculation
Report Structure:
# Upcoming Earnings Calendar - Week of [START_DATE] to [END_DATE]
**Report Generated**: [Current Date]
**Data Source**: FMP API (Mid-cap and above, >$2B market cap)
**Coverage Period**: Next 7 days
**Total Companies**: [COUNT]
---
## Executive Summary
- **Total Companies Reporting**: [TOTAL_COUNT]
- **Mega/Large Cap (>$10B)**: [LARGE_CAP_COUNT]
- **Mid Cap ($2B-$10B)**: [MID_CAP_COUNT]
- **Peak Day**: [DAY_WITH_MOST_EARNINGS]
---
## [Day Name], [Full Date]
### Before Market Open (BMO)
| Ticker | Company | Market Cap | Sector | EPS Est. | Revenue Est. |
|--------|---------|------------|--------|----------|--------------|
| [TICKER] | [COMPANY] | [MCAP] | [SECTOR] | [EPS] | [REV] |
### After Market Close (AMC)
| Ticker | Company | Market Cap | Sector | EPS Est. | Revenue Est. |
|--------|---------|------------|--------|----------|--------------|
| [TICKER] | [COMPANY] | [MCAP] | [SECTOR] | [EPS] | [REV] |
### Time Not Announced (TAS)
| Ticker | Company | Market Cap | Sector | EPS Est. | Revenue Est. |
|--------|---------|------------|--------|----------|--------------|
| [TICKER] | [COMPANY] | [MCAP] | [SECTOR] | [EPS] | [REV] |
---
[Repeat for each day of week]
---
## Key Observations
### Highest Market Cap Companies This Week
1. [COMPANY] ([TICKER]) - [MCAP] - [DATE] [TIME]
2. [COMPANY] ([TICKER]) - [MCAP] - [DATE] [TIME]
3. [COMPANY] ([TICKER]) - [MCAP] - [DATE] [TIME]
### Sector Distribution
- **Technology**: [COUNT] companies
- **Healthcare**: [COUNT] companies
- **Financial**: [COUNT] companies
- **Consumer**: [COUNT] companies
- **Other**: [COUNT] companies
### Trading Considerations
- **Days with Heavy Volume**: [DATES with multiple large-cap earnings]
- **Pre-Market Focus**: [BMO companies that may move markets]
- **After-Hours Focus**: [AMC companies that may move markets]
---
## Timing Reference
- **BMO (Before Market Open)**: Announcements typically around 6:00-8:00 AM ET before market opens at 9:30 AM ET
- **AMC (After Market Close)**: Announcements typically around 4:00-5:00 PM ET after market closes at 4:00 PM ET
- **TAS (Time Not Announced)**: Specific time not yet disclosed - monitor company investor relations
---
## Data Notes
- **Market Cap Categories**:
- Mega Cap: >$200B
- Large Cap: $10B-$200B
- Mid Cap: $2B-$10B
- **Filter Criteria**: Th
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.4kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
