
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 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.
- Installs
- 687
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/joellewis/finance_skills --skill tax-loss-harvesting- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads tax-loss-harvesting automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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:
- Realized gains YTD: Sum all short-term and long-term capital gains already realized (including fund distributions).
- Planned gain exposure: Estimate gains from pending rebalancing trades, planned liquidations, or expected fund capital gain distributions.
- Loss carryforward balance: Check prior-year unused capital loss carryforwards (these offset gains before new harvests do).
- 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 calculation; for a California resident at the 13.3% bracket, state tax roughly doubles the benefit of each harvest.
- NIIT interaction: The 3.8% Net Investment Income Tax (IRC Section 1411) applies to the lesser of net investment income or MAGI exceeding $250,000 (MFJ) — a statutory threshold that is not inflation-indexed. Harvested losses reduce net investment income, potentially eliminating NIIT exposure.
Post-Harvest Monitoring
After executing the harvest:
- Wash-sale window tracking: Maintain a calendar of open wash-sale windows with security identifiers and expiration dates. Flag any pending purchases (including automated ones) that would violate the window.
- Replacement performance: Monitor tracking error between the replacement and original security. If the replacement significantly underperforms (>3% divergence), evaluate whether the tax benefit justified the swap.
- Cost basis updates: Verify that broker statements reflect the new (lower) cost basis on replacement securities. The replacement's basis equals purchase price, not the original security's basis.
- Swap-back timing: After the 31st day, the investor may sell the replacement and repurchase the original security if desired. Evaluate whether the swap-back itself triggers a taxable gain on the replacement position.
Household-Level Coordination
TLH across a household with multiple accounts requires centralized tracking:
- Account type matrix: Taxable accounts are the only accounts where TLH generates direct tax benefits. Retirement accounts have no realized gains/losses for tax purposes, but they can trigger wash sales in taxable accounts.
- Advisor-managed vs held-away: If the client has accounts at other institutions (401(k) plan, outside brokerage), the advisor cannot control purchases. Document held-away holdings and instruct the client to avoid purchasing substantially identical securities during open wash-sale windows.
- Spousal coordination checklist: (1) Review spouse's 401(k) fund lineup for overlap, (2) suspend DRIP in spouse's accounts for harvested securities, (3) coordinate any year-end tax trades across both spouses.
Key Formulas
| Formula | Expression | Use Case |
|---|---|---|
| Tax Benefit | Benefit = Realized_Loss * Applicable_Tax_Rate | Dollar value of a single harvest |
| Net Tax Alpha | Alpha = Tax_Savings - Tracking_Error_Cost - Transaction_Costs | True value after implementation costs |
| Break-Even Holding Period | T_be = Tax_Savings / (Annual_Tracking_Error_Cost + Annual_Expense_Delta) | How long replacement can be held before costs exceed benefit |
| Wash-Sale Adjusted Basis | New_Basis = Replacement_Purchase_Price + Disallowed_Loss | Cost basis when wash sale is triggered |
| Annual TLH Capacity | Capacity = Portfolio_Value * Expected_Volatility * Loss_Capture_Rate | Estimate of harvestable losses per year |
| Target Harvest Amount | Target = Realized_Gains_YTD + Planned_Gains - Loss_Carryforward + 3000 | Harvest needed to offset all gains plus the $3,000 ordinary-income deduction |
Worked Examples
Example 1: Single Position Harvest with Replacement Selection
Given:
- Client holds 500 shares of XYZ Corp purchased at $80/share ($40,000 cost basis), current price $62/share ($31,000 market value), held 8 months (short-term)
- Client has $12,000 in short-term realized gains YTD, marginal federal rate 35%, state rate 9.3%, NIIT applies (3.8%)
- Replacement candidate: Sector ETF (correlation 0.97, tracking error 1.4% annualized, expense ratio 0.10% vs 0% for individual stock)
Calculate: Tax benefit, net tax alpha, and break-even holding period for the replacement.
Solution:
- Unrealized loss: $31,000 - $40,000 = -$9,000 (short-term)
- Applicable rate: 35% federal + 9.3% state + 3.8% NIIT = 48.1% combined
- Tax benefit: $9,000 * 48.1% = $4,329
- Transaction costs: Commission $0 (zero-commission broker) + estimated spread cost 0.05% * $31,000 * 2 trades = $31
- Tracking error cost: 1.4% annualized * $31,000 * (30/365) = $36 (for the 30-day minimum hold)
- Net tax alpha: $4,329 - $31 - $36 = $4,262
- Annual cost of replacement: $31,000 * (0.10% expense + 1.4% tracking error drag estimate of 0.05%) = $46.50/year
- Break-even holding period: $4,262 / $46.50 = 91.7 years — the tax benefit overwhelmingly justifies the swap
- Action: Sell XYZ Corp (Spec ID, all lots), buy Sector ETF. Set wash-sale window reminder for 31 calendar days. Suspend any XYZ DRIP in all household accounts.
Example 2: Portfolio-Wide TLH Scan with Gain/Loss Budget
Given:
- $2M taxable portfolio, 15 equity positions, year is mid-October
- Realized gains YTD: $18,000 long-term, $5,000 short-term
- Loss carryforward from prior years: $0
- Planned rebalancing trades will realize approximately $4,000 in additional long-term gains
- Three positions show unrealized losses: Position A (-$14,000 LT), Position B (-$6,500 ST), Position C (-$2,100 LT)
- Federal LTCG rate 20%, ordinary rate 37%, state 5%, NIIT 3.8%
Calculate: Target harvest amount, prioritized trade list, and total tax savings.
Solution:
- Gain/loss budget:
- Total expected gains: $18,000 LT + $5,000 ST + $4,000 LT (planned) = $22,000 LT + $5,000 ST = $27,000
- Loss carryforward: $0
- Target harvest: $27,000 - $0 + $3,000 = $30,000 to fully offset gains and capture the $3,000 ordinary income deduction
- Candidate ranking by tax benefit:
- Position B: $6,500 ST * (37% + 5% + 3.8%) = $6,500 * 45.8% = $2,977 (highest rate — harvest first)
- Position A: $14,000 LT * (20% + 5% + 3.8%) = $14,000 * 28.8% = $4,032 (largest absolute benefit)
- Position C: $2,100 LT * 28.8% = $605
- Harvest plan: Harvest all three: $14,000 + $6,500 + $2,100 = $22,600 in total losses — $7,400 short of the $30,000 target, so every harvested dollar is consumed offsetting gains and the $3,000 ordinary-income offset is not reached
- $5,000 ST losses offset $5,000 ST gains at 45.8% = $2,290 saved
- $1,500 remaining ST losses cross over to offset LT gains at 28.8% = $432 saved
- $16,100 LT losses ($14,000 A + $2,100 C) offset $16,100 of $22,000 LT gains at 28.8% = $4,637 saved
- Remaining taxable LT gains: $22,000 - $16,100 - $1,500 = $4,400 still taxable
- Total tax savings: $2,290 + $432 + $4,637 = $7,359
- Coordinate with rebalancing: Position A is also 2% overweight — its TLH sell doubles as a rebalance sell, saving one round-trip trade.
Example 3: Wash-Sale Violation Across Accounts
Given:
- On November 5, client sells VTI (Vanguard Total Stock Market ETF) in taxable account for a $8,000 long-term loss
- On November 20 (15 days later), client's 401(k) makes its regular bi-weekly contribution, which includes an allocation to a Vanguard Total Stock Market Index Fund (institutional share class of the same fund)
- 401(k) contribution to the total stock market fund: $750
Calculate: Wash-sale impact and corrected cost basis.
Solution:
- Wash-sale triggered: The 401(k) fund is substantially identical to VTI (same underlying index, same fund family). The purchase on November 20 falls within the 30-day post-sale window (November 5 + 30 = December 5).
- Disallowed loss: The wash-sale disallowance is proportional to the replacement shares acquired. If 500 VTI shares were sold and the $750 401(k) purchase acquired the equivalent of approximately 3 shares at $250/share, then 3/500 = 0.6% of the loss is disallowed.
- Disallowed amount: $8,000 * (3/500) = $48 disallowed
- Remaining allowable loss: $8,000 - $48 = $7,952 — still deductible
- Basis adjustment — 401(k) trap: The $48 disallowed loss would normally be added to the replacement security's cost basis. However, because the replacement was purchased inside a 401(k), the cost basis adjustment provides NO future tax benefit (401(k) distributions are taxed as ordinary income regardless of basis). The $48 is permanently lost.
- Prevention: Before executing TLH, review the client's 401(k) fund lineup and contribution schedule. If the 401(k) holds a substantially identical fund, either (a) temporarily redirect that 401(k) allocation to a non-identical fund during the wash-sale window, or (b) delay the TLH sale until after the next 401(k) contribution and ensure no contribution occurs for 30 days after.
Common Pitfalls
- Harvesting losses without checking for substantially identical holdings in retirement accounts, triggering permanent loss disallowance in IRAs/401(k)s
- Forgetting to suspend DRIP on the sold security and related funds across all household accounts during the 61-day window
- Harvesting small losses (under $1,000) where transaction costs and operational complexity exceed the tax benefit
- Over-harvesting in early years, depressing cost basis so severely that future sales generate outsized gains (basis step-down compounding)
- Failing to coordinate with spouse's automated investments (401(k) payroll contributions, robo-advisor purchases)
- Selecting a replacement security that is substantially identical (same index, same fund family, different share class) — this does not avoid wash-sale rules
- Not tracking the holding period of replacement securities, leading to unintended short-term gains when the replacement is later sold
- Ignoring state tax differences when calculating harvest value — states with no income tax (FL, TX, NV) reduce the benefit by 5-13 percentage points versus high-tax states
Cross-References
- tax-efficiency (wealth-management plugin): broader tax-aware investing context; TLH is one strategy within the overall tax-efficiency framework
- rebalancing (wealth-management plugin): TLH trades should be coordinated with rebalancing to minimize total transaction count
- investment-suitability (compliance plugin): replacement securities must still satisfy suitability requirements
- investment-policy (wealth-management plugin): IPS may specify TLH policy parameters (minimum loss threshold, approved replacement pairs)
- performance-attribution (wealth-management plugin): tax alpha from TLH should be tracked and attributed separately
- client-review-prep (advisory-practice plugin): TLH opportunities are flagged during periodic client review preparation
- financial-planning-workflow (advisory-practice plugin): TLH is a specific tax recommendation that may emerge from the financial plan
- equity-compensation (wealth-management plugin): recurring RSU vests and ESPP purchases can trigger wash sales against losses harvested in employer stock
FAQ
What does the tax-loss-harvesting skill do?
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.
How do I install tax-loss-harvesting?
Run npx skills add https://github.com/joellewis/finance_skills --skill tax-loss-harvesting in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tax-loss-harvesting/ (personal) or .claude/skills/tax-loss-harvesting/ (project).
Which AI agents can use tax-loss-harvesting?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is tax-loss-harvesting safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains tax-loss-harvesting?
It is published by joellewis in joellewis/finance_skills. It has 687 recorded installs.
More from joellewis/finance_skills
asset-allocation
joellewis/finance_skills
Determine how to distribute capital across asset classes using strategic and tactical allocation frameworks. Use when the user asks about portfolio allocation, mean-variance optimization, Black-Litterman, risk parity, glide paths, or target-date strategies. Also trigger when users mention 'how much in stocks vs bonds', '60/40 portfolio', 'policy portfolio', 'core-satellite', 'liability-driven investing', 'asset-liability matching', or ask how to split their money across investments.
statistics-fundamentals
joellewis/finance_skills
Apply statistical methods to financial data including descriptive statistics, covariance estimation, regression, hypothesis testing, and resampling. Use when the user asks about return distributions, correlation between assets, building a covariance matrix, running a CAPM regression, testing whether alpha is significant, checking if returns are normal, or estimating confidence intervals. Also trigger when users mention 'volatility', 'how correlated are these', 'fat tails', 'skewness', 'R-squared', 'beta of a fund', 'bootstrap a Sharpe ratio', 'shrinkage estimator', 'Ledoit-Wolf', or ask why their optimizer produces unstable weights.
quantitative-valuation
joellewis/finance_skills
Estimate intrinsic value of stocks and companies using DCF, dividend discount models, comparable multiples, and residual income. Use when the user asks about discounted cash flow, DCF models, WACC, terminal value, dividend discount models, comparable multiples, or sum-of-the-parts valuation. Also trigger when users mention 'what is this stock worth', 'fair value estimate', 'Gordon growth model', 'free cash flow valuation', 'cost of equity', 'sensitivity analysis', 'exit multiple', or ask whether a stock is overvalued or undervalued.
finance-psychology
joellewis/finance_skills
Recognize and mitigate cognitive biases that impair financial decisions, and coach clients toward values-driven financial lives. Use when the user asks about behavioral finance, money psychology, loss aversion, overconfidence, herd behavior, or emotional investing. Also trigger when users mention 'why do I panic sell', 'money fights with my spouse', 'I can never save enough', 'fear of investing', 'lifestyle creep', 'keeping up with the Joneses', 'Rich Life', 'money scripts', or ask how emotions affect financial decisions.
commodities
joellewis/finance_skills
Analyze commodity markets including futures curve dynamics, roll yield, and supply/demand fundamentals. Use when the user asks about commodity investing, commodity ETFs, contango, backwardation, roll yield, commodity indices (GSCI, BCOM), or commodities as an inflation hedge. Also trigger when users mention 'oil prices', 'gold as a safe haven', 'agricultural futures', 'convenience yield', 'storage costs', 'natural gas', 'copper demand', or ask why commodity ETF returns differ from spot price changes.
investment-policy
joellewis/finance_skills
Construct comprehensive Investment Policy Statements governing return objectives, risk tolerance, and portfolio constraints. Use when the user asks about building an IPS, setting return objectives, assessing risk tolerance, defining investment constraints, or establishing rebalancing and benchmark policies. Also trigger when users mention 'investment plan', 'policy portfolio', 'risk capacity vs willingness', 'spending rate for an endowment', 'foundation payout', 'manager selection criteria', or ask how to document their investment strategy.
Popular security skills
azure-compliance
microsoft/azure-skills
Run Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment.
minimal-run-and-audit
lllllllama/rigorpilot-skills
Rigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation command and write standardized reprooutputs/ files, including patch notes when repository files changed. Do not use for training execution, initial repo intake, generic environment setup, paper lookup, target selection, hidden scientific-meaning changes, or end-to-end orchestration by itself.
seo-audit
coreyhaines31/marketingskills
When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," "indexing issues," "stuck on page 2," "striking distance keywords," "title tag rewrite," "low CTR," "local SEO," "Google Business Profile," or "map pack." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema. For AI search optimization, see ai-seo.
firebase-security-rules-auditor
firebase/agent-skills
Audits Firebase (Firestore, Cloud Storage) security rules for vulnerabilities, privilege escalation, role bypasses, create vs update inconsistencies, resource exhaustion, type safety, size limits, and hasOnly ownership checks. Use when auditing/reviewing rules, running red-team rule assessments, or scoring against auditor checklists. Don't use for Firebase CLI (login, deploy), Auth, Crashlytics, Remote Config, or database queries.
audit
pbakaus/impeccable
Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.
competitors
coreyhaines31/marketingskills
When the user wants to create competitor comparison or alternative pages for SEO and buyer-facing use. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'competitor teardown,' 'audit our competitor pages,' 'are our comparison pages out of date,' or 'competitive asset audit.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For auditing existing claims (not researching competitors from scratch, which is competitor-profiling; not technical SEO on these pages, which is seo-audit), use the asset audit here. For internal battle cards and sales-specific competitor docs, see sales-enablement.