Back to Details

earnings-calendar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
本技能通过Financial Modeling Prep (FMP) API获取美股即将发布的财报信息。它聚焦于市值较高（中大型公司，市值超过20亿美元）、可能影响市场走势的企业。本技能会生成结构化的Markdown报告，展示未来一周内将发布财报的公司，并按日期和发布时间（盘前、盘后、未公布时间）分组。
核心特性:
  • 使用FMP API获取可靠、结构化的财报数据
  • 按市值筛选（>20亿美元），聚焦影响市场的公司
  • 包含每股收益（EPS）和营收预期
  • 支持多环境（CLI、Desktop、Web）
  • 灵活的API密钥管理
  • 按日期、发布时间和市值排序

Prerequisites

前置条件

FMP API Key

FMP API密钥

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).
本技能需要Financial Modeling Prep的API密钥。
获取免费API密钥:
  1. 访问：https://site.financialmodelingprep.com/developer/docs
  2. 注册免费账户
  3. 立即获取API密钥
  4. 免费套餐：每日250次API调用（足以满足每周财报日历的需求）
按环境配置API密钥:
Claude Code (CLI):
bash
export FMP_API_KEY="your-api-key-here"
Claude Desktop: 在系统中设置环境变量，或配置MCP服务器。
Claude Web: 在技能执行过程中会请求API密钥（仅在当前会话中存储）。

Core Workflow

核心工作流程

Step 1: Get Current Date and Calculate Target Week

步骤1：获取当前日期并计算目标周

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.
关键: 始终从获取准确的当前日期开始。
获取当前日期和时间:
  • 使用系统日期/时间获取今日日期
  • 注意：“今日日期”由环境提供（<env>标签）
  • 计算目标周：从当前日期起的7天内
日期范围计算:
当前日期: [例如：2025年11月2日]
目标周开始: [当前日期+1天，例如：2025年11月3日]
目标周结束: [当前日期+7天，例如：2025年11月9日]
重要性:
  • 财报日历对时间敏感
  • “下周”必须根据实际当前日期计算
  • 为API请求提供准确的日期范围
日期格式需为YYYY-MM-DD以兼容API。

Step 2: Load FMP API Guide

步骤2：加载FMP API指南

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
在获取数据前，加载完整的FMP API指南:
读取: references/fmp_api_guide.md
本指南包含:
  • FMP API端点结构和参数
  • 认证要求
  • 市值筛选策略（通过公司概况API）
  • 财报发布时间约定（BMO、AMC、TAS）
  • 响应格式和字段说明
  • 错误处理策略
  • 最佳实践和优化技巧

Step 3: API Key Detection and Configuration

步骤3：API密钥检测与配置

Detect API key availability based on environment.
Multi-Environment API Key Detection:
根据环境检测API密钥是否可用。
多环境API密钥检测:

3.1 Check Environment Variable (CLI/Desktop)

3.1 检查环境变量（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.
bash
if [ ! -z "$FMP_API_KEY" ]; then
  echo "✓ 环境中找到API密钥"
  API_KEY=$FMP_API_KEY
fi
如果环境变量已设置，进入步骤4。

3.2 Prompt User for API Key (Desktop/Web)

3.2 提示用户提供API密钥（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.
如果未找到环境变量，使用AskUserQuestion工具:
问题配置:
问题: "本技能需要FMP API密钥来获取财报数据。您是否已有FMP API密钥？"
标题: "API密钥"
选项:
  1. "是，我现在提供" → 进入3.3
  2. "没有，获取免费密钥" → 显示说明（3.2.1）
  3. "跳过API，手动输入" → 跳至步骤8（ fallback模式）
3.2.1 如果用户选择“没有，获取免费密钥”:
提供说明:
获取免费FMP API密钥的步骤:

1. 访问: https://site.financialmodelingprep.com/developer/docs
2. 点击“Get Free API Key”或“Sign Up”
3. 创建账户（邮箱+密码）
4. 立即获取API密钥
5. 免费套餐包含每日250次调用（足以满足日常使用）

