# Tax Agent

> Claude skills for US investment tax analysis, backed by a deterministic Python engine. Analysis only: no tool places an order, modifies a custodian record or files a return.

The model interprets requests and explains results. It performs no tax calculation. Every figure is produced by tested code, validated independently of the engine that produced it, and pinned to a reviewed rule pack.

## Skills

- **entity-review**: Compute section 179 expensing with both of its limits, and compare federal tax on the same income inside a C corporation against passing it through. Produces arithmetic over supplied rates, never an entity-choice recommendation.
- **estate-review**: Estimate federal estate tax against the unified credit, including the effect of lifetime gifts and a deceased spouse's unused exclusion. Use when someone asks what an estate would owe. Never values property and never decides what is in the gross estate.
- **expat-review**: Compute the foreign earned income exclusion and housing amount for a US taxpayer working abroad, and check whether a gift from a foreign person must be reported. Never establishes eligibility and never compares against the foreign tax credit.
- **gain-loss-review**: Calculate realized and unrealized gain and loss at lot level, split by holding period, from a frozen snapshot. Use when the user asks what they would realize by selling, where they stand on gains this year, or how a sale splits between short and long term.
- **gift-planning**: Work out how much of a gift the annual exclusion covers, including gift splitting between spouses and the separate figure for a non-citizen spouse. Use for annual gifting questions. Produces an exclusion calculation, not a recommendation to give.
- **harvest-review**: Review tax-loss harvesting opportunities in one taxable account, with wash-sale screening and an explicit gain budget. Use when the user asks about harvesting losses, offsetting gains, or raising cash tax-efficiently. Produces scenarios for professional review, never a trade instruction.
- **household-coordination**: Coordinate harvesting and cash raising across a household's accounts or a UMA's sleeves under one shared gain budget, with cross-account and cross-sleeve wash-sale prevention. Use when a request spans more than one account or manager, or when a UMA overlay must stop one sleeve from washing another's loss.
- **lot-review**: Check tax-lot completeness and integrity before any tax calculation — basis, acquisition dates, quantities, duplicates and position reconciliation. Use when lots have just been imported, a transfer arrived, or another skill reported blocked calculations.
- **muni-review**: Compare a municipal bond against a taxable alternative, and work out how a discount or premium will be taxed. Use for muni yield questions, de minimis market discount, and bond premium. Does not decide whether a bond is a private activity bond and does not look up any state's treatment.
- **penalty-review**: Compute late filing and late payment additions to tax, and partnership or S corporation late-filing penalties. Use when a return or payment is late. Interest is never included, so the figure is always lower than what is owed.
- **rebalance-review**: Rebalance one account toward advisor-supplied target weights within a gain budget, showing the tax cost and the drift that remains. Use when the user asks what rebalancing would cost, or wants to compare acting now against leaving the drift.
- **salt-review**: Compute the federal cap on deducting state and local tax, including its phase-down, and report what this deployment can say about an individual state's own tax. No state's own income tax is computed in this release.
- **tax-intake**: Turn uploaded statements and exports into source-cited, normalized tax facts with a missing-information register. Use at the start of any engagement, or when new documents arrive and no snapshot exists yet.
- **tax-profile**: Establish the household scope, tax units, account classifications and stated assumptions that every other tax skill depends on. Use before the first analysis of an engagement, or when ownership, registration or residency is unclear.
- **tax-review-pack**: Assemble a source-bound review package for a completed analysis — scope, assumptions, results, validation, limitations and version pins — for the responsible professional. Use when the user wants something to review, file, sign off, or hand to a CPA.
- **wash-sale-review**: Screen proposed or completed loss sales for wash sales under IRC section 1091, across the accounts available, with explicit coverage gaps. Use when the user asks whether a loss is allowed, about the 30-day rule, or about repurchasing a security they sold at a loss.

## Engine coverage

- `rule-based-harvest-selector` — implemented; scopes: account
  - Greedy selection; no optimality claim.
  - No multi-period or risk-aware objective.
