Earnings CalendarCAUTION

Claude Code skills for equity investors and traders — market analysis, technical charting, economic calendars, screeners, and trading strategy development.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: 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**:
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)**:
```bash
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)

```bash
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)**:
```bash
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09
```

**Option B: With Session API Key (Desktop/Web)**:
```bash
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}"
```

**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):
```json
[
  {
    "symbol": "A

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

not all pinned

Secrets in source

none-found

Findings (3)

# Add to ~/.zshrc or ~/.bashrc

examples/daily-market-dashboard/.claude/skills

requests

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Earnings Calendar](https://modelsatlas.com/skills/tradermonty/earnings-calendar/badge.svg)](https://modelsatlas.com/skills/tradermonty/earnings-calendar/)

Not your listing, or something out of date? Claim or update your listing.