获取密钥后，请选择“是，我现在提供”继续。

3.3 Request API Key Input

3.3 请求输入API密钥

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...
如果用户已有API密钥，请求输入:
提示:
请在下方粘贴您的FMP API密钥:

(您的API密钥仅会存储在本次对话会话中，会话结束后将被遗忘。如需常规使用，建议设置FMP_API_KEY环境变量。)
将API密钥存储在会话变量中:
API_KEY = [用户输入]
向用户确认:
✓ 已收到API密钥并存储在本次会话中。

安全提示:
- API密钥仅存储在当前对话上下文
- 不会保存到磁盘或持久化存储
- 会话结束后将被遗忘
- 请勿分享包含您API密钥的对话

正在获取财报数据...

Step 4: Retrieve Earnings Data via FMP API

步骤4：通过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": "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):
bash
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}" > earnings_data.json
Or capture to variable:
bash
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
使用Python脚本从FMP API获取财报数据。
脚本位置:
scripts/fetch_earnings_fmp.py
执行方式:
选项A：使用环境变量（CLI）:
bash
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09
选项B：使用会话API密钥（Desktop/Web）:
bash
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}"
脚本工作流程（自动执行）:
  1. 验证API密钥和日期参数
  2. 调用FMP财报日历API获取指定日期范围的数据
  3. 获取公司概况（市值、行业、领域）
  4. 筛选市值>20亿美元的公司
  5. 统一发布时间格式（BMO/AMC/TAS）
  6. 按日期→发布时间→市值（降序）排序
  7. 向标准输出输出JSON格式数据
预期输出格式（JSON）:
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"
  },
  ...
]
保存到文件（推荐用于报告生成器）:
bash
python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}" > earnings_data.json
或捕获到变量:
bash
earnings_data=$(python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}")
错误处理:
如果脚本返回错误:
  • 401 Unauthorized: API密钥无效 → 验证密钥或重新输入
  • 429 Rate Limit: 超出每日250次调用限制 → 等待24小时或升级套餐
  • Empty Result: 指定日期范围内无财报 → 扩大日期范围或在报告中说明
  • Connection Error: 网络问题 → 重试或使用缓存数据（如果有）

Step 5: Process and Organize Data

步骤5：处理和整理数据

Once earnings data is retrieved (JSON format), process and organize it:
获取到财报数据（JSON格式）后，进行处理和整理:

5.1 Parse JSON Data

5.1 解析JSON数据

Load JSON data from script output:
python
import json
earnings_data = json.loads(earnings_json_string)
Or if saved to file:
python
with open('earnings_data.json', 'r') as f:
    earnings_data = json.load(f)
从脚本输出加载JSON数据:
python
import json
earnings_data = json.loads(earnings_json_string)
或从文件加载:
python
with open('earnings_data.json', 'r') as f:
    earnings_data = json.load(f)

5.2 Verify Data Structure

5.2 验证数据结构

Confirm data includes required fields:
  • ✓ symbol
  • ✓ companyName
  • ✓ date
  • ✓ timing (BMO/AMC/TAS)
  • ✓ marketCap
  • ✓ sector
确认数据包含必填字段:
  • ✓ 股票代码（symbol）
  • ✓ 公司名称（companyName）
  • ✓ 日期（date）
  • ✓ 发布时间（timing，BMO/AMC/TAS）
  • ✓ 市值（marketCap）
  • ✓ 行业（sector）

5.3 Group by Date

5.3 按日期分组

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

5.4 按发布时间子分组

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.
在每个日期下，创建三个子部分:
  1. 盘前发布（BMO）
  2. 盘后发布（AMC）
  3. 未公布时间（TAS）
脚本输出的数据已按发布时间排序，因此保持此顺序。

5.5 Within Each Timing Group

5.5 各发布时间组内排序

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.
脚本输出的公司已按市值降序排序:
  • 超大型公司（>2000亿美元）优先
  • 大型公司（100亿-2000亿美元）次之
  • 中型公司（20亿-100亿美元）最后
