sec-revenue-change-analysis-method - SKILL.md Agent Skill

name: sec-revenue-change-analysis-method description: Use this skill for SEC, XBRL, companyfacts, ticker, CIK, revenue, quarterly financials, 营收变化, 财报分析, revenue change, quarterly financial analysis, and Markdown report workflows where an Agent needs official SEC XBRL API data and deterministic intermediate inputs for recent quarter-over-quarter revenue change analysis of a US listed company.

SEC Revenue Change Analysis Method

When to use

Use this skill when the user asks about a US SEC-reporting company's ticker and wants to analyze how the most recent quarter's revenue changed versus the prior quarter, using SEC XBRL companyfacts data.

Trigger examples include SEC, XBRL, 上市公司, 财报, 营收变化, revenue change, quarterly financial analysis, companyfacts, ticker, CIK, and Markdown report.

What this skill does

Fetches ticker to CIK mapping from the official SEC company_tickers.json endpoint.
Fetches company facts from the official SEC XBRL companyfacts endpoint.
Extracts core metrics: revenue, gross_profit, operating_income, and net_income.
Uses this revenue tag whitelist in order: RevenueFromContractWithCustomerExcludingAssessedTax, Revenues, SalesRevenueNet.
Declares revenue structure analysis unsupported in this MVP because it uses SEC companyfacts standard facts only and does not parse XBRL dimensions.
Calculates only revenue_growth, gross_margin, operating_margin, and net_margin.
Calculates optional product/service revenue changes and their contribution to total revenue change when available.
Adds seasonality_check for the current period versus the prior-year same quarter when available. This is only a seasonality/base-effect prompt, not full year-over-year analysis.
Adds period_continuity checks to determine whether selected frames are consecutive quarters.
Selects analysis periods using revenue-available quarterly frames only; supporting metrics must never change the selected periods.
Returns structured JSON intermediate results and evidence_pack for the Agent.
Provides evidence-bound analysis_hints for cautious financial-structure interpretation.

What this skill does not do

It does not directly output a final Markdown report.
It does not call OpenAI, Claude, or any LLM API.
It does not use Yahoo Finance, Alpha Vantage, FMP, Finnhub, Nasdaq Data Link, or any third-party market data API.
It does not parse PDF or HTML filings.
It does not provide investment advice, valuation, price forecasts, buy/sell recommendations, industry analysis, peer comparison, segment analysis, region analysis, MD&A analysis, news analysis, or full year-over-year analysis.
It does not claim to identify true business causes.

Inputs

Primary script:

python scripts/sec_revenue_data.py --ticker AAPL --user-agent "YourApp your_email@example.com"

Python entry point:

from scripts.sec_revenue_data import prepare_analysis_payload

payload = prepare_analysis_payload(
    "AAPL",
    user_agent="YourApp your_email@example.com",
)

For offline testing, pass both companyfacts_json and ticker_json to prepare_analysis_payload. When both are provided, the function does not access the network.

Workflow

Provide a ticker and SEC-compliant User-Agent.
Resolve ticker to 10-digit CIK via https://www.sec.gov/files/company_tickers.json.
Fetch companyfacts via https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json.
Extract only us-gaap facts with USD units.
Prefer 10-Q and 10-K facts.
Use only quarterly frame values matching CY\d{4}Q[1-4].
If duplicate metric and frame records exist, select the record with the latest filed date.
Select the latest two sortable revenue quarters.
Select the latest two sortable revenue frames as previous_period and current_period; set period_selection_basis to revenue_available_frames.
Look up supporting metrics only inside those selected periods and mark missing values as unavailable.
Compute deterministic raw metrics, derived margins, optional revenue component contribution, seasonality check, and period continuity.
Build evidence_pack for Agent-authored Markdown reporting.
Return JSON intermediate results only.

Optional consecutive-period mode:

python scripts/sec_revenue_data.py --ticker AAPL --period-selection-mode latest_consecutive_revenue_available_frames

This mode selects the latest pair of consecutive revenue-available quarterly frames and sets period_selection_basis to latest_consecutive_revenue_available_frames.

Script output contract

The CLI writes JSON to stdout. It must not write Markdown reports.

