git:20260614.5208b4c to git:20260615.1734111

30 added, 48 removed. Audit A to A.

---

name: xlsx-financials

multi_ticker_semantics: single_target

description: Produce formatted .xlsx financial statement workbooks from XBRL statement data. Uses Bash + openpyxl (Python) following Anthropic FSI xlsx-author conventions for professional Excel output with calculation arc cross-validation.

temporal_scope:

default_quarters: 4

max_quarters: 12

description: "Fiscal years for statement rendering; default latest year"

allowed_tools:

- search_xbrl_facts

- get_statement

- get_statement_structure

- list_xbrl_concepts

+ - Bash

retrieval_scope: structured_only

min_tool_diversity: 2

---

# xlsx-financials

Shared skill for producing formatted Excel workbooks from XBRL financial statement data. Invoked as a sub-skill by financial modeling and analysis skills. Centralizes formatting, formula auditing, and calculation arc cross-validation in one place.

## Triggers

- Produce Excel financial statements for {ticker}

- Generate .xlsx workbook from XBRL data

- Export income statement to Excel

- Export balance sheet to Excel

- Export cash flow statement to Excel

- Render financial statements as spreadsheet

- Create formatted financial workbook

- Build .xlsx from get_statement output

- Financial model Excel export

- Statement Excel output

## Defaults

| Parameter | Default | Notes |

|-----------|---------|-------|

| statement_type | income_statement | income_statement, balance_sheet, cash_flow, equity, oci |

| fiscal_year | (latest available) | Integer year |

| include_calculations | true | Include calculation arc weights for cross-validation |

## Methodology

### Retrieval Scope

`structured_only` — this skill wraps the XBRL `get_statement` endpoint and does not perform document search. It is purely a data-to-Excel rendering pipeline.

### Retrieval Strategy

- 1. **Fetch statement structure**: call `get_statement_structure/{ticker}?statement_type=<type>&fiscal_year=<YYYY>&include_calculations=true` to retrieve the hierarchical concept tree from `gold.xbrl_presentation` (3.8M rows) with `order_in_parent` and calculation arc weights .

- 2. **Fetch rendered statement**: call `get_statement/{ticker}?statement_type=<type>&fiscal_year=<YYYY>` for the period-column-formatted financial data.

- 3. **Structure for Excel**: map the hierarchical concept tree to Excel rows with proper indentation levels, parent-child grouping, and subtotal rows.

- 4. **Build workbook**: write a Python script using `openpyxl` (following Anthropic FSI xlsx-author conventions) and execute via Bash.

+ See `contracts/retrieval.md` for the canonical decision tree; skill-specific retrieval detail is in `references/methodology.md`.

### Temporal Scope

Default: latest fiscal year (max 12). Users can request specific fiscal years for multi-year comparison.

### Tool Allowlist

- `get_statement`: fetches rendered financial statement data with period columns

- `get_statement_structure`: fetches hierarchical concept tree with `order_in_parent`

- `search_xbrl_facts`: fallback for individual concept values

- `list_xbrl_concepts`: concept discovery when structure tree is unavailable

- **Excel generation**: uses `Bash` to execute a Python script with `openpyxl` (following Anthropic FSI xlsx-author conventions)

### Protocol

- 1. **Receive request from parent skill**: parent skill (dcf, comps, 3-statement, recent-quarter, earnings-preview) invokes this skill with `ticker`, `statement_type`, and `fiscal_year`.

- 2. **Fetch statement structure** via `get_statement_structure` — get the hierarchical concept tree with indentation levels.

- 3. **Fetch statement data** via `get_statement` — get the period-column financial values.

- 4. **Apply formatting rules** per `style.md`:

- - Currency: $#,##0.0 with B/M/K auto-detection

- - Percentages: 0.0%

- - Frozen header row (row 1)

- - Parent concepts: **bold**

- - Child concepts: indented 2 spaces per level

- - Subtotal rows: bold with top border

- 5. **Inject calculation arcs**: when `include_calculations=true`, add a hidden "Validation" sheet with the calculation arc cross-check: parent expected value vs sum of weighted children .