此排序确保对市场影响最大的公司排在前面。

5.6 Calculate Summary Statistics

5.6 计算汇总统计

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
计算:
  • 总公司数: 数据集中的公司总数
  • 超大型/大型公司数: 市值≥100亿美元的公司数量
  • 中型公司数: 市值在20亿-100亿美元之间的公司数量
  • 峰值日: 财报发布最多的工作日
  • 行业分布: 按行业统计数量（科技、医疗、金融等）
  • 市值最高的公司: 市值前五的公司

Step 6: Generate Markdown Report

步骤6：生成Markdown报告

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:
bash
python scripts/generate_report.py earnings_data.json
Option B: Save to file:
bash
python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md
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:
markdown
undefined
使用报告生成脚本从JSON数据创建格式化的Markdown报告。
脚本位置:
scripts/generate_report.py
执行方式:
选项A：输出到标准输出:
bash
python scripts/generate_report.py earnings_data.json
选项B：保存到文件:
bash
python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md
脚本功能:
  1. 从JSON文件加载财报数据
  2. 按日期和发布时间（BMO/AMC/TAS）分组
  3. 各组内按市值排序
  4. 计算汇总统计
  5. 生成格式化的Markdown报告
  6. 输出到标准输出或保存到文件
脚本会自动处理所有格式，包括:
  • 正确的Markdown表格结构
  • 日期分组和星期名称
  • 市值排序
  • EPS和营收格式化
  • 汇总统计计算
报告结构:
markdown
undefined

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]
报告生成时间: [当前日期] 数据来源: FMP API（中大型公司，市值>20亿美元） 覆盖周期: 未来7天 总公司数: [数量]

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]
  • 发布财报的总公司数: [总数]
  • 超大型/大型公司（>100亿美元）: [大型公司数量]
  • 中型公司（20亿-100亿美元）: [中型公司数量]
  • 峰值日: [财报最多的工作日]

[Day Name], [Full Date]

[星期X], [完整日期]

Before Market Open (BMO)

盘前发布（BMO）

TickerCompanyMarket CapSectorEPS Est.Revenue Est.
[TICKER][COMPANY][MCAP][SECTOR][EPS][REV]
股票代码公司名称市值行业预期EPS预期营收
[股票代码][公司名称][市值][行业][EPS][营收]

After Market Close (AMC)

盘后发布（AMC）

TickerCompanyMarket CapSectorEPS Est.Revenue Est.
[TICKER][COMPANY][MCAP][SECTOR][EPS][REV]
股票代码公司名称市值行业预期EPS预期营收
[股票代码][公司名称][市值][行业][EPS][营收]

Time Not Announced (TAS)

未公布时间（TAS）

TickerCompanyMarket CapSectorEPS Est.Revenue Est.
[TICKER][COMPANY][MCAP][SECTOR][EPS][REV]
[Repeat for each day of week]
股票代码公司名称市值行业预期EPS预期营收
[股票代码][公司名称][市值][行业][EPS][营收]
[按星期重复]

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]
  1. [公司名称] ([股票代码]) - [市值] - [日期] [时间]
  2. [公司名称] ([股票代码]) - [市值] - [日期] [时间]
  3. [公司名称] ([股票代码]) - [市值] - [日期] [时间]

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]
  • 交易量高峰日: [有多只大型公司发布财报的日期]
  • 盘前关注: [可能影响市场的BMO公司]
  • 盘后关注: [可能影响市场的AMC公司]

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
  • BMO (Before Market Open): 通常在美东时间早上6:00-8:00发布，早于9:30的开盘时间
  • AMC (After Market Close): 通常在美东时间下午4:00-5:00发布，晚于4:00的收盘时间
  • TAS (Time Not Announced): 具体时间尚未公布 - 请关注公司投资者关系页面

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.
  • 市值分类:
    • 超大型公司: >2000亿美元
    • 大型公司: 100亿-2000亿美元
    • 中型公司: 20亿-100亿美元
  • 筛选标准: 本报告包含市值20亿美元及以上的中大型公司，且财报发布时间在未来一周内。
  • 数据来源: Financial Modeling Prep (FMP) API
  • 数据时效性: 财报日期和时间可能发生变化。请通过公司投资者关系网站核实关键日期的最新信息。
  • EPS和营收预期: 来自FMP API的分析师共识预期。实际结果将在财报日公布。

