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 m

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 : 1. Visit: https://site.financialmodelingprep.com/developer/docs 2. Sign up for free account 3. Receive API key immediately 4. Free tier: 250 API calls/day (sufficient for weekly earnings calendar) API Key Setup by Environment : Claude Code (CLI) : 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 : 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: 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 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 : 3.2.1 If user chooses "No, get free key" : Provide instructions: 3.3 Request API Key Input If user has API key, request input: Prompt : Store API key in session variable : Confirm with user : Step 4: Retrieve Earnings Data via FMP API Use the Python script to fetch earnings data from FMP API. Script Location : Execution : Option A: With Environment Variable (CLI) : Option B: With Session API Key (Desktop/Web) : Script Workflow (automatic): 1. Validates API key and date parameters 2. Calls FMP Earnings Calendar API for date range 3. Fetches company profiles (market cap, sector, industry) 4. Filters companies with market cap $2B 5. Normalizes timing (BMO/AMC/TAS) 6. Sorts by date → timing → market cap (descending) 7. Outputs JSON to stdout Expected Output Format (JSON): Save to file (recommended for use with report generator): Or capture to variable: 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: Or if saved to file: 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: 1. Before Market Open (BMO) 2. After Market Close (AMC) 3. 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 : Execution : Option A: Output to stdout : Option B: Save to file : What the script does : 1. Loads earnings data from JSON file 2. Groups by date and timing (BMO/AMC/TAS) 3. Sorts by market cap within each group 4. Calculates summary statistics 5. Generates formatted markdown report 6. 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 : Formatting Best Practices : Use markdown tables for clean presentation Bold important company names (mega cap) if desired Include market cap in human readable format ($3.0T, $150B, $5.2B) already formatted by script Group logically by date then timing Include summary section at top for quick overview Add EPS and revenue estimates if available Step 7: Quality Assurance Before finalizing the report, verify: Data Quality Checks : 1. ✓ All dates fall within the target week (next 7 days) 2. ✓ Market cap values are present for all companies 3. ✓ Each company has timing specified (BMO/AMC/TAS) 4. ✓ Companies are sorted by market cap within each section 5. ✓ Summary statistics are accurate 6. ✓ Report generation date is clearly stated 7. ✓ EPS and revenue estimates included where available Completeness Checks : 1. ✓ All days of the target week are included (even if no earnings) 2. ✓ Major known companies are not missing (verify against external sources if needed) 3. ✓ Sector information is included where available 4. ✓ Timing reference section is present 5. ✓ Data sources are credited (FMP API) Format Checks : 1. ✓ Markdown tables are properly formatted 2. ✓ Dates are consistently formatted 3. ✓ Market caps use consistent units (B for billions, T for trillions) 4. ✓ All sections follow template structure 5. ✓ No placeholder text ([PLACEHOLDER]) remains 6. ✓ EPS and revenue estimates properly formatted Step 8: Save and Deliver Report Save the generated report with an appropriate filename: Filename Convention : Example: earnings calendar 2025 11 02.md The filename date represents the report generation date, not the earnings week. Delivery : Save the markdown file to the working directory Inform the user that the report has been generated Provide a brief summary of key findings (e.g., "45 companies reporting next week, with Apple and Microsoft on Monday") Example Summary : Fallback Mode (Step 8 Alternative): Manual Data Entry If API access is unavailable or user chooses to skip API: Provide Instructions for Manual Entry : Process Manual Input : 1. Parse user provided earnings data 2. Organize by date, timing, and market cap 3. Generate report using same template 4. Note in report: "Data Source: Manual Entry" Use Cases and Examples Use Case 1: Weekly Review (Primary Use Case) User Request : "Get next week's earnings calendar" Workflow : 1. Get current date (e.g., November 2, 2025) 2. Calculate target week (November 3 9, 2025) 3. Load FMP API guide 4. Detect/request API key 5. Fetch earnings data: 6. Generate markdown report: 7. Notify user with summary Complete One Liner : Use Case 2: Focused on Specific Day User Request : "What earnings are coming out Monday?" Workflow : 1. Get current date and identify next Monday (e.g., November 4, 2025) 2. Fetch full week data (same as Use Case 1) 3. Generate full report but highlight Monday section 4. Provide verbal summary of Monday's earnings with emphasis Use Case 3: Mega Cap Focus User Request : "Show me earnings for companies over $100B market cap next week" Workflow : 1. Fetch full earnings data (script already filters $2B) 2. Process and organize as normal 3. When generating report, add a "Mega Cap Focus" section at top 4. Filter tables to show only companies $100B 5. Note: Still include full data in appendix for reference Use Case 4: Sector Specific User Request : "What tech companies have earnings next week?" Workflow : 1. Fetch full earnings data 2. Process and organize as normal 3. Filter results by sector = "Technology" 4. Generate report with focus on technology sector 5. Note: Template structure remains the same; content is filtered Troubleshooting Problem: API key not working Solutions : Verify API key is correct (copy paste carefully) Check if API key is active (login to FMP dashboard) Ensure no extra spaces before/after key Try generating new API key from FMP dashboard Problem: Script returns empty results Solutions : Verify date range is in future (not past dates) Check date format is YYYY MM DD Try wider date range (e.g., 14 days instead of 7) Verify companies actually have announced earnings dates for that week Problem: Missing major companies Solutions : Company may not have announced earnings date yet Some companies announce dates very late (1 2 days before) Cross reference with company investor relations website Market cap may have dropped below $2B threshold Problem: Rate limit hit (429 error) Solutions : Free tier: 250 calls/day Each weekly report uses ~3 5 API calls Check if other tools/scripts are using same API key Wait 24 hours for rate limit reset Consider upgrading to paid tier if needed frequently Problem: Script execution error Solutions : Verify Python 3 is installed: python3 version Install requests library: pip install requests Check script has execute permissions: chmod +x fetch earnings fmp.py Run with python3 explicitly: python3 fetch earnings fmp.py ... Best Practices Do's ✓ 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'ts ✗ Don't assume "next week" without calculating from current date ✗ Don't omit timing information (BMO/AMC/TAS) ✗

earnings-calendar