wikidjon/personal-finance-skill

---

Why This Skill?

Most AI finance tools hallucinate numbers. This one doesn’t.

• Deterministic math — Tax liability, P/L, net worth always computed by tools, never by LLM arithmetic
• Policy engine — Every trade, transfer, and tax move passes finance_policy_check before execution
• Multi-provider — Plaid (banking) + Alpaca (trading) + IBKR (portfolio) + IRS tax forms + Finnhub/SEC/FRED/BLS (market data) + StockTwits/X (sentiment) in one unified model
• Approval gates — No live trades without explicit human confirmation, ever
• Canonical data model — All providers normalize into shared types (Account, Transaction, Position, Liability)
• Works with 40+ AI agents — Claude Code, Cursor, Codex, OpenClaw, Windsurf, and more via the Agent Skills Protocol

---

Install

npx skills add /personal-finance-skill

Or install for specific agents:

npx skills add /personal-finance-skill -a claude-code -a cursor -a codex

---

Architecture

+---------------------------------------------------+
|              Intelligence Layer                     |
|  tax-engine (23)  market-intel (10)                |
|  social-sentiment (6)                              |
+---------------------------------------------------+
|            Data Source Adapters                      |
|  plaid-connect (8)  |  alpaca-trading (10)         |
|  ibkr-portfolio (9) |                              |
+---------------------------------------------------+
|              Foundation Layer                        |
|  finance-core (9 tools)                             |
|  Canonical models, storage, normalization,          |
|  policy checks, anomaly detection, briefs           |
+---------------------------------------------------+

Data flow: Adapters fetch provider data → finance-core normalizes & stores → intelligence layer analyzes → policy engine gates actions.

Extensions at a Glance

---

Tool Catalog

finance-core

plaid-connect

alpaca-trading

ibkr-portfolio

tax-engine

market-intel

social-sentiment

---

Key Workflows

1. Onboarding — Connect Accounts

plaid_create_link_token(products: ["transactions", "investments", "liabilities"])
  -> User completes Plaid Link
  -> plaid_exchange_token(publicToken)
  -> plaid_get_accounts -> finance_upsert_snapshot(source: "plaid")
  -> plaid_get_transactions -> finance_upsert_snapshot
  -> plaid_get_investments -> finance_upsert_snapshot
  -> finance_get_net_worth -> present baseline to user

2. Daily Anomaly Scan

plaid_get_transactions(cursor) -> finance_upsert_snapshot
alpaca_list_positions -> finance_upsert_snapshot(source: "alpaca")
ibkr_auth_status -> ibkr_get_positions -> finance_upsert_snapshot(source: "ibkr")
  -> finance_detect_anomalies(lookbackDays: 7)
  -> Alert on medium/high severity findings

3. Tax-Loss Harvesting

finance_get_state(include: ["positions"])
  -> tax_find_tlh_candidates(positions, marginalRate)
  -> tax_check_wash_sales(proposedSales, recentPurchases)
  -> tax_lot_selection(symbol, qty, lots)
  -> finance_policy_check(actionType: "tax_move")
  -> [If approved] alpaca_create_order(side: "sell", ...)

4. Quarterly Tax Review

tax_parse_w2 + tax_parse_1099b + tax_parse_1099div + tax_parse_1099int
  + tax_parse_1040 + tax_parse_schedule_c + tax_parse_schedule_se
  -> tax_estimate_liability(filingStatus, income)
  -> tax_compute_state_tax(stateCode, taxableIncome, filingStatus)
  -> tax_compute_amt(amtInput)  [if ISO/high-income]
  -> tax_quarterly_estimate(projectedIncome, priorYearTax, paymentsMade)
  -> finance_generate_brief(period: "quarterly")

5. Portfolio Monitoring

alpaca_list_positions + ibkr_get_positions
  -> finance_upsert_snapshot (both sources)
  -> ibkr_portfolio_allocation (check drift)
  -> alpaca_portfolio_history (performance trend)
  -> finance_detect_anomalies
  -> finance_generate_brief(period: "weekly")

---

Quick Start

Prerequisites

• Node.js 18+ and npm
• TypeScript 5+
• API credentials for at least one provider (see below)

1. Clone & Onboard

The onboard script builds all extensions, registers them as OpenClaw plugins, and installs the skill:

git clone https://github.com/wikidjon/personal-finance-skill.git
cd personal-finance-skill