Additional Resources

额外资源

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**:
- 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
本报告使用FMP财报日历API生成，筛选市值>20亿美元的中大型公司。数据截至报告生成时间。请始终通过公司官方渠道核实财报日期。

**格式最佳实践**:
- 使用Markdown表格提升可读性
- 如需要，为重要公司名称（超大型公司）加粗
- 市值使用易读格式（$3.0T、$150B、$5.2B）- 脚本已自动格式化
- 按日期→发布时间的逻辑分组
- 在顶部添加摘要部分以便快速浏览
- 尽可能包含EPS和营收预期

Step 7: Quality Assurance

步骤7：质量保证

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
在最终确定报告前，进行验证:
数据质量检查:
  1. ✓ 所有日期均在目标周内（未来7天）
  2. ✓ 所有公司均包含市值
  3. ✓ 每家公司都有发布时间（BMO/AMC/TAS）
  4. ✓ 各组内公司按市值降序排列
  5. ✓ 汇总统计准确
  6. ✓ 报告生成日期明确标注
  7. ✓ 尽可能包含EPS和营收预期
完整性检查:
  1. ✓ 包含目标周的所有天数（即使当天无财报）
  2. ✓ 未遗漏知名大公司（如有需要，通过外部来源验证）
  3. ✓ 尽可能包含行业信息
  4. ✓ 包含发布时间说明部分
  5. ✓ 注明数据来源（FMP API）
格式检查:
  1. ✓ Markdown表格格式正确
  2. ✓ 日期格式统一
  3. ✓ 市值单位统一（B代表十亿，T代表万亿）
  4. ✓ 所有部分遵循模板结构
  5. ✓ 无占位文本（[PLACEHOLDER]）残留
  6. ✓ EPS和营收预期格式正确

Step 8: Save and Deliver Report

步骤8：保存并交付报告

Save the generated report with an appropriate filename:
Filename Convention:
earnings_calendar_[YYYY-MM-DD].md
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:
✓ 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)
使用合适的文件名保存生成的报告:
文件名规范:
earnings_calendar_[YYYY-MM-DD].md
示例: 
earnings_calendar_2025-11-02.md
文件名中的日期代表报告生成日期，而非财报所在周。
交付:
  • 将Markdown文件保存到工作目录
  • 告知用户报告已生成
  • 提供关键发现的简要摘要（例如：“下周将有45家公司发布财报，苹果和微软将在周一发布”）
示例摘要:
✓ 财报日历报告已生成: earnings_calendar_2025-11-02.md

2025年11月3日-9日一周摘要:
- 45家公司将发布财报
- 28家超大型/大型公司，17家中型公司
- 峰值日: 周四（15家公司）
- 重点公司: 苹果（周一盘后）、微软（周二盘后）、特斯拉（周三盘后）

市值前五的公司:
1. 苹果 (AAPL) - $3.0T - 11月4日 AMC
2. 微软 (MSFT) - $2.8T - 11月5日 AMC
3. 谷歌 (GOOGL) - $1.8T - 11月7日 AMC
4. 亚马逊 (AMZN) - $1.6T - 11月8日 AMC
5. 特斯拉 (TSLA) - $800B - 11月6日 AMC

Fallback Mode (Step 8 Alternative): Manual Data Entry

fallback模式（步骤8替代方案）：手动输入数据

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:
  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"
如果无法使用API或用户选择跳过API:
提供手动输入说明:
由于无法使用FMP API，您可以手动收集财报数据:

