investment-statement-importer-onboarding

Onboard broker statement importers that map PDF or CSV trades into investment_events with calibrated fees and cost basis.

Updated Jun 12, 2026
One-click install
npx skills add https://github.com/ssttkkl/finance-tracker --skill investment-statement-importer-onboarding-ssttkkl
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: investment-statement-importer-onboarding
Source: https://github.com/ssttkkl/finance-tracker/tree/main/.agents/skills/investment-statement-importer-onboarding
Command: npx skills add https://github.com/ssttkkl/finance-tracker --skill investment-statement-importer-onboarding-ssttkkl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Adding a new securities or crypto broker statement importer often produces wrong cash legs, double-counted fees, or incorrect cost basis because developers invent schemas instead of calibrating against real statements. This Skill provides a proven playbook for parsing broker PDFs/CSVs into investment_events with correct SWAP, commission, and CHECKIN semantics. ## Core Features & Use Cases - Fee and cash-leg contract design: Fill a native-field census and fee table from at least five real sample trades before writing any map code, ensuring each fen of fee appears in either the cash leg or the commission field, never both. - CHECKIN-based calibration: Emit cash and per-ticker holdings CHECKIN events from statement headers so end shares, cost price, and cash match the broker statement exactly. - Idempotent import wiring: Wire parsers into the CLI with stable source_identity keys, password-file handling for encrypted PDFs, and dual-backend (SQLite/PostgreSQL) parity. - Use Case: When onboarding a new broker like Futu or IBKR, run the census, fee contract, and calibration loop against a real statement until cash, shares, and cost price reconcile with the statement header. ## Quick Start Ask the AI to onboard a new broker statement importer for your brokerage PDF using the investment statement importer playbook, starting with a native field census and fee contract table.

Frequently Asked Questions about investment-statement-importer-onboarding

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new broker statement importer for PDF or CSV files?

Start with a native field census from a real statement, then fill a fee contract table before writing any map code. Implement parse and map functions in the importers module, wire the CLI source choice, and calibrate against the statement header until cash, shares, and cost price match.

How do I avoid double-counting fees when importing broker trades?

Each fee amount must appear in either the cash leg or the commission field, never both. For net statements like DFZQ, peel the fee into commission and adjust the cash leg so projection cash still equals the net amount; for gross-plus-fee statements like IBKR, use gross as the cash leg and the separate fee as commission.

Why does my imported average cost price not match the broker statement?

Flow replay alone often produces wrong cost basis when history is incomplete. Parse the statement holdings summary and emit a per-ticker CHECKIN event with the broker cost price and share count, since CHECKIN replaces the position rather than applying a delta.

Can this importer handle encrypted broker PDF statements?

Yes, encrypted PDFs are decrypted with qpdf and text is extracted with mutool, with the password supplied via a password file rather than command-line arguments. Never read a PDF directly as UTF-8 text, and fail with an install hint if the external tools are missing.

When should I not use this investment importer approach?

Do not use it for cash, bank, or wallet bills, which belong to the statement-source-onboarding skill, nor for connector API sync or live quote valuation, which are separate features. It also excludes investment relations such as trade lots and FIFO accounting.