- 6. **Write workbook** via `Bash` executing a Python `openpyxl` script: write a self-contained `.py` script, execute with `python3`, output to the path specified by the parent skill. Follow Anthropic FSI conventions: blue=hardcoded input, black=formula, green=cross-sheet link, named ranges, Checks tab.

+ Step-by-step execution detail is in `references/methodology.md`.

## Deliverable Chain

**Inputs** → **Build** → **Validate** → **Output** → **Next**

1. **Inputs**: resolved ticker + structured facts (`search_xbrl_facts`, `get_company_financials`) and any filing pages from the three-layer protocol.

- 2. **Build**: assemble the workbook/deck spec and call `xlsx.build` / `pptx.build` (office plane).

- 3. **Validate**: run `xlsx.audit` (or recalc) and the `## Validation Gates` below.

+ 2. **Build**: write a self-contained Python script using `openpyxl` that creates the workbook per `## Output Structure`; execute via `Bash: python3 script.py`; verify the `.xlsx` exists at the output path. If `import openpyxl` fails, fall back to the `.md` summary with `data_availability: degraded` (see `contracts/office-tooling.md`).

+ 3. **Validate**: run the calculation-arc cross-check in the workbook Checks tab and the `## Validation Gates` below.

4. **Output**: write the artifact path per `## Output File`.

5. **Next**: append to `agentii.md`; hand off to a downstream pitch/review skill if requested.

## Output File

- Write the final deliverable to `{ticker}/{YYYY-MM-DD_HHMM}_xlsx-financials_{affix}.md` .

+ Primary deliverable: `{ticker}/{YYYY-MM-DD_HHMM}_statement-{type}.xlsx` — the formatted Excel workbook (the primary artifact).

+ Companion summary: `{ticker}/{YYYY-MM-DD_HHMM}_xlsx-financials_summary.md` — validation report with calculation-arc results, coverage gaps, and key citations. The `.md` summary is a companion, NOT a substitute for the `.xlsx`.

## Output Structure

- The final deliverable is an `.xlsx` workbook with proper number formatting, frozen headers, and calculation arc cross-validation. Output conventions follow the Anthropic FSI xlsx-author standard (blue font = hardcoded inputs, black font = formulas).

+ The deliverable is a structured markdown report written to the path in `## Output File`. Full section-by-section template (headings, tables, and field definitions) lives in `references/output-structure.md`. Required elements:

- ### Single-Ticker

- ```

- {ticker}/{YYYY-MM-DD_HHMM}_statement-{type}.xlsx

- ```

- Example: `LLY/2026-06-03_1430_statement-income.xlsx`

+ 1. **Executive Summary** — headline conclusions (≤200 words).

+ 2. **Core analysis sections** — per this skill's methodology and analyst modes.

+ 3. **Data classification** — tag findings `[FACT]` / `[DEDUCTED]` / `[VIEW]` per `contracts/snapshot-synthesis.md`.

+ 4. **Coverage Gaps & Citations** — inline `/v/` citations are PRIMARY (immediately after each fact); the bottom **Citations** section is a non-duplicative roll-up index.

+ 5. **Output frontmatter** — emit the FR-090 structured block per `contracts/output-frontmatter-schema.md`.

- ### Multi-Ticker

- ```

- _cross/{slug}_{YYYY-MM-DD_HHMM}_statement-{type}.xlsx

- ```

- Example: `_cross/LLY-vs-peers_2026-06-03_1430_statement-income.xlsx`

+ **Citations & memory**: follow `contracts/citation-and-memory.md` — ≥1 citation per 200 words; every material fact, table row, and metric is immediately followed by its inline clickable `https://agentii.ai/v/{ticker}/{citation_id}/{N}` link; a bottom **Citations** section provides a non-duplicative roll-up index; the closing TUI reply includes a compact **Key Citations** list (headline 5–10 facts) of clickable `/v/` URLs; and append the run to `agentii.md` per `contracts/agentii-md-schema.md`.

## xlsx-author Conventions

- Following Anthropic FSI `xlsx-author` conventions:

- - **Blue font** = hardcoded input values (statement data fetched from API)

- - **Black font** = formulas (subtotals, growth rates, validation checks)

- - **Green font** = links/references to other sheets

- - **Named ranges** for key metrics (Revenue, NetIncome, TotalAssets) to enable cross-sheet references