1. 访问Finviz: https://finviz.com/screener.ashx?v=111&f=cap_midover%2Cearningsdate_nextweek
2. 或Yahoo Finance: https://finance.yahoo.com/calendar/earnings
3. 记录下周将发布财报的公司

请提供每家公司的以下信息:
- 股票代码
- 公司名称
- 财报日期
- 发布时间（BMO/AMC/TAS）
- 市值（约数）
- 行业

我会将其格式化为标准的财报日历报告。
处理手动输入:
  1. 解析用户提供的财报数据
  2. 按日期、发布时间和市值整理
  3. 使用相同模板生成报告
  4. 在报告中注明: "数据来源: 手动输入"

Use Cases and Examples

使用场景示例

Use Case 1: Weekly Review (Primary Use Case)

场景1：每周回顾（主要场景）

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:
    bash
    python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json
  6. Generate markdown report:
    bash
    python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md
  7. Notify user with summary
Complete One-Liner:
bash
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.md
用户请求: "获取下周的财报日历"
工作流程:
  1. 获取当前日期（例如：2025年11月2日）
  2. 计算目标周（2025年11月3日-9日）
  3. 加载FMP API指南
  4. 检测/请求API密钥
  5. 获取财报数据:
    bash
    python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json
  6. 生成Markdown报告:
    bash
    python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md
  7. 向用户发送摘要
完整单行命令:
bash
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.md

Use Case 2: Focused on Specific Day

场景2：聚焦特定日期

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
用户请求: "周一有哪些公司发布财报？"
工作流程:
  1. 获取当前日期并确定下周一（例如：2025年11月4日）
  2. 获取整周数据（同场景1）
  3. 生成完整报告，但突出周一的部分
  4. 口头总结周一的财报重点

Use Case 3: Mega-Cap Focus

场景3：聚焦超大型公司

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
用户请求: "展示下周市值超过1000亿美元的公司财报"
工作流程:
  1. 获取完整财报数据（脚本已筛选>20亿美元的公司）
  2. 按常规流程处理和整理
  3. 生成报告时，在顶部添加“超大型公司聚焦”部分
  4. 筛选表格仅显示市值>1000亿美元的公司
  5. 注意: 仍需在附录中包含完整数据供参考

Use Case 4: Sector-Specific

场景4：特定行业

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
用户请求: "下周有哪些科技公司发布财报？"
工作流程:
  1. 获取完整财报数据
  2. 按常规流程处理和整理
  3. 筛选行业为“Technology”的结果
  4. 生成聚焦科技行业的报告
  5. 注意: 模板结构保持不变，仅内容被筛选

Troubleshooting

故障排除

Problem: API key not working

问题：API密钥无效

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
解决方案:
  • 验证API密钥是否正确（仔细复制粘贴）
  • 检查API密钥是否激活（登录FMP控制台）
  • 确保密钥前后无多余空格
  • 尝试从FMP控制台生成新的API密钥

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
解决方案:
  • 验证日期范围是否为未来（非过去日期）
  • 检查日期格式是否为YYYY-MM-DD
  • 尝试扩大日期范围（例如：14天而非7天）
  • 确认该周确实有公司公布了财报日期

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
解决方案:
  • 公司可能尚未公布财报日期
  • 部分公司会很晚才公布（财报前1-2天）
  • 通过公司投资者关系网站交叉验证
  • 公司市值可能已降至20亿美元以下

Problem: Rate limit hit (429 error)

问题：触发速率限制（429错误）

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
解决方案:
  • 免费套餐: 每日250次调用
  • 每份每周报告约使用3-5次API调用
  • 检查是否有其他工具/脚本使用同一API密钥
  • 等待24小时重置速率限制
  • 如果频繁使用，考虑升级到付费套餐

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 ...
解决方案:
  • 验证是否安装了Python 3: 
    python3 --version
  • 安装requests库: 
    pip install requests
  • 检查脚本是否有执行权限: 
    chmod +x fetch_earnings_fmp.py
  • 明确使用python3执行: 
    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
