earnings-calendarThis 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.
Install via ClawdBot CLI:
clawdbot install Veeramanikandanr48/earnings-calendarThis 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:
This skill requires a Financial Modeling Prep API key.
Get Free API Key:
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).
CRITICAL: Always start by obtaining the accurate current date.
Retrieve the current date and time:
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:
Format dates in YYYY-MM-DD for API compatibility.
Before retrieving data, load the comprehensive FMP API guide:
Read: references/fmp_api_guide.mdThis guide contains:
Detect API key availability based on environment.
Multi-Environment API Key Detection:
if [ ! -z "$FMP_API_KEY" ]; then
echo "ā API key found in environment"
API_KEY=$FMP_API_KEY
fiIf environment variable is set, proceed to Step 4.
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.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...Use the Python script to fetch earnings data from FMP API.
Script Location:
scripts/fetch_earnings_fmp.pyExecution:
Option A: With Environment Variable (CLI):
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09Option B: With Session API Key (Desktop/Web):
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}"Script Workflow (automatic):
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.jsonOr 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:
Once earnings data is retrieved (JSON format), process and organize it:
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)Confirm data includes required fields:
Group all earnings announcements by date:
Within each date, create three sub-sections:
Data is already sorted by timing from the script, so maintain this order.
Companies are already sorted by market cap descending (script output):
This prioritization ensures the most market-moving companies are listed first.
Compute:
Use the report generation script to create a formatted markdown report from the JSON data.
Script Location:
scripts/generate_report.pyExecution:
Option A: Output to stdout:
python scripts/generate_report.py earnings_data.jsonOption B: Save to file:
python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.mdWhat the script does:
The script automatically handles all formatting including:
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**: This report includes companies with market cap $2B and above (mid-cap+) with earnings scheduled for the next week.
- **Data Source**: Financial Modeling Prep (FMP) API
- **Data Freshness**: Earnings dates and times can change. Verify critical dates through company investor relations websites for the most current information.
- **EPS and Revenue Estimates**: Analyst consensus estimates from FMP API. Actual results will be reported on earnings date.
---
## Additional Resources
- **FMP API Documentation**: https://site.financialmodelingprep.com/developer/docs
- **Seeking Alpha Calendar**: https://seekingalpha.com/earnings/earnings-calendar
- **Yahoo Finance Calendar**: https://finance.yahoo.com/calendar/earnings
---
*Report generated using FMP Earnings Calendar API with mid-cap+ filter (>$2B market cap). Data current as of report generation time. Always verify earnings dates through official company sources.*Formatting Best Practices:
Before finalizing the report, verify:
Data Quality Checks:
Completeness Checks:
Format Checks:
Save the generated report with an appropriate filename:
Filename Convention:
earnings_calendar_[YYYY-MM-DD].mdExample: earnings_calendar_2025-11-02.md
The filename date represents the report generation date, not the earnings week.
Delivery:
Example Summary:
ā Earnings calendar report generated: earnings_calendar_2025-11-02.md
Summary for week of November 3-9, 2025:
- 45 companies reporting earnings
- 28 large/mega-cap, 17 mid-cap
- Peak day: Thursday (15 companies)
- Notable: Apple (Mon AMC), Microsoft (Tue AMC), Tesla (Wed AMC)
Top 5 by market cap:
1. Apple - $3.0T (Mon AMC)
2. Microsoft - $2.8T (Tue AMC)
3. Alphabet - $1.8T (Thu AMC)
4. Amazon - $1.6T (Fri AMC)
5. Tesla - $800B (Wed AMC)If API access is unavailable or user chooses to skip API:
Provide Instructions for Manual Entry:
Since FMP API is not available, you can manually gather earnings data:
1. Visit Finviz: https://finviz.com/screener.ashx?v=111&f=cap_midover%2Cearningsdate_nextweek
2. Or Yahoo Finance: https://finance.yahoo.com/calendar/earnings
3. Note down companies reporting next week
Please provide the following information for each company:
- Ticker symbol
- Company name
- Earnings date
- Timing (BMO/AMC/TAS)
- Market cap (approximate)
- Sector
I will format this into the standard earnings calendar report.Process Manual Input:
User Request: "Get next week's earnings calendar"
Workflow:
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json
python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.mdComplete One-Liner:
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json && \
python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.mdUser Request: "What earnings are coming out Monday?"
Workflow:
User Request: "Show me earnings for companies over $100B market cap next week"
Workflow:
User Request: "What tech companies have earnings next week?"
Workflow:
Solutions:
Solutions:
Solutions:
Solutions:
Solutions:
python3 --versionpip install requestschmod +x fetch_earnings_fmp.pypython3 fetch_earnings_fmp.py ...ā Always get current date first before any data retrieval
ā Use FMP API as primary source for reliability
ā Store API key in environment variable for CLI usage
ā Sort by market cap to prioritize high-impact companies
ā Group by date then timing for logical organization
ā Include summary statistics for quick overview
ā Credit data sources in report footer
ā Use clean markdown tables for readability
ā Provide timing reference section for clarity
ā Note data freshness and potential for changes
ā Include EPS and revenue estimates when available
ā Don't assume "next week" without calculating from current date
ā Don't omit timing information (BMO/AMC/TAS)
ā Don't mix date formats within report (stay consistent)
ā Don't include micro/small-cap unless specifically requested
ā Don't forget to sort by market cap within sections
ā Don't share API key in conversations or reports
ā Don't include earnings from current week or past dates
ā Don't generate report without quality assurance checks
ā Don't commit API keys to version control
Important Reminders:
Best Practice:
For Claude Code (CLI), always use environment variable:
# Add to ~/.zshrc or ~/.bashrc
export FMP_API_KEY="your-key-here"For Claude Web, understand that:
FMP API:
Supplementary Sources (for verification):
Skill Resources:
references/fmp_api_guide.mdscripts/fetch_earnings_fmp.pyassets/earnings_report_template.mdThis skill provides a reliable, API-driven approach to generating weekly earnings calendars for US stocks. By using FMP API, it ensures structured, accurate data with additional insights like EPS/revenue estimates. The multi-environment support makes it flexible for CLI, Desktop, and Web usage, while the fallback mode ensures functionality even without API access.
Key Workflow: Date Calculation ā API Key Setup ā API Data Retrieval ā Processing ā Report Generation ā QA ā Delivery
Output: Clean, organized markdown report with earnings grouped by date/timing/market cap, including summary statistics and trading considerations.
Generated Mar 1, 2026
Investment analysts at hedge funds or asset management firms use this skill to prepare weekly earnings reports, focusing on mid-cap and above companies with significant market impact. They retrieve upcoming earnings announcements to identify potential market-moving events and adjust portfolio strategies accordingly, using the organized markdown tables for quick reference.
Financial journalists and news editors utilize this skill to gather data on companies reporting earnings in the upcoming week, enabling them to plan coverage and write articles. The skill's focus on market cap filtering helps prioritize high-impact stories, while the clean table format streamlines content creation for publications.
Business strategists in corporations use this skill to monitor earnings announcements of competitors and industry peers, analyzing timing and estimates to inform strategic decisions. By tracking mid-cap and above companies, they assess market trends and potential competitive threats in their sector.
Retail investors with self-directed portfolios employ this skill to stay informed about earnings dates for stocks they own or are considering, using the data to plan trades and manage risk. The skill's multi-environment support allows them to access information conveniently across devices.
Researchers and students in finance or economics use this skill to collect earnings calendar data for studies on market reactions, event analysis, or academic projects. The structured output facilitates data analysis, while the API integration supports reproducible research workflows.
This model involves offering premium API tiers with higher call limits, advanced data features, or real-time updates for a monthly or annual fee. It targets professional users like analysts and firms who require extensive data beyond the free tier, generating recurring revenue from API usage.
A freemium approach provides basic earnings calendar data for free, while charging for additional services such as historical data, custom reports, or integration with other financial tools. This attracts a broad user base and monetizes advanced needs through one-time or ongoing payments.
This model involves licensing the skill or its underlying data to large institutions like banks, media companies, or educational organizations for internal use or redistribution. Revenue comes from annual licensing agreements, often with customization and support options tailored to enterprise clients.
š¬ Integration Tip
Ensure API key management is handled securely across environments by using environment variables for CLI/Desktop and session-based storage for Web, with clear user prompts to avoid exposure.
Manage Trello boards, lists, and cards via the Trello REST API.
Sync and query CalDAV calendars (iCloud, Google, Fastmail, Nextcloud, etc.) using vdirsyncer + khal. Works on Linux.
Manage tasks and projects in Todoist. Use when user asks about tasks, to-dos, reminders, or productivity.
Master OpenClaw's timing systems. Use for scheduling reliable reminders, setting up periodic maintenance (janitor jobs), and understanding when to use Cron v...
Calendar management and scheduling. Create events, manage meetings, and sync across calendar providers.
Kanban-style task management dashboard for AI assistants. Manage tasks via CLI or dashboard UI. Use when user mentions tasks, kanban, task board, mission con...