# Build, symlink plugins, and install skill in one command
./scripts/onboard.sh

The script will:

1. Install deps and build all 7 extensions
2. Register each as an OpenClaw plugin (dev-linked via openclaw plugins install -l)
3. Symlink the skill into ~/.openclaw/skills/
4. Verify everything is reachable

Options: --copy to copy instead of symlink, --uninstall to remove everything.

2. Configure API Credentials

Set credentials for the providers you plan to use (you don’t need all of them):

# Plaid — https://dashboard.plaid.com
export PLAID_CLIENT_ID="your-client-id"
export PLAID_SECRET="your-secret"
export PLAID_ENV="sandbox"              # sandbox | development | production

# Alpaca — https://app.alpaca.markets
export ALPACA_API_KEY="your-key"
export ALPACA_API_SECRET="your-secret"
export ALPACA_ENV="paper"               # paper | live

# IBKR — https://www.interactivebrokers.com
export IBKR_BASE_URL="https://localhost:5000/v1/api"

# Market Intelligence
export FINNHUB_API_KEY="your-key"       # https://finnhub.io
export FRED_API_KEY="your-key"          # https://fred.stlouisfed.org
export BLS_API_KEY="your-key"           # https://data.bls.gov
export ALPHA_VANTAGE_API_KEY="your-key" # https://www.alphavantage.co

# Social Sentiment
export X_API_BEARER_TOKEN="your-token"  # https://developer.x.com
export QUIVER_API_KEY="your-key"        # https://www.quiverquant.com

3. Restart & Verify

openclaw gateway restart
openclaw plugins list        # should show all 7 extensions

4. Run Tests

for ext in extensions/*/; do
  echo "Testing $ext..."
  (cd "$ext" && npm test)
done

612 tests across 55+ test files, all passing.

---

Project Structure

personal-finance-skill/
  SKILL.md                              # Agent Skills Protocol entry point
  README.md                             # This file
  LICENSE                               # MIT
  scripts/
    onboard.sh                          # Build + register + verify (one command)
  extensions/
    finance-core/                       # Foundation: models, storage, policy
    plaid-connect/                      # Adapter: Plaid banking API
    alpaca-trading/                     # Adapter: Alpaca brokerage API
    ibkr-portfolio/                     # Adapter: IBKR Client Portal API
    tax-engine/                         # Intelligence: tax parsing + strategy (23 tools)
    market-intel/                       # Intelligence: news, filings, economic data (10 tools)
    social-sentiment/                   # Intelligence: social sentiment (6 tools)
  references/
    ext-finance-core.md                 # 9 tool schemas + storage layer
    ext-plaid-connect.md                # 8 tool schemas + Link flow
    ext-alpaca-trading.md               # 10 tool schemas + order lifecycle
    ext-ibkr-portfolio.md               # 9 tool schemas + session mgmt
    ext-tax-engine.md                   # 23 tool schemas + calculators
    ext-market-intel.md                 # 10 tool schemas (Finnhub, SEC, FRED, BLS, Alpha Vantage)
    ext-social-sentiment.md             # 6 tool schemas (StockTwits, X, Quiver)
    data-models-and-schemas.md          # Canonical types + enums
    risk-and-policy-guardrails.md       # Policy engine + approval tiers
    api-plaid.md                        # Plaid API reference
    api-alpaca-trading.md               # Alpaca API reference
    api-ibkr-client-portal.md           # IBKR API reference
    api-openclaw-framework.md           # OpenClaw architecture
    api-openclaw-extension-patterns.md  # Extension patterns
    api-irs-tax-forms.md                # IRS form schemas

---

Automation Examples

Set up recurring scans with your agent runtime:

---

Safety & Guardrails

These rules are enforced for all AI agents using this skill:

---

Key Concepts

---

Documentation

---

Agent Compatibility

This skill follows the Agent Skills Protocol and works with 40+ AI coding agents including:

Claude Code • Cursor • Codex • OpenClaw • Windsurf • Cline • Roo Code • Goose • Continue • Kilo • Amp • and more

---

Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Write tests first (TDD)
4. Ensure all 612 tests pass
5. Submit a PR

See CLAUDE.md for coding conventions and architecture guidelines.

---

Disclaimer

This software is for informational and educational purposes only. It is not financial advice. Always consult a qualified financial advisor before making investment or tax decisions. The authors assume no liability for financial losses incurred through the use of this software.

---

License

MIT