✓ 始终先获取当前日期再进行任何数据获取 ✓ 使用FMP API作为主要数据源以确保可靠性 ✓ 在CLI中使用环境变量存储API密钥 ✓ 按市值排序以优先显示高影响公司 ✓ 按日期→发布时间的逻辑分组 ✓ 包含汇总统计以便快速浏览 ✓ 在报告页脚注明数据来源 ✓ 使用清晰的Markdown表格提升可读性 ✓ 包含发布时间说明部分以明确含义 ✓ 注明数据时效性和可能的变化 ✓ 尽可能包含EPS和营收预期

Don'ts

不建议

✗ 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
✗ 不要在未根据当前日期计算的情况下假设“下周”的范围 ✗ 不要省略发布时间信息（BMO/AMC/TAS） ✗ 不要在报告中混合使用不同的日期格式（保持统一） ✗ 除非特别要求，否则不要包含微型/小型公司 ✗ 不要忘记在各组内按市值排序 ✗ 不要在对话或报告中分享API密钥 ✗ 不要包含本周或过去日期的财报 ✗ 不要在未进行质量检查的情况下生成报告 ✗ 不要将API密钥提交到版本控制系统

Security Notes

安全说明

API Key Security

API密钥安全

Important Reminders:
  1. ✓ Use free tier API keys for testing
  2. ✓ Rotate keys regularly
  3. ✓ Don't share conversations containing API keys
  4. ✓ Set API key as environment variable for CLI
  5. ✓ Keys provided in chat are session-only (forgotten after session ends)
  6. ✗ Never commit API keys to Git repositories
  7. ✗ Never use production API keys with sensitive data access
Best Practice: For Claude Code (CLI), always use environment variable:
bash
undefined
重要提醒:
  1. ✓ 测试时使用免费套餐的API密钥
  2. ✓ 定期轮换密钥
  3. ✓ 不要分享包含API密钥的对话
  4. ✓ 在CLI中使用环境变量存储API密钥
  5. ✓ 聊天中提供的密钥仅在会话内有效（会话结束后遗忘）
  6. ✗ 永远不要将API密钥提交到Git仓库
  7. ✗ 永远不要使用具有敏感数据访问权限的生产环境API密钥
最佳实践: 对于Claude Code (CLI)，始终使用环境变量:
bash
undefined

Add to ~/.zshrc or ~/.bashrc

添加到~/.zshrc或~/.bashrc

export FMP_API_KEY="your-key-here"

For Claude Web, understand that:
- API key entered in chat is temporary
- Stored only in conversation context
- Not saved to disk
- Forgotten when session ends
export FMP_API_KEY="您的密钥"

对于Claude Web，请了解:
- 聊天中输入的API密钥是临时的
- 仅存储在对话上下文
- 不会保存到磁盘
- 会话结束后将被遗忘

Resources

资源

FMP API:
Supplementary Sources (for verification):
Skill Resources:
  • FMP API Guide: 
    references/fmp_api_guide.md
  • Python Script: 
    scripts/fetch_earnings_fmp.py
  • Report Template: 
    assets/earnings_report_template.md
FMP API:
补充数据源（用于验证）:
技能资源:
  • FMP API指南: 
    references/fmp_api_guide.md
  • Python脚本: 
    scripts/fetch_earnings_fmp.py
  • 报告模板: 
    assets/earnings_report_template.md

Summary

总结

This 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.
本技能提供了一种可靠的、基于API的美股每周财报日历生成方法。通过使用FMP API，确保数据结构化、准确，并包含EPS/营收预期等额外洞察。多环境支持使其适用于CLI、Desktop和Web场景，而fallback模式确保即使无法使用API也能正常工作。
核心工作流程: 日期计算 → API密钥设置 → API数据获取 → 数据处理 → 报告生成 → 质量检查 → 交付
输出: 清晰、结构化的Markdown报告，按日期/发布时间/市值分组展示财报信息，包含汇总统计和交易注意事项。