Personal Finance

Parse personal finance CSV exports, validate schema, categorize transactions via local rules, and summarize/report income, expenses, merchants, and categories.

Security Scan

The skill appears to implement the described offline CSV parsing, validation, categorization, and reporting functionality and requests no external credentials, but the packaging has a few inconsistencies you should review before use.

Purpose & Capability

The files and script implement CSV validation, summarization, categorization via local JSON rules, and reporting as claimed. However there are small mismatches: README and SKILL.md mention jq and bash usage while the main script actually invokes embedded Python (requires python3). The README suggests a GitHub clone URL and mentions a 'category' column in examples, but the shipped sample CSV omits a category header (the script handles that). Metadata claims no required binaries, but the runtime requires python3. These are packaging/documentation inconsistencies but not evidence of hidden capabilities.

Instruction Scope

SKILL.md and README state read-only behavior by default, account masking, and offline operation. The script follows that: it reads local CSV/rules, masks account digits in outputs, and only writes when --output is provided. The embedded Python performs file size checks and enforces output-path safety (absolute paths must start in the user's home). Note: absolute-path check only applies to absolute paths — relative output paths are allowed and will be created relative to the current working directory. Also the runtime executes embedded Python code (contained in the script) — review the Python block before running with sensitive data.

Install Mechanism

No install spec is present (instruction-only skill with bundled script and sample files). Nothing downloads or extracts code at install time. This lowers installation risk.

Credentials

The skill declares no required environment variables or credentials and the code does not access external secrets. Minor mismatch: README lists jq as a requirement and package metadata lists no required binaries, but the script needs python3. No network calls are made by the code. Overall the credential/environment access is minimal and proportionate.

Persistence & Privilege

always is false and the skill does not request persistent agent privileges. It only writes files when explicitly given an --output path and does not modify other skills or global agent configuration.

Assessment

This skill is internally consistent with an offline personal-finance utility, but review these before installing or running: 1) The main script runs an embedded Python program — read the Python block to ensure no unexpected behavior. 2) The README mentions jq and bash but the script requires python3; ensure python3 is available. 3) Output safety: absolute output paths are restricted to the user home, but relative paths are allowed and will be created relative to your current directory — avoid running with an output path that could overwrite important files. 4) The package metadata/source/homepage are missing/unspecified; prefer code from a known repository or inspect the files locally before use. 5) Test first on the included sample data and run the validate command before processing real statements. If you need higher assurance, run the script in a sandboxed environment or review the full embedded Python code line-by-line.

Scope & Safety

• Operate on exported bank or credit-card CSVs in a read-only manner by default; no automatic uploads, API calls, or write-backs occur unless an explicit --output path is provided.
• Mask account numbers in all CLI outputs by replacing digits except the final four to keep PII safe for every command.
• Work offline; all logic lives inside personal-finance.sh, config/category-rules.json, and the included sample CSV.

Primary Operations

All commands live in personal-finance.sh at the skill root. Invoke with:

./personal-finance.sh <command> [--csv <path>] [--config <path>] [--output <path>] [--period <period>]

1. validate

Checks that the CSV contains the required fields (date, description, amount, account_number) and that every amount is numeric. Use this before processing new exports to avoid schema drift.

./personal-finance.sh validate --csv sample-data/sample-transactions.csv

2. summarize

Aggregates income (positive amount) and expenses (negative amount) by period. Supports month, quarter, or year (default month). Outputs totals and net flows.

./personal-finance.sh summarize --period month --csv sample-data/sample-transactions.csv

3. categorize

Uses the local rules file (config/category-rules.json) to map descriptions to categories through keyword matching. Prints each transaction with masked accounts and assigned categories. Pass --output to emit a new CSV; otherwise, it stays read-only.

./personal-finance.sh categorize --csv sample-data/sample-transactions.csv --output /tmp/categorized.csv

4. report

Builds insight summaries: top merchants and categories by spend, plus transaction counts. It reuses the same rules file so it can work offline and stay consistent with categorize.

./personal-finance.sh report --csv sample-data/sample-transactions.csv

Configuration & Samples

• config/category-rules.json: keyword-to-category rules that categorize and report share.
• sample-data/sample-transactions.csv: minimal CSV (date, description, merchant, category, amount, account_number) for smoke tests and onboarding.

Keep both files in the skill folder. Adjust the JSON rules for your own merchant vocabulary; the script reloads them each run and never calls external services.