mirror of
https://github.com/farcasclaudiu/xtb-investment-tools.git
synced 2026-06-22 05:01:57 +03:00
farcasclaudiu
68cfec926e
- Created requirements.txt for dependencies including pandas, numpy, openpyxl, and yfinance. - Added setup-env.sh script to set up a Python virtual environment and install required packages. - Introduced validate-export.sh script to validate the exporter module and check expected fields. - Implemented test cases in test_portfolio_performance_exporter.py to ensure correct CSV export functionality and data handling.
189 lines
6.3 KiB
Markdown
189 lines
6.3 KiB
Markdown
# Install Skills For Agents
|
|
|
|
This file is written for LLM agents and coding assistants. Follow it when a user asks you to install, use, or copy the XTB portfolio skills from this repository.
|
|
|
|
The repository ships three standalone, harness-neutral skill folders:
|
|
|
|
- `skills/xtb-portfolio-review`
|
|
- `skills/xtb-wealthfolio-export`
|
|
- `skills/xtb-portfolio-performance-export`
|
|
|
|
Each skill folder is self-contained: it includes `SKILL.md`, references, runnable scripts, Python source files, requirements, and offline Chart.js assets where needed. Users may copy a single skill folder without cloning the full repository.
|
|
|
|
## Choose The Installation Path
|
|
|
|
Use one of these paths based on the user's agent harness.
|
|
|
|
| Harness | Recommended action |
|
|
| ------- | ------------------ |
|
|
| Codex | Copy the desired skill folder into `~/.codex/skills/`. |
|
|
| Claude or Claude Code | Copy the desired skill folder into the user's configured skills/instructions directory, or keep it in the project and read `SKILL.md` before use. |
|
|
| Cursor, Aider, OpenHands, generic LLM | Keep/copy the skill folder anywhere accessible and explicitly read `SKILL.md` before running scripts. |
|
|
| Unknown harness | Do not assume a special install location. Use the skill folder directly. |
|
|
|
|
## Install From This Repository
|
|
|
|
Run these commands from the repository root.
|
|
|
|
For Codex:
|
|
|
|
```bash
|
|
mkdir -p "$HOME/.codex/skills"
|
|
cp -R skills/xtb-portfolio-review "$HOME/.codex/skills/"
|
|
cp -R skills/xtb-wealthfolio-export "$HOME/.codex/skills/"
|
|
cp -R skills/xtb-portfolio-performance-export "$HOME/.codex/skills/"
|
|
```
|
|
|
|
For a generic agent workspace, copy the skill folders to a user-chosen directory:
|
|
|
|
```bash
|
|
mkdir -p ./agent-skills
|
|
cp -R skills/xtb-portfolio-review ./agent-skills/
|
|
cp -R skills/xtb-wealthfolio-export ./agent-skills/
|
|
cp -R skills/xtb-portfolio-performance-export ./agent-skills/
|
|
```
|
|
|
|
If only one workflow is needed, copy only that folder.
|
|
|
|
## Install From A Copied Skill Folder
|
|
|
|
If the user already has only one copied skill folder, no repository files are required. Work from the directory where the user's XTB workbook and future `results/` folder should live.
|
|
|
|
For portfolio review:
|
|
|
|
```bash
|
|
/path/to/xtb-portfolio-review/scripts/setup-env.sh
|
|
/path/to/xtb-portfolio-review/scripts/validate-review.sh
|
|
/path/to/xtb-portfolio-review/scripts/run-review.sh /path/to/report.xlsx
|
|
```
|
|
|
|
Append `--csv` to `run-review.sh` only when the user explicitly asks for the
|
|
per-section CSV exports.
|
|
|
|
For Wealthfolio export:
|
|
|
|
```bash
|
|
/path/to/xtb-wealthfolio-export/scripts/setup-env.sh
|
|
/path/to/xtb-wealthfolio-export/scripts/validate-export.sh
|
|
/path/to/xtb-wealthfolio-export/scripts/export-wealthfolio.sh /path/to/report.xlsx
|
|
```
|
|
|
|
For Portfolio Performance export:
|
|
|
|
```bash
|
|
/path/to/xtb-portfolio-performance-export/scripts/setup-env.sh
|
|
/path/to/xtb-portfolio-performance-export/scripts/validate-export.sh
|
|
/path/to/xtb-portfolio-performance-export/scripts/export-portfolio-performance.sh /path/to/report.xlsx
|
|
```
|
|
|
|
The setup scripts create or reuse `.venv` in the current working directory. If network access or package installation requires approval, ask before running `setup-env.sh`.
|
|
|
|
## Use Without Installing
|
|
|
|
If you cannot copy files, use the skill in place:
|
|
|
|
1. Read the relevant `SKILL.md` completely.
|
|
2. Read referenced files only when the skill tells you to.
|
|
3. Run the bundled validation script.
|
|
4. Run the bundled workflow script.
|
|
5. Report generated output paths and data-quality caveats to the user.
|
|
|
|
Example prompts a user can give an agent:
|
|
|
|
```text
|
|
Read skills/xtb-portfolio-review/SKILL.md and use that skill to generate a portfolio report for my XTB export.
|
|
```
|
|
|
|
```text
|
|
Read skills/xtb-wealthfolio-export/SKILL.md and use that skill to create a Wealthfolio CSV from my XTB export.
|
|
```
|
|
|
|
```text
|
|
Read skills/xtb-portfolio-performance-export/SKILL.md and use that skill to create Portfolio Performance CSV files from my XTB export.
|
|
```
|
|
|
|
## Skill Contents
|
|
|
|
Expected portable structure:
|
|
|
|
```text
|
|
skills/
|
|
xtb-portfolio-review/
|
|
SKILL.md
|
|
references/
|
|
scripts/
|
|
setup-env.sh
|
|
validate-review.sh
|
|
run-review.sh
|
|
main.py
|
|
html_charts.py
|
|
requirements.txt
|
|
assets/
|
|
|
|
xtb-wealthfolio-export/
|
|
SKILL.md
|
|
references/
|
|
scripts/
|
|
setup-env.sh
|
|
validate-export.sh
|
|
export-wealthfolio.sh
|
|
exporter.py
|
|
main.py
|
|
html_charts.py
|
|
requirements.txt
|
|
assets/
|
|
|
|
xtb-portfolio-performance-export/
|
|
SKILL.md
|
|
references/
|
|
scripts/
|
|
setup-env.sh
|
|
validate-export.sh
|
|
export-portfolio-performance.sh
|
|
exporter.py
|
|
main.py
|
|
html_charts.py
|
|
requirements.txt
|
|
```
|
|
|
|
Do not require the root-level `main.py`, `exporter.py`,
|
|
`portfolio_performance_exporter.py`, or `html_charts.py` for copied skill
|
|
usage. Those root files are repository compatibility shims only.
|
|
|
|
## Verification Commands
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
skills/xtb-portfolio-review/scripts/validate-review.sh
|
|
skills/xtb-wealthfolio-export/scripts/validate-export.sh
|
|
skills/xtb-portfolio-performance-export/scripts/validate-export.sh
|
|
```
|
|
|
|
If the full repository test suite is available:
|
|
|
|
```bash
|
|
.venv/bin/python -m pytest -q
|
|
```
|
|
|
|
Successful validation means the Python dependencies are importable and the bundled skill tools can be loaded. A successful portfolio or export run is still the final check for a specific workbook.
|
|
|
|
## Operational Rules For Agents
|
|
|
|
- Prefer the bundled scripts inside the skill folder over re-implementing behavior.
|
|
- Keep generated files in the user's current working directory, usually under `results/`.
|
|
- Do not upload or expose XTB workbooks; they can contain personal financial data.
|
|
- Do not present portfolio output as investment advice. Report computed values, assumptions, and caveats.
|
|
- If dependencies are missing, propose running `scripts/setup-env.sh`.
|
|
- If package installation needs network access or elevated permissions, ask the user first.
|
|
- If a workbook path is ambiguous, ask the user which `.xlsx` file to use.
|
|
- If validation fails, report the failing command and the actionable error.
|
|
|
|
## Copy-Paste Installation Request
|
|
|
|
A user can paste this to another agent:
|
|
|
|
```text
|
|
Install the XTB agent skills from this repository. Read INSTALL_FOR_AGENTS.md, copy the needed folder from skills/ into your skill or instruction directory if your harness supports that, run the skill's setup and validation scripts, then use the relevant SKILL.md workflow for my XTB workbook.
|
|
```
|