The payload includes:

company: ticker and CIK.
analysis_scope: source, previous/current periods, period_selection_basis, period_relation, comparison_label, and missing_periods.
raw_metrics: revenue, gross profit, operating income, and net income values where available.
revenue_structure_scope: states that product/service, region, and business-line revenue structure analysis is not supported without filing-specific XBRL dimension parsing or MD&A/note disclosure parsing.
derived_metrics: gross, operating, and net margins with changes in percentage points.
seasonality_check: current quarter versus prior-year same quarter when available.
classification: deterministic signals.
evidence_pack: report-ready structured evidence grouped into primary revenue, period continuity, revenue mix, margin quality, operating efficiency, and seasonality observations.
analysis_hints: evidence-bound interpretation hints with metric name, numeric change, allowed interpretation, and limitation.
warnings: typed warning objects. Supported warning types include missing_revenue_period, missing_supporting_metric, and non_consecutive_periods.
limitations: fixed report limitations.

If revenue is missing, fewer than two sortable revenue quarters exist, the ticker cannot be mapped, or SEC requests fail, the script raises a clear error and the CLI exits non-zero.

Period selection rules:

The latest two analysis periods must be anchored only on revenue availability.
Select the latest two sortable quarterly frame values from revenue facts first.
Do not skip a revenue-available quarter because gross_profit, operating_income, or net_income is missing.
Supporting metrics are looked up only in the already selected previous_period and current_period.
Missing supporting metrics must be represented as unavailable with a missing_supporting_metric warning.

The script no longer attempts to extract product_revenue or service_revenue from simple companyfacts tags. It must not emit a revenue component unavailable warning.

Period continuity rules:

If previous_period and current_period are consecutive frames, period_relation is consecutive_quarters, comparison_label is quarter_over_quarter, and the Agent may use “环比”.
If they are not consecutive, period_relation is non_consecutive_quarters, comparison_label is available_period_to_available_period, missing_periods lists skipped quarters, and the Agent must not use “环比”.
For non-consecutive periods, analysis_hints must include period_continuity_caution.

How the Agent should write the Markdown report

The Agent must use the script JSON plus templates/report_template.md to write the final Markdown document. The report must be authored by the Agent, not by the script.

The Agent must:

Preserve the fixed six-section structure from the template.
Use raw_metrics, revenue_structure_scope, derived_metrics, seasonality_check, classification, evidence_pack, analysis_hints, warnings, and limitations.
Base section 4 only on evidence_pack and analysis_hints.
Write section 4 with fixed subsections: 4.1 总量变化, 4.2 收入结构变化, 4.3 盈利质量变化, and 4.4 季节性与基数影响.
Decide whether “环比” is allowed from analysis_scope.period_relation or evidence_pack.period_continuity_observation.
If period_relation is non_consecutive_quarters, state that the change cannot be interpreted as standard QoQ/环比 and include missing_periods.
If operating_income is missing, explicitly state that current operating margin is unavailable, do not infer operating expense efficiency, and analyze only gross margin and net margin where available.
Use cautious language such as “可能”, “暗示”, and “与……一致”.
Avoid adding external explanations from news, MD&A, segments, regions, pricing, volume, or market data.

Report template

Use templates/report_template.md.

The report title must be:

# 上市公司营收变化分析报告

The fixed sections are:

分析对象与数据来源
营收变化结论
财务结构证据
营收变化的可能原因
- 4.1 总量变化
- 4.2 收入结构变化
- 4.3 盈利质量变化
- 4.4 季节性与基数影响
结论
局限性

Limitations

Only US SEC-reporting companies are supported.
Only the latest two quarters are analyzed.
Only company-level financial metrics are used.
Missing non-revenue metrics produce warnings and continue where possible.
Missing revenue is a hard error.
This skill cannot confirm true business causes.
This skill is not investment advice.

Safety / interpretation rules

Do not output investment advice. Do not say buy, sell, 原因就是, 证明了, 一定是, or 真实原因是.

All interpretations must be framed as possible financial-structure signals only. The script must not directly output a final Markdown report. The Agent must write the Markdown report from the JSON output and templates/report_template.md.