| name | personal-finance-skill |
| description | Personal finance management skill providing 75 tools across 7 extensions for bank account aggregation (Plaid), brokerage trading (Alpaca), portfolio monitoring (IBKR), tax optimization, market intelligence (Finnhub, SEC EDGAR, FRED, BLS, Alpha Vantage), social sentiment (StockTwits, X/Twitter, Quiver), and financial analysis. Supports scheduled scans, anomaly detection, net worth tracking, tax-loss harvesting, and approval-gated execution of financial actions.
|
| license | MIT |
| metadata | {"author":"contributors","version":"2.0.0","tools":"75","extensions":"finance-core, plaid-connect, alpaca-trading, ibkr-portfolio, tax-engine, market-intel, social-sentiment"} |
Personal Finance Skill
A comprehensive personal finance management skill with 75 tools across 7 extensions for banking, investing, tax, market intelligence, social sentiment, and financial analysis workflows.
When to Use
Activate this skill when a user asks for:
- Account aggregation — connecting bank accounts, viewing balances, syncing transactions
- Net worth / cash flow — computing totals, tracking spending, savings rate analysis
- Portfolio monitoring — positions, allocation, performance, drift detection
- Trading — placing/canceling orders, market data, asset lookup (Alpaca)
- Tax optimization — estimated liability, TLH candidates, wash sale checks, quarterly payments
- Tax document processing — parsing W-2, 1099-B/DIV/INT, K-1, Form 1040, Schedules A-E/SE, Form 8949, Form 6251 (AMT), state returns
- Market intelligence — company news, SEC filings, analyst recommendations, economic data (FRED, BLS), news sentiment
- Social sentiment — StockTwits sentiment, X/Twitter cashtag analysis, trending symbols, congressional trading
- Recurring expense tracking — subscriptions, bills, income streams
- Anomaly detection — unusual transactions, balance drops, duplicate charges
- Financial briefings — weekly/monthly summaries with action items
- Scheduled finance workflows — cron-based scans, alerts, reports
Architecture Overview
Seven extensions organized in three layers:
Intelligence Layer
tax-engine (23 tools) — parsing (15), liability, TLH, wash sales, lots,
Schedule D computation, state tax, AMT
market-intel (10 tools) — news, fundamentals, SEC filings, economic data
social-sentiment (6 tools) — StockTwits, X/Twitter, congressional trades
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 and stores → intelligence layer analyzes → policy engine gates actions.
Tool Catalog
finance-core — 9 tools
| 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 |
Full schemas: references/ext-finance-core.md
plaid-connect — 8 tools
| 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 |
Full schemas: references/ext-plaid-connect.md
alpaca-trading — 10 tools
| 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 |
Full schemas: references/ext-alpaca-trading.md
ibkr-portfolio — 9 tools
| 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 |
Full schemas: references/ext-ibkr-portfolio.md
tax-engine — 23 tools
| 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 federal return) | READ |
tax_parse_schedule_a | Parse Schedule A (itemized deductions, SALT cap) | READ |
tax_parse_schedule_b | Parse Schedule B (interest/dividend payors) | READ |
tax_parse_schedule_c | Parse Schedule C (self-employment income) | READ |
tax_parse_schedule_d | Parse Schedule D (capital gains netting) | READ |
tax_parse_schedule_e | Parse Schedule E (rental/royalty/partnership) | READ |
tax_parse_schedule_se | Parse Schedule SE (self-employment tax) | READ |
tax_parse_form_8949 | Parse Form 8949 (sales and dispositions) | READ |
tax_parse_state_return | Parse state return (CA 540, NY IT-201, etc.) | 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 | Compute Schedule D netting with loss carryover | READ |
tax_compute_state_tax | Compute state tax for CA/NY/NJ/IL/PA/MA/TX/FL | READ |
tax_compute_amt | Compute Alternative Minimum Tax (Form 6251) | READ |
Full schemas: references/ext-tax-engine.md
market-intel — 10 tools
| Tool | Description | Risk |
|---|
intel_company_news | Get recent news articles for a company (Finnhub) | READ |
intel_market_news | Get general market news by category (Finnhub) | READ |
intel_stock_fundamentals | Get reported financial statements (Finnhub) | READ |
intel_analyst_recommendations | Get analyst buy/hold/sell consensus (Finnhub) | READ |
intel_sec_filings | List SEC filings for a company by ticker (EDGAR) | READ |
intel_sec_search | Full-text search across SEC filings (EDGAR) | READ |
intel_fred_series | Fetch economic time series (GDP, CPI, rates) (FRED) | READ |
intel_fred_search | Search for FRED series by keyword | READ |
intel_bls_data | Fetch labor/price statistics time series (BLS) | READ |
intel_news_sentiment | Get news with AI-scored sentiment (Alpha Vantage) | READ |
Full schemas: references/ext-market-intel.md
social-sentiment — 6 tools
| Tool | Description | Risk |
|---|
social_stocktwits_sentiment | Get bull/bear sentiment for a stock (StockTwits) | READ |
social_stocktwits_trending | Get currently trending symbols (StockTwits) | READ |
social_x_search | Search recent tweets by keyword (X/Twitter) | READ |
social_x_user_timeline | Get recent tweets from a user (X/Twitter) | READ |
social_x_cashtag | Search cashtag with keyword sentiment scoring (X) | READ |
social_quiver_congress | Get congressional stock trading disclosures (Quiver) | READ |
Full schemas: references/ext-social-sentiment.md
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 Scan — Anomaly Detection
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_estimate_liability(filingStatus, 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")
6. Company Research — Market Intelligence
intel_company_news(symbol: "AAPL", limit: 10)
→ intel_analyst_recommendations(symbol: "AAPL")
→ intel_stock_fundamentals(symbol: "AAPL", freq: "quarterly")
→ intel_sec_filings(symbol: "AAPL", formType: "10-K")
→ intel_news_sentiment(tickers: "AAPL")
→ social_stocktwits_sentiment(symbol: "AAPL")
→ social_x_cashtag(symbol: "AAPL")
7. Economic Overview
intel_fred_series(seriesId: "GDP")
→ intel_fred_series(seriesId: "CPIAUCSL")
→ intel_fred_series(seriesId: "UNRATE")
→ intel_bls_data(seriesIds: ["CES0000000001"])
→ intel_fred_series(seriesId: "DFF")
8. Full Tax Return Processing
tax_parse_1040(rawData) → tax_parse_schedule_a(rawData)
→ tax_parse_schedule_b(rawData) → tax_parse_schedule_c(rawData)
→ tax_parse_schedule_d(rawData) → tax_parse_schedule_e(rawData)
→ tax_parse_form_8949(rawData) → tax_parse_schedule_se(rawData)
→ tax_compute_schedule_d(gains, losses, carryovers)
→ tax_compute_state_tax(stateCode, taxableIncome, filingStatus)
→ tax_compute_amt(taxableIncome, adjustments, regularTax)
→ tax_parse_state_return(rawData)
9. Congressional Trading Signals
social_quiver_congress(daysBack: 30)
→ Filter for large purchases
→ intel_company_news(symbol: <top_ticker>)
→ alpaca_market_data(symbols: <top_ticker>)
→ social_stocktwits_sentiment(symbol: <top_ticker>)
Configuration
Environment Variables
| Variable | Extension | Description |
|---|
PLAID_CLIENT_ID | plaid-connect | Plaid API client ID |
PLAID_SECRET | plaid-connect | Plaid API secret key |
PLAID_ENV | plaid-connect | sandbox / development / production |
ALPACA_API_KEY | alpaca-trading | Alpaca API key |
ALPACA_API_SECRET | alpaca-trading | Alpaca API secret |
ALPACA_ENV | alpaca-trading | paper / live |
IBKR_BASE_URL | ibkr-portfolio | Client Portal Gateway URL |
FINNHUB_API_KEY | market-intel | Finnhub API key (finnhub.io) |
FRED_API_KEY | market-intel | FRED API key (fred.stlouisfed.org) |
BLS_API_KEY | market-intel | BLS registration key (v2) |
ALPHA_VANTAGE_API_KEY | market-intel | Alpha Vantage API key |
X_API_BEARER_TOKEN | social-sentiment | X/Twitter OAuth 2.0 Bearer Token |
QUIVER_API_KEY | social-sentiment | Quiver Quantitative API key |
Extension Config
Each extension has an openclaw.plugin.json with a configSchema. Key settings:
- finance-core:
storageDir, anomalyThresholds, policyRulesPath
- plaid-connect:
plaidEnv, webhookUrl, clientName, countryCodes
- alpaca-trading:
env (paper/live), maxOrderQty, maxOrderNotional
- ibkr-portfolio:
baseUrl, defaultAccountId
- tax-engine:
defaultFilingStatus, defaultState, defaultTaxYear
- market-intel:
finnhubApiKeyEnv, fredApiKeyEnv, blsApiKeyEnv, alphaVantageApiKeyEnv, secEdgarUserAgent
- social-sentiment:
xApiBearerTokenEnv, quiverApiKeyEnv
Cron Examples
Weekly Financial Brief
openclaw cron add \
--name "Finance Weekly Brief" \
--cron "0 8 * * 1" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Run personal-finance-skill weekly workflow: sync all providers, compute net worth delta, top spend changes, upcoming bills, tax posture, and portfolio drift. Send concise brief with action queue."
Daily Anomaly Scan
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."
Quarterly Tax Check
openclaw cron add \
--name "Quarterly Tax Review" \
--cron "0 9 1 1,4,6,9 *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Run quarterly tax review: estimate liability, check withholding gap, find TLH opportunities, assess quarterly payment risk."
Portfolio Drift Monitor
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."
Non-Negotiable Guardrails
These rules apply to all AI agents using this skill:
- Always run
finance_policy_check before any side-effecting action (trades, transfers, tax moves).
- Never bypass approval requirements. If policy requires user or advisor approval, halt and request it.
- Numeric outputs must come from deterministic calculators. Never use LLM arithmetic for tax amounts, P/L, or net worth — always use the tool.
- Recommendations must include assumptions and data freshness. Every financial recommendation states what data it used and when that data was last updated.
- Never expose raw access tokens or API keys in tool outputs or conversation.
- Never auto-execute in live trading without explicit user confirmation, even if policy rules allow it.
- All investment-related outputs must include disclaimer: "This is informational only, not financial advice. Consult a qualified advisor before making financial decisions."
- If data is stale, say so. Report data freshness before advising.
Reference Index
Detailed documentation is available in the references/ directory:
| File | Contents |
|---|
| references/ext-finance-core.md | 9 tools, storage layer, normalization functions |
| references/ext-plaid-connect.md | 8 tools, Plaid Link flow, webhook handling |
| references/ext-alpaca-trading.md | 10 tools, order lifecycle, safety limits |
| references/ext-ibkr-portfolio.md | 9 tools, session management, market data fields |
| references/ext-tax-engine.md | 23 tools, 15 parsers + 8 calculators/strategy, form field mappings |
| references/ext-market-intel.md | 10 tools, Finnhub/SEC EDGAR/FRED/BLS/Alpha Vantage |
| references/ext-social-sentiment.md | 6 tools, StockTwits/X/Twitter/Quiver Quantitative |
| references/data-models-and-schemas.md | Canonical types, enums, entity schemas |
| references/risk-and-policy-guardrails.md | Policy engine, approval tiers, hard rules |
| references/api-plaid.md | Full Plaid API reference |
| references/api-alpaca-trading.md | Full Alpaca API reference |
| references/api-ibkr-client-portal.md | IBKR Client Portal Web API reference |
| references/api-openclaw-framework.md | OpenClaw architecture reference |
| references/api-openclaw-extension-patterns.md | How to build OpenClaw extensions |
| references/api-irs-tax-forms.md | IRS tax form schemas and rules |
