skill

personal-finance-skill

AI-powered personal finance skill — 75 tools across 7 extensions for banking (Plaid), trading (Alpaca), portfolio monitoring (IBKR), tax optimization, market intelligence, and social sentiment. Built

6missedcalls/personal-finance-skillcommunitylistedunreviewednot running here yet

Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below; one-click install arrives with accounts.

README

synced Oct 14, 2026

`personal-finance-skill`

Your AI-Powered Personal CFO

75 tools across 7 extensions for banking, investing, tax optimization, market intelligence, social sentiment, and financial analysis — built for the Agent Skills Protocol.

Connect your bank accounts • Monitor your portfolio • Trade stocks • Optimize taxes • Track market intel • Detect anomalies

All through natural language, with deterministic calculations, policy guardrails, and approval gates.

Install • Architecture • Tools • Workflows • Docs

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 <owner>/personal-finance-skill

Or install for specific agents:

npx skills add <owner>/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

Extension	Tools	What It Does
finance-core	9	Canonical data models, snapshot storage, normalization, policy engine, anomaly detection, financial briefs
plaid-connect	8	Plaid Link flow, bank accounts, transactions, investments, liabilities, recurring charges, webhooks
alpaca-trading	10	Brokerage account, positions, orders, market data, trading with safety limits
ibkr-portfolio	9	IBKR Client Portal, portfolio allocation, performance, market snapshots, session management
tax-engine	23	15 form parsers (1040, Schedules A-E/SE, 8949, 6251, W-2, 1099-B/DIV/INT, K-1, state returns) + 8 calculators (liability, TLH, wash sales, lots, quarterly, Schedule D, state tax, AMT)
market-intel	10	Company news, SEC filings, economic data (FRED, BLS), analyst recommendations, news sentiment via Finnhub, SEC EDGAR, FRED, BLS, Alpha Vantage
social-sentiment	6	Social media sentiment via StockTwits, X/Twitter, congressional trading via Quiver Quantitative

Tool Catalog

finance-core

Tool	Description	Risk
`finance_upsert_snapshot`	Store normalized financial data snapshot (idempotent)	LOW
`finance_get_state`	Get current financial state (accounts, positions, etc.)	READ
`finance_get_transactions`	Query transactions with filters and pagination	READ
`finance_get_net_worth`	Calculate net worth breakdown by category/account	READ
`finance_detect_anomalies`	Scan for unusual transactions, balance drops, fee spikes	READ
`finance_cash_flow_summary`	Income vs expenses by category with savings rate	READ
`finance_subscription_tracker`	Identify recurring charges and subscription patterns	READ
`finance_generate_brief`	Create structured financial summary with action items	READ
`finance_policy_check`	Validate proposed action against policy rules	READ

plaid-connect

Tool	Description	Risk
`plaid_create_link_token`	Initialize Plaid Link for account connection	LOW
`plaid_exchange_token`	Exchange public token for permanent access	MED
`plaid_get_accounts`	List connected accounts with balances	READ
`plaid_get_transactions`	Fetch transactions via cursor-based sync	READ
`plaid_get_investments`	Fetch holdings, securities, investment transactions	READ
`plaid_get_liabilities`	Fetch credit, student loan, and mortgage data	READ
`plaid_get_recurring`	Identify recurring inflow/outflow streams	READ
`plaid_webhook_handler`	Process incoming Plaid webhook events	LOW

alpaca-trading

Tool	Description	Risk
`alpaca_get_account`	Get account balances, buying power, status	READ
`alpaca_list_positions`	List all open positions	READ
`alpaca_get_position`	Get single position by symbol	READ
`alpaca_list_orders`	List orders with status/date filters	READ
`alpaca_create_order`	Submit buy/sell order with safety checks	HIGH
`alpaca_cancel_order`	Cancel a pending order	MED
`alpaca_portfolio_history`	Historical equity and P/L over time	READ
`alpaca_get_assets`	Search tradable assets by class/exchange	READ
`alpaca_market_data`	Get snapshots, bars, or quotes for symbols	READ
`alpaca_clock`	Check if market is open, next open/close	READ

ibkr-portfolio

Tool	Description	Risk
`ibkr_auth_status`	Check gateway authentication status	READ
`ibkr_tickle`	Keep gateway session alive (~1 min interval)	LOW
`ibkr_list_accounts`	List accounts (must call first)	READ
`ibkr_get_positions`	Get positions for an account (paginated)	READ
`ibkr_portfolio_allocation`	Allocation by asset class, sector, group	READ
`ibkr_portfolio_performance`	NAV time series and returns	READ
`ibkr_search_contracts`	Search contracts by symbol/name/type	READ
`ibkr_market_snapshot`	Real-time market data for contracts	READ
`ibkr_get_orders`	Get current live orders	READ

tax-engine

