Use when collecting financial data for a US public company, assembling DCF inputs, pulling market and filing facts, or grounding downstream analysis in structured yfinance and SEC data.
Use when collecting financial data for a US public company, assembling DCF inputs, pulling market and filing facts, or grounding downstream analysis in structured yfinance and SEC data.
zh_description
用于收集股票、财报、宏观和市场数据并生成分析输入。
version
1.0.0
author
seaworld008
source
in-house
source_url
tags
["collector", "data", "finance", "financial"]
created_at
2026-03-18
updated_at
2026-03-20
quality
4
complexity
intermediate
Financial Data Collector
Collect and validate real financial data for US public companies using free data sources.
Output is a standardized JSON file ready for consumption by other financial skills.
When to Use
Use this skill when the user wants to:
collect filing and market data for a US public company
prepare structured inputs for valuation work
ground downstream analysis in sourced SEC and market data
generate a machine-readable financial dataset instead of a narrative report
Usage
Recommended flow:
collect data
-> validate output
-> preserve source attribution
-> hand off standardized JSON to downstream analysis
For the most portable workflow, prefer the SEC helper first because it uses Python standard library only. Use the yfinance collector when you specifically need market data and analyst estimates.
Critical Constraints
NO FALLBACK values. If a field cannot be retrieved, set it to null with _source: "missing".
Never substitute defaults (e.g., beta or 1.0). The downstream skill decides how to handle missing data.
Data source attribution is mandatory. Every data section must have a _source field.
CapEx sign convention: yfinance returns CapEx as negative (cash outflow). Preserve the original sign. Document the convention in output metadata. Do NOT flip signs.
yfinance FCF ≠ Investment bank FCF. yfinance FCF = Operating CF + CapEx (no SBC deduction). Flag this in output metadata so downstream DCF skills don't overstate FCF.
That path is dependency-light and easier to reuse across AI coding tools.
collect_data.py defaults to --engine auto, which now resolves to the yfinance path when the optional dependency is installed. If not installed, the script fails clearly instead of silently dropping to a weaker live path.
Full schema with all field definitions: references/output-schema.md
<correct_patterns>
Handling Missing Years
if pd.isna(revenue):
result[year] = {"revenue": None, "_source": "yfinance returned NaN — supplement from 10-K"}
# Report missing years to the user. Do NOT skip or fill with estimates.
# ❌ WRONG
beta = info.get("beta", 1.0)
growth = data.get("growth") or0.02# ✅ RIGHT
beta = info.get("beta") # May be None — that's OK
Mistake 2: Assuming All Years Have Data
# ❌ WRONG — 2020-2021 may be NaN
revenue = float(financials.loc["Total Revenue", year_col])
# ✅ RIGHT
value = financials.loc["Total Revenue", year_col]
revenue = float(value) if pd.notna(value) elseNone
Mistake 3: Using yfinance FCF in DCF Models Directly
yfinance FCF does NOT deduct SBC. For mega-caps like META, SBC can be $20-30B/yr, making yfinance FCF ~30% higher than investment-bank FCF. Always flag this in output.
