xtb-investment-tools/skills/xtb-portfolio-review/SKILL.md

name, description

name	description
xtb-portfolio-review	Use when analyzing XTB brokerage .xlsx exports, creating investment portfolio analysis reports, generating HTML/CSV outputs, validating cash reconciliation, reviewing holdings, dividends, risk, income, performance, or explaining report outputs from main.py.

XTB Portfolio Review

Use this skill to run and assess XTB portfolio reviews from a copied skill folder. The skill bundles the required Python tools in scripts/, so it can run without the original repository as long as Python dependencies are installed.

Workflow

1. Identify the target workbook. If the user does not name one and exactly one non-lock .xlsx exists in the current working directory, use it.
2. Ensure dependencies are available: <skill-folder>/scripts/setup-env.sh
3. Validate the bundled tools: <skill-folder>/scripts/validate-review.sh
4. Generate the review from the directory where outputs should be written: <skill-folder>/scripts/run-review.sh <report.xlsx> Add --csv only when the user explicitly asks for CSV exports.
5. Inspect the results/<stem>_review.html output. If CSV export was requested, also inspect outputs named from the workbook stem, especially _holdings.csv, _cash_flows.csv, _performance.csv, _income.csv, and _evolution.csv.
6. Check whether computed ending cash reconciles to the broker Total row within EUR/USD/etc. 0.01.
7. Report findings with caveats: cost-priced tickers, missing live prices, cash mismatch, XIRR availability, concentration, income tax drag, and any generated file paths.

Bundled Tools

• scripts/main.py: standalone XTB portfolio review generator.
• scripts/html_charts.py: offline Chart.js report rendering helper.
• scripts/assets/chartjs.umd.min.js: vendored Chart.js bundle for self-contained HTML.
• scripts/run-review.sh: shell wrapper that runs the bundled review tool. It writes only the HTML report by default; pass --csv to also write CSV outputs.
• scripts/validate-review.sh: dependency and asset smoke check.
• scripts/setup-env.sh: creates .venv in the current working directory and installs dependencies.
• scripts/requirements.txt: Python dependencies.

References

• Read references/xtb-format.md when parsing behavior, report assumptions, or XTB edge cases matter.
• Read references/validation-checklist.md before claiming a generated portfolio review is correct or ready to use.

Guardrails

• Do not treat the generated report as investment advice; describe what the tool computed and the data-quality limits.
• Prefer the bundled validation script and generated outputs over eyeballing the HTML alone.
• Preserve offline/self-contained HTML behavior; do not introduce CDN dependencies when modifying the report.