Tool	Description	Risk
`tax_parse_1099b`	Parse 1099-B (proceeds, cost basis, wash sales)	READ
`tax_parse_1099div`	Parse 1099-DIV (dividends, capital gains)	READ
`tax_parse_1099int`	Parse 1099-INT (interest, bond premiums)	READ
`tax_parse_w2`	Parse W-2 (wages, withholding, SS/Medicare)	READ
`tax_parse_k1`	Parse Schedule K-1 (partnership pass-through)	READ
`tax_parse_1040`	Parse Form 1040 (main individual return)	READ
`tax_parse_schedule_a`	Parse Schedule A (itemized deductions, SALT cap)	READ
`tax_parse_schedule_b`	Parse Schedule B (interest/dividends, foreign accounts)	READ
`tax_parse_schedule_c`	Parse Schedule C (self-employment, 23 expense categories)	READ
`tax_parse_schedule_d`	Parse Schedule D (capital gains netting)	READ
`tax_parse_schedule_e`	Parse Schedule E (rental/partnership income)	READ
`tax_parse_schedule_se`	Parse Schedule SE (self-employment tax)	READ
`tax_parse_form_8949`	Parse Form 8949 (capital asset dispositions)	READ
`tax_parse_state_return`	Parse generic state income tax return	READ
`tax_parse_form_6251`	Parse Form 6251 (AMT)	READ
`tax_estimate_liability`	Calculate federal/state tax with brackets	READ
`tax_find_tlh_candidates`	Identify tax-loss harvesting opportunities	READ
`tax_check_wash_sales`	Validate wash sale rule compliance (61-day window)	READ
`tax_lot_selection`	Compare FIFO/LIFO/specific ID for a proposed sale	READ
`tax_quarterly_estimate`	Quarterly estimated payments with safe harbor	READ
`tax_compute_schedule_d`	Schedule D computation with $3K loss cap and carryover	READ
`tax_compute_state_tax`	State income tax (8 states: CA, NY, NJ, IL, PA, MA, TX, FL)	READ
`tax_compute_amt`	Alternative Minimum Tax with 2025 parameters	READ

market-intel

Tool	Description	Risk
`intel_company_news`	Company-specific news articles by ticker (Finnhub)	READ
`intel_market_news`	General/forex/crypto/merger market news (Finnhub)	READ
`intel_stock_fundamentals`	Financial statements, annual/quarterly (Finnhub)	READ
`intel_analyst_recommendations`	Analyst buy/hold/sell recommendations (Finnhub)	READ
`intel_sec_filings`	SEC filing history by company CIK (SEC EDGAR)	READ
`intel_sec_search`	Full-text search of SEC filings (SEC EDGAR)	READ
`intel_fred_series`	Economic data series observations (FRED)	READ
`intel_fred_search`	Search for economic data series (FRED)	READ
`intel_bls_data`	Bureau of Labor Statistics time series (BLS)	READ
`intel_news_sentiment`	News sentiment analysis by ticker/topic (Alpha Vantage)	READ

social-sentiment

Tool	Description	Risk
`social_stocktwits_sentiment`	Sentiment aggregation (bullish/bearish) for a ticker	READ
`social_stocktwits_trending`	Trending symbols on StockTwits	READ
`social_x_search`	Search recent tweets with financial query	READ
`social_x_user_timeline`	Fetch a user's recent tweets	READ
`social_x_cashtag`	Cashtag search ($AAPL) with basic sentiment	READ
`social_quiver_congress`	Congressional stock trading activity (Quiver Quantitative)	READ

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/6missedcalls/personal-finance-skill.git
cd personal-finance-skill

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

The script will:

Install deps and build all 7 extensions
Register each as an OpenClaw plugin (dev-linked via openclaw plugins install -l)
Symlink the skill into ~/.openclaw/skills/
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:

openclaw cron add \
  --name "Finance Weekly Brief" \
  --cron "0 8 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Sync all providers, compute net worth delta, top spend changes, upcoming bills, tax posture, portfolio drift. Send concise brief with action queue."

openclaw cron add \
  --name "Finance Daily Anomaly" \
  --cron "15 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Sync latest transactions, run finance_detect_anomalies. Alert on medium/high/critical findings only."

openclaw cron add \
  --name "Quarterly Tax Review" \
  --cron "0 9 1 1,4,6,9 *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Estimate liability, check withholding gap, find TLH opportunities, assess quarterly payment risk."

openclaw cron add \
  --name "Portfolio Drift Monitor" \
  --cron "*/30 13-21 * * 1-5" \
  --tz "America/New_York" \
  --session isolated \
  --message "Check portfolio allocation vs target bands. Alert if drift exceeds threshold for 2 consecutive scans."

Safety & Guardrails

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

#	Rule
1	Always run `finance_policy_check` before any trade, transfer, or tax move
2	Never bypass approval requirements — halt and request confirmation
3	Deterministic math only — never use LLM arithmetic for money
4	State data freshness — every recommendation includes when data was last synced
5	Never expose credentials — no API keys or tokens in outputs
6	No auto-execution — live trades always require explicit human confirmation
7	Include disclaimers — investment outputs state "not financial advice"
8	Flag stale data — warn before advising on outdated information

Key Concepts

Concept	Description
Canonical Models	All provider data normalizes into shared types: `Account`, `Transaction`, `Position`, `Liability`
Snapshot Storage	Append-only, content-hashed, idempotent storage with point-in-time queries
Policy Engine	Configurable rules with approval tiers (none / user / advisor) gate all side effects
Deterministic Calculators	Tax, P/L, net worth computed by tools — zero LLM math
Progressive Disclosure	SKILL.md has the overview, `references/` has full schemas, `api-*.md` has upstream docs

Documentation

Audience	Start Here
AI agents	`SKILL.md` — tool catalog, workflows, guardrails
Developers	`CLAUDE.md` — build instructions, architecture, rules
Tool schemas	`references/ext-*.md` — full input/output schemas per extension
Data models	`references/data-models-and-schemas.md`
Policy rules	`references/risk-and-policy-guardrails.md`

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:

Fork the repo
Create a feature branch (git checkout -b feat/my-feature)
Write tests first (TDD)
Ensure all 612 tests pass
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