- - **Checks tab**: include a "Checks" sheet with TRUE/FALSE validation:

- - BS balance: Assets = Liabilities + Equity

- - Subtotal tie-out: parent = sum of children per calculation arcs

- - Period consistency: all periods have matching concept coverage

+ Excel formatting conventions are in `references/methodology.md` and `contracts/office-tooling.md`.

## Validation Gates

1. **calculation arc cross-validation **: parent concept values MUST equal the weighted sum of children per `gold.xbrl_calculations`. Discrepancies ≥1% flagged in Checks tab. *If failed*: If ≥5% discrepancy: mark Checks tab cell red, add comment with the XBRL-expected value.

2. **statement structure integrity**: all concepts in the rendered statement MUST exist in the presentation tree (`gold.xbrl_presentation`). Missing concepts flagged. *If failed*: list missing concepts in a "Coverage Notes" sheet.

3. **period alignment**: all period columns MUST have data for the same set of concepts. Gaps flagged. *If failed*: fill empty cells with "N/R" (not reported) and note in Coverage Notes.

## Tool Fallbacks

- |------|-------------|-----------------|---------------------|

- | `get_statement` | Endpoint unavailable | Use `search_xbrl_facts` with individual concept queries; structure manually from `get_statement_structure` tree | "Statement endpoint unavailable; built from individual XBRL facts" |

+ Per-tool failure modes and fallback actions are tabulated in `references/tool-fallbacks.md`.

## Preflight

- !curl -s -o /dev/null -w "%{http_code}" --max-time 2 https://mcp.agentii.ai/mcp/health 2>/dev/null || echo "UNREACHABLE"

+ Run the canonical pre-flight sequence — MCP health probe, ticker resolution, workspace `style.md` override, memory load, and coverage check. See `contracts/preflight.md`.

- **Agent Call Tracing**: The first tool you call will return a `_run_id` in its result. On every subsequent tool call, include HTTP header `X-Agentii-Trace: agent={skill_name}; parent={caller_name}; instance={instance_label}`. The MCP server will inject run_id, depth, and user_id automatically. When spawning parallel sub-agents of the same type, assign each a unique instance label (e.g., equity-research-1, equity-research-2). See `contracts/x-agentii-trace-header.md` for the full contract.

+ Include the `X-Agentii-Trace` header on every tool call per `contracts/x-agentii-trace-header.md`.

+ ## Memory & Snapshot

+ - **Memory load** (pre-flight): load prior workspace context for the ticker before retrieval — see `contracts/memory-load.md`.

+ - **Structured output frontmatter**: emit the FR-090 block (`key_metrics`, `conclusions`, `facts_count`, `deducted_count`, `views_count`, `citation_count`) per `contracts/output-frontmatter-schema.md`.

+ - **Snapshot synthesis**: after writing the deliverable, update the two-tier snapshot and classify findings as `[FACT]`/`[DEDUCTED]`/`[VIEW]` — see `contracts/snapshot-synthesis.md`.

+ - **Session archival**: record the run under `sessions/{YYYY-MM-DD}/` and update `sessions/INDEX.md` per `contracts/session-format.md`.

+ ## Final Summary (TUI)

+ End the closing chat reply with a compact **Key Citations** list (headline 5–10 facts), each a clickable `https://agentii.ai/v/{ticker}/{citation_id}/{N}` link, so the user can cmd+click straight to the exact SEC page. See `contracts/citation-and-memory.md`.

## Error Handling

|-------------|-----------|--------|---------------------|

| No XBRL data for ticker | `get_statement` returns empty | Halt; suggest checking coverage | "No XBRL statement data for {ticker} in fiscal year {year}." |

| Statement type not available | `get_statement_structure` returns empty tree | Try alternative statement types | "{type} not available; available types: {available_types}." |

| Non-USD currency | `unit` field is not USD | Annotate with ISO 4217 code; apply currency label to all values | "⚠ {ticker} reports in {currency}. Values NOT converted to USD." |

| Calculation arc mismatch | Checks tab shows ≥5% discrepancy | Flag in Checks tab with red cell; note in output | "Calculation arc validation found {n} discrepancies ≥5%." |