- `oracle-account-adapter` — implemented; scopes: account
  - Optimal means optimal over the lots, prices and constraints supplied, for the stated objective: reach the cash target, realize as little gain as possible, use as few trades as possible. It is not a statement about what the account should do.
  - Risk, tracking error, a client's view on a position and the reason a lot was bought are outside the model entirely.
  - Beyond 40 budget-consuming lots the search is not exhausted. The status degrades to feasible and a gap is reported; optimality is never claimed from a truncated search.
  - Account scope only. Running it once per account is not a household optimum.
- `household-coordinator` — implemented; scopes: household_coordinated
  - Sequential allocation. Results depend on the declared unit order and are not a joint optimum.
  - Budgets are allocated per tax unit; a household spanning several tax units gets several budgets, never one.
  - Cross-unit wash-sale prevention covers accounts in scope and planned purchases supplied with the request. Unseen accounts and unreported manager intentions remain outside it.
- `household-optimizer` — implemented; scopes: household
  - Solved per tax unit and summed. That decomposition is exact, not an approximation: a gain budget belongs to one taxpayer, so no selection in one unit changes what is available in another and the objective is additive. A household spanning several tax units still gets several budgets and never one pooled allowance.
  - Wash-sale scope follows the taxpayer and is handled before the solve, by excluding lots whose loss would be disallowed. Accounts outside the snapshot remain unseen.
  - Optimality is over the supplied lots and constraints. It says nothing about which account should hold which exposure, which is an allocation decision this engine does not make.
  - Beyond 40 budget-consuming lots in a tax unit the search is not exhausted and the status degrades to feasible with a reported gap.
- `rebalance-engine` — implemented; scopes: account
  - Drift is the sum of absolute differences between current and target weight. The engine never sells more of a security than its overweight, so with chunky lots it under-trades rather than overshooting, and residual drift is expected and reported.
  - Buys are allocated across underweight securities in proportion to their shortfall. A purchase has no tax consequence, so there is nothing to optimise about which lot it becomes.
  - A buy is withheld when the security was sold at a loss inside the wash-sale window, which leaves that drift open until the window closes.
  - Requires advisor-supplied target weights. Inferring a target from the current holdings would make the portfolio its own benchmark.
  - Account scope only, and no view on transaction costs, market impact, tracking error or which account should hold which exposure.
- `federal-income-estimator` — implemented; scopes: supplied_figures
  - Computes ordinary tax, preferential-rate tax on long-term gains, NIIT, AMT, the section 199A deduction and the capital loss deduction. Each is exact over the figures given.
  - These do not compose into a return. AMT and QBI are computed separately and are not folded into one liability; credits, self-employment tax, the additional Medicare tax, phase-outs other than those named, state and local tax, and any non-2026 year are outside it.
  - Figures transcribed from Rev. Proc. 2025-32 and verified line by line on 2026-10-05. The methodology built on those figures has not been reviewed by a tax professional.
  - Not bound into the analysis workflow: a harvest or coordination run reports gains and losses, never tax dollars.
- `tax-liability-engine` — unavailable; scopes: none
  - No return-level liability engine is bound. A portfolio run produces gain and loss amounts only; it never states the tax on them.
  - What exists instead is federal-income-estimator, which computes tax on figures a caller supplies. It is not wired into a run and does not assemble a return, so it cannot answer what a given harvest costs in tax without a human carrying the figures across.
- `municipal-bond-engine` — implemented; scopes: supplied_figures
  - Computes a taxable-equivalent yield, the de minimis market discount test and mandatory premium amortization. Each is exact over the figures given.
  - Whether a bond is a private activity bond is supplied by the caller. It decides whether the interest is an AMT preference, and getting it wrong reverses the answer for a taxpayer in AMT.
  - No state's treatment is looked up. The holder's state rate and whether the bond is exempt in their state both come from the caller.
  - Original issue discount accrual and the constant-yield premium schedule are not computed; amortization is shown straight-line, which reaches the same basis at maturity.
  - Municipal bonds remain outside every portfolio engine. A muni lot cannot be harvested, screened or rebalanced here, because accrued market discount is not tracked in lot accounting.
  - Credit risk, call features, duration and liquidity are not modelled, so a yield comparison is not a recommendation.

