xonevn-ai/xone-trading-skills/earnings-calendar
Claude Code and agent skill by xonevn-ai/xone-trading-skills
- community
Checking that the SKILL.md file is still in the repository.
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.
Install
npx vskill@latest install xonevn-ai/xone-trading-skills/earnings-calendarSKILL.md
The same SKILL.md was published earlier as xonevn-ai/xone-trading-skills/earnings-calendar.
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):
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):
- 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):
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:
- 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:
Execution:
Option A: Output to stdout:
Option B: Save to file:
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:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/earnings-calendar/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/xonevn-ai/xone-trading-skills/earnings-calendar)