Skip to content
Finance
Skill

/tax-loss-harvesting

Execute a complete tax-loss harvesting workflow from candidate identification through post-harvest monitoring. Use when the user asks about finding TLH candidates, gain/loss budgeting, replacement security selection, wash-sale compliance, or harvest execution planning. Also

From plugin
finance-skills
16491 skills
Install
$ npx -y skills add JoelLewis/finance_skills --skill tax-loss-harvesting --agent claude-code

How it fires

How this skill gets triggered: by you, by Claude, or both.

  • Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
  • You can call itInvoke it directly when you want it.
  • Slash command/tax-loss-harvesting

Context preview

The summary Claude sees to decide when to auto-load this skill.

Execute a complete tax-loss harvesting workflow from candidate identification through post-harvest monitoring. Use when the user asks about finding TLH candidates, gain/loss budgeting, replacement security selection, wash-sale compliance, or harvest execution planning. Also

SKILL.md

tax-loss-harvesting.SKILL.md
name: tax-loss-harvesting
description: "Execute a complete tax-loss harvesting workflow from candidate identification through post-harvest monitoring. Use when the user asks about finding TLH candidates, gain/loss budgeting, replacement security selection, wash-sale compliance, or harvest execution planning. Also trigger when users mention 'unrealized losses in my portfolio', 'swap ETFs for tax purposes', 'harvest losses before year-end', 'substantially identical security', 'wash-sale window', 'NIIT offset', 'loss carryforward', or ask how much tax they can save by harvesting."

Tax-Loss Harvesting

Core Concepts

Candidate Identification

Scan the portfolio for positions with unrealized losses that meet all three filters:

  • **Materiality threshold:** Minimum absolute loss (e.g., $2,000) or minimum loss-to-value ratio (e.g., loss exceeds 5% of position market value). Harvesting a $200 loss on a $50,000 portfolio is not worth the operational cost.
  • **Holding period filter:** Positions held less than 31 days may not have meaningful losses and create short-term wash-sale complexity. Positions approaching the one-year mark (days 335-365) may benefit from waiting to convert a short-term loss into a long-term loss only if the position is expected to continue declining.
  • **Loss magnitude ranking:** Rank candidates by Tax Benefit = Unrealized Loss * Applicable Tax Rate. Prioritize short-term losses (taxed at ordinary rates up to 37%) over long-term losses (taxed at capital gains rates of 15-20%) when gain/loss budget allows.

Gain/Loss Budgeting

Before harvesting, build the year-to-date tax budget:

1. **Realized gains YTD:** Sum all short-term and long-term capital gains already realized (including fund distributions). 2. **Planned gain exposure:** Estimate gains from pending rebalancing trades, planned liquidations, or expected fund capital gain distributions. 3. **Loss carryforward balance:** Check prior-year unused capital loss carryforwards (these offset gains before new harvests do). 4. **Target harvest amount:** Target Harvest = (Realized Gains YTD + Planned Gains) - Loss Carryforward + $3,000 ordinary income offset. Harvesting this amount offsets all expected gains AND captures the full $3,000 annual deduction against ordinary income; harvest more to build carryforward for future years.

Replacement Security Selection

The replacement must maintain market exposure without being "substantially identical":

  • **ETF-to-ETF swaps:** Switch between funds tracking different indices (e.g., Vanguard Total Stock Market to Schwab Broad Market, or S&P 500 to Russell 1000). Different index methodology is generally sufficient.
  • **Individual stock replacement:** Replace a single stock with a sector ETF or a peer company. Example: sell Apple, buy Technology Select Sector SPDR (XLK).
  • **Tracking error budget:** The replacement should have a correlation of 0.95+ and tracking error under 2% annualized relative to the original holding. Wider tracking error is acceptable for larger tax benefits.
  • **Expense ratio delta:** Ensure the replacement does not have meaningfully higher expenses. A 10 bps cost increase on a $100K position held for 30 days costs roughly $8 — negligible against a $2,000+ tax benefit.

Wash-Sale Compliance

The wash-sale rule (IRC Section 1091) disallows a loss if a substantially identical security is acquired within the 61-day window (30 days before + sale date + 30 days after):

  • **Cross-account scope:** The rule applies across ALL accounts owned by the taxpayer: taxable brokerage, Traditional IRA, Roth IRA, 401(k), HSA, and spouse's accounts. A purchase in any of these accounts triggers wash-sale disallowance.
  • **IRA wash-sale trap:** If a wash sale is triggered by a purchase in an IRA, the disallowed loss is permanently lost — it cannot be added to the IRA cost basis. This is the most dangerous wash-sale scenario.
  • **DRIP suspension:** Automatic dividend reinvestment (DRIP) in the sold security or a substantially identical fund must be suspended during the 61-day window. Reinvesting even a small dividend triggers a partial wash sale.
  • **Spouse coordination:** Purchases in a spouse's accounts (including retirement accounts) trigger wash-sale rules. Both spouses' automatic investments, 401(k) contributions, and DRIP settings must be reviewed.

Execution Planning

Translate candidates into an actionable trade list:

  • **Lot selection method:** Use Specific Identification (Spec ID) to select the highest-cost-basis lots first (HIFO). This maximizes the realized loss per share sold. If only partial harvesting is needed, sell only the lots with cost basis above current market price.
  • **Coordination with rebalancing:** If the portfolio also needs rebalancing, combine TLH sells with rebalance sells to reduce total trade count. A position that is both overweight and at a loss is the ideal candidate — the harvest and rebalance are the same trade.
  • **Timing strategy:** Year-end harvesting (October-December) captures the full year's losses but faces market timing risk. Opportunistic harvesting throughout the year during drawdowns of 5%+ captures losses that may recover by year-end.
  • **Trade list fields:** Security, account, action (sell/buy), shares, lot IDs, estimated loss, replacement security, wash-sale window start/end dates.

Tax Savings Calculation

Quantify the dollar value of each proposed harvest:

  • **Federal rate selection:** Short-term losses offset short-term gains first (up to 37% ordinary rate). Long-term losses offset long-term gains (15-20% rate). Net losses of either type can cross over to offset the other, then up to $3,000 offsets ordinary income.
  • **State tax impact:** Most states tax capital gains as ordinary income (rates range from 0% up to California's top statutory rate on investment income of 13.3%; California's effective top rate on wage income is 14.4%+ since the 2024 SDI uncapping). Include state tax savings in the calcu
Read more
Ships withfinance-skills

A collection of Claude Code skill plugins for financial services. 91 skills across 7 domain plugins teach Claude investment management, regulatory compliance, advisory workflows, trading operations, and more — so it can assist with finance questions, build

Get the whole plugin
Stats
170
Stars
34
Forks
Maintained
Maintenance
Python
Language
MIT
License
1mo ago
Last commit
6mo ago
Created

Repo: JoelLewis/finance_skills

Other skills on finance-skills.