## Tools a host can call

- `calculate_federal` (calculation)
- `calculate_capgains` (calculation)
- `calculate_niit` (calculation)
- `calculate_amt` (calculation)
- `calculate_qbi` (calculation)
- `calculate_loss` (calculation)
- `get_federal_capabilities` (calculation)
- `calculate_estate_tax` (calculation)
- `calculate_gift_exclusion` (calculation)
- `calculate_fiduciary_tax` (calculation)
- `get_estate_capabilities` (calculation)
- `calculate_feie` (calculation)
- `calculate_foreign_gift` (calculation)
- `get_international_capabilities` (calculation)
- `calculate_section_179` (calculation)
- `calculate_entity_comparison` (calculation)
- `get_business_capabilities` (calculation)
- `calculate_filing_penalty` (calculation)
- `calculate_entity_penalty` (calculation)
- `calculate_safe_harbour` (calculation)
- `get_compliance_capabilities` (calculation)
- `calculate_muni_yield` (calculation)
- `calculate_muni_discount` (calculation)
- `calculate_muni_premium` (calculation)
- `get_muni_capabilities` (calculation)
- `calculate_salt_cap` (calculation)
- `calculate_state_coverage` (calculation)
- `get_salt_capabilities` (calculation)
- `check_holdings` (internal_write)
- `review_rebalance` (internal_write)
- `review_lots` (internal_write)
- `optimize_harvest` (internal_write)
- `review_harvest` (internal_write)
- `resolve_subject` (read)
- `get_run_status` (read)
- `get_scenario` (read)
- `get_capabilities` (read)
- `optimize_household` (internal_write)
- `coordinate_household` (internal_write)
- `resolve_subject` (read)
- `get_run_status` (read)
- `get_scenario` (read)
- `get_capabilities` (read)

## Internal workflow operations

Real code, but not callable as tools: they run as steps inside a workflow template, which owns their order and preconditions.

- `create_snapshot` (internal_write)
- `validate_lots` (calculation)
- `compile_constraints` (calculation)
- `select_harvest_candidates` (calculation)
- `calculate_gain_loss` (calculation)
- `screen_wash_sales` (calculation)
- `build_evidence_pack` (internal_write)
- `select_household_jointly` (calculation)
- `select_account_optimally` (calculation)

## Tax rules

Bundle `us-federal-investment-rules.v1` (sha256:40d9e73fd3d40323ac0…), knowledge time 2026-09-28T00:00:00Z.

- `long_term_holding_period_years`: IRC section 1222(3); Rev. Rul. 66-7
- `permanently_disallowing_registrations`: Rev. Rul. 2008-5
- `replacement_matching_basis`: IRC section 1091(a)
- `wash_sale_window_days`: IRC section 1091(a)

## Not supported

- A municipal bond inside a portfolio engine: Munis are priced on their own server. No portfolio engine reads one, because accrued market discount is not tracked in lot accounting, so a muni lot cannot be harvested, screened or rebalanced.
- Tax owed, in dollars: No return-level liability engine is bound. Gains and losses are produced; converting them to tax needs facts and an engine this release does not have.
- "Is this substantially identical?": Matching is by exact security identifier. Whether two different securities are substantially identical is a reviewed policy question the screener declines.
- A clean bill of health on wash sales: A screen is complete or it has gaps. It never clears an account it has not read, including a spouse's account at another custodian.
- A gain budget with no netting basis: Gross and net readings of the same sentence give different answers, so the request returns the exact fields it needs rather than guessing.
- A lot with unknown basis: Blocked, never defaulted to zero. A missing basis stays missing.
- A relaxed constraint to make a target reachable: Infeasible is reported with the shortfall. Constraints change only when a person changes them.
- Any trade, ever: Analysis only. No tool in this release places an order, modifies a custodian record or files a return.

Source: https://github.com/ai-theories/tax-skills
Full documentation: https://ai-theories.github.io/tax-skills/llms-full.txt