Agent skill

Tax Efficiency

by JoelLewis in JoelLewis/finance_skills

Maximizes after-tax returns through strategic asset location, gain/loss management, and withdrawal sequencing.

MITAuto-check passedBusiness, Finance & HR

Install Tax Efficiency

skills CLI
$ npx skills add JoelLewis/finance_skills --skill tax-efficiency -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install JoelLewis/finance_skills tax-efficiency --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/JoelLewis/finance_skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/wealth-management/skills/tax-efficiency .claude/skills/tax-efficiency && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
tax-efficiency
GitHub stars
205
Token cost
~3k tokens
SKILL.md length
1,496 words
Files
2 (incl. scripts)
Skills in repo
91
Repo updated
First seen
Licence
MIT

At a glance

Maximizes after-tax returns through strategic asset location, gain/loss management, and withdrawal sequencing.

  • Works in 6 steps: Optimal placement: Bonds ($500K) in IRA;… → Naive placement (50/50 each): Taxable… → Tax drag — naive: Taxable bonds: $250K ×… → …
  • The user asks about asset location
  • SKILL.md covers Core Concepts, Key Formulas, Worked Examples and Common Pitfalls, plus 2 more sections
  • Runs Python scripts from its folder; calls uv, python3 and pip

What it does

Tax Efficiency is an agent skill from JoelLewis/finance_skills. Maximizes after-tax returns through strategic asset location, gain/loss management, and withdrawal sequencing. Use when the user asks about asset location, Roth conversions, tax-efficient withdrawals, tax lot selection, or charitable giving with appreciated securities. Also trigger when users mention 'which account should I hold bonds in', 'tax drag', 'Roth vs Traditional', 'RMD planning', 'bracket stuffing', 'HIFO vs FIFO', or ask how to minimize taxes on investments. For tax-loss harvesting execution and…

Its SKILL.md is about 3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/tax_efficiency.py`).

It sits in Business, Finance & HR, covering Tax preparation. The repository describes itself as: Claude Code skill plugins for financial services — 81 skills across 7 domain plugins covering investment management, compliance, advisory practice, trading, and operations. The licence is MIT.

When your agent uses it

  • The user asks about asset location
  • Roth conversions
  • Tax-efficient withdrawals
  • Tax lot selection

Example prompts

  • “which account should I hold bonds in”
  • “tax drag”
  • “Roth vs Traditional”
  • “/tax-efficiency”

Requirements

  • Python 3

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Optimal placement: Bonds ($500K) in IRA; Equities ($500K) in taxable.
  2. Naive placement (50/50 each): Taxable has $250K bonds + $250K equities; IRA has $250K bonds + $250K equities.
  3. Tax drag — naive: Taxable bonds: $250K × 5% × 32% = $4,000. Taxable equity dividends: $250K × 2% × 15% = $750. Total tax = $4,750.
  4. Tax drag — optimal: Taxable equity dividends only: $500K × 2% × 15% = $1,500. Total tax = $1,500.
  5. Annual tax savings: $4,750 - $1,500 = $3,250/year (0.325% of total portfolio).
  6. Over 20 years compounded, this adds significantly to after-tax wealth.

What it can do on your machine

Read from SKILL.md and the folder at commit 5c498ea. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • uv
    • python3
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv and pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tax Efficiency loads about 3k tokens when it runs. Until then it costs about 146 tokens; SKILL.md has 1,496 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~146
When it runs · the whole SKILL.md, loaded when a task matches
~3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from JoelLewis/finance_skills at commit 5c498ea, republished under its MIT licence (© JoelLewis). 1,496 words, ~3,045 tokens.

Download SKILL.mdSave it as .claude/skills/tax-efficiency/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
tax-efficiency
description
Maximizes after-tax returns through strategic asset location, gain/loss management, and withdrawal sequencing. Use when the user asks about asset location, Roth conversions, tax-efficient withdrawals, tax lot selection, or charitable giving with appreciated securities. Also trigger when users mention 'which account should I hold bonds in', 'tax drag', 'Roth vs Traditional', 'RMD planning', 'bracket stuffing', 'HIFO vs FIFO', or ask how to minimize taxes on investments. For tax-loss harvesting execution and wash-sale mechanics, see the tax-loss-harvesting skill.

Tax-Efficient Investing

Core Concepts

Asset Location

Place tax-inefficient assets in tax-advantaged accounts and tax-efficient assets in taxable accounts:

  • Tax-deferred accounts (Traditional IRA, 401k): Bonds, REITs, high-turnover funds, TIPS — assets generating ordinary income
  • Tax-exempt accounts (Roth IRA, Roth 401k): Highest expected growth assets — all growth is permanently tax-free
  • Taxable accounts: Index equity funds (low turnover, qualified dividends, tax-loss harvesting eligible), municipal bonds, tax-managed funds

The benefit of asset location increases with the spread between ordinary income tax rates and capital gains rates, and with the size of the tax-advantaged accounts relative to total portfolio.

Tax-Loss Harvesting (TLH)

Realize investment losses to offset capital gains, reducing current tax liability while maintaining market exposure:

  • Sell a losing position, immediately buy a similar (but not "substantially identical") replacement
  • Harvested losses offset gains dollar-for-dollar; net losses offset up to $3,000 of ordinary income per year; excess carries forward indefinitely
  • Wash-sale rule (61-day window): Cannot repurchase the same or substantially identical security within the 61-day window (30 days before + sale date + 30 days after) — applies across all accounts (including spouse's accounts and IRAs)
  • Tax alpha from TLH: Estimated 0.5-1.5% per year in early years of a portfolio's life, declining as cost basis rises
  • Best opportunities arise during market volatility and in the first few years of investing
After-Tax Return

Different income types face different tax rates:

  • Interest income: Taxed at ordinary income rates
  • Qualified dividends: Taxed at long-term capital gains rates (0%, 15%, or 20% + 3.8% NIIT)
  • Short-term capital gains (held ≤ 1 year): Ordinary income rates
  • Long-term capital gains (held > 1 year): Preferential rates (0%, 15%, or 20% + 3.8% NIIT)
  • The 3.8% NIIT applies above $250,000 MAGI (MFJ) — a statutory threshold that is not inflation-indexed
  • After-tax return on income: R_at = R × (1 - t)
  • Capital gains are taxed only at realization, providing a deferral benefit
Tax Drag

The annual cost of taxes on investment returns:

  • Tax drag = pre-tax return - after-tax return
  • High-turnover funds generate more short-term gains → higher tax drag
  • Index funds with low turnover minimize tax drag
  • ETFs generally more tax-efficient than mutual funds (in-kind creation/redemption process)
Tax Lot Management

When selling partial positions, the method of selecting which lots to sell affects tax liability:

  • Specific identification: Choose exactly which lots to sell
  • HIFO (Highest In, First Out): Sell highest-cost-basis lots first to minimize gains
  • FIFO (First In, First Out): Default method; may realize larger gains on older lots
  • Tax-optimal: Select lots to minimize current-year tax liability considering holding period and gains/losses
Roth Conversion

Convert Traditional IRA/401k assets to Roth, paying ordinary income tax now for tax-free growth and withdrawals later:

  • Breakeven analysis: Conversion is beneficial if current marginal tax rate < expected future marginal tax rate
  • Factors favoring conversion: Long time horizon, low current income year, expectation of higher future rates, desire to reduce future RMDs, estate planning benefits
  • Partial conversions: Convert just enough to fill current tax bracket ("bracket stuffing")
  • Tax on conversion: conversion amount × current marginal rate
Required Minimum Distributions (RMDs)

Mandatory annual withdrawals from tax-deferred accounts (Traditional IRA, 401k) beginning at age 73 (under SECURE 2.0, rising to 75 in 2033):

  • RMD = account balance (Dec 31 prior year) / distribution period (from IRS Uniform Lifetime Table)
  • Failure penalty: 25% excise tax on shortfall (reduced from prior 50%)
  • RMDs are taxed as ordinary income and can push retirees into higher brackets
  • Roth IRAs have no RMDs during the owner's lifetime
Withdrawal Sequencing

The order of withdrawals from different account types in retirement:

  • General rule: Taxable → Tax-deferred → Roth (preserves tax-free growth longest)
  • Optimized approach: Withdraw from taxable first, then fill low tax brackets with tax-deferred withdrawals, use Roth to avoid bracket jumps
  • Dynamic strategy: Adjust each year based on income, deductions, and bracket thresholds
Charitable Giving Strategies
  • Donate appreciated stock: Avoid capital gains tax and deduct full fair market value (must be held > 1 year)
  • Qualified Charitable Distributions (QCDs): Donate up to $111,000/year (2026 limit, indexed annually) directly from IRA to charity (counts toward RMD, excluded from taxable income); available at age 70½+
  • Donor-Advised Funds (DAFs): Bunch multiple years of donations for itemized deduction, invest tax-free, distribute to charities over time

Key Formulas

FormulaExpressionUse Case
After-tax return (income)R_at = R × (1 - t)Bond/interest income after tax
After-tax return (deferred gains)R_at = ((1 + R)^n × (1 - t_cg) + t_cg)^(1/n) - 1Unrealized equity with deferral benefit
Tax-loss harvesting valueTLH_value = loss × marginal_tax_rateImmediate tax benefit of harvesting
Roth conversion breakevent_now < t_futureConvert when current rate < future rate
RMD amountRMD = balance_Dec31 / distribution_periodRequired minimum distribution
Appreciated-stock donation benefitTax saved = FMV × t_income + gain × t_cg_avoidedTax benefit of donating appreciated stock (deduction + avoided gains tax)

Worked Examples

Example 1: Asset location optimization

Given: $500K in taxable brokerage + $500K in Traditional IRA. Portfolio target: 50% bonds (yielding 5%) and 50% equities (expected 10% total return, 2% qualified dividends). Marginal tax rate: 32% ordinary, 15% LTCG. Calculate: Optimal asset placement and annual tax savings vs naive allocation. Solution:

  1. Optimal placement: Bonds ($500K) in IRA; Equities ($500K) in taxable.
  2. Naive placement (50/50 each): Taxable has $250K bonds + $250K equities; IRA has $250K bonds + $250K equities.
  3. Tax drag — naive: Taxable bonds: $250K × 5% × 32% = $4,000. Taxable equity dividends: $250K × 2% × 15% = $750. Total tax = $4,750.
  4. Tax drag — optimal: Taxable equity dividends only: $500K × 2% × 15% = $1,500. Total tax = $1,500.
  5. Annual tax savings: $4,750 - $1,500 = $3,250/year (0.325% of total portfolio).
  6. Over 20 years compounded, this adds significantly to after-tax wealth.
Show full SKILL.md (603 more words)Show less
Example 2: Roth conversion breakeven

Given: Consider converting $50,000 from Traditional IRA to Roth. Current marginal tax rate: 24%. Tax on conversion paid from outside funds. Investment horizon: 20 years. Expected return: 7%. Simplifying assumption: Assume the $12,000, if not used for conversion tax, would grow at the same 7% with no tax drag — i.e., side-fund growth itself is untaxed. Calculate: Future marginal tax rate at which conversion breaks even. Solution:

  1. Cost of conversion now: $50,000 × 24% = $12,000 tax paid today.
  2. Traditional IRA path: $50,000 grows to $50,000 × (1.07)^20 = $193,484. After-tax at withdrawal: $193,484 × (1 - t_future).
  3. Roth path: $50,000 grows to $193,484 tax-free, but the $12,000 side fund forgoes growth to $12,000 × (1.07)^20 = $46,436. Roth net value: $193,484 - $46,436 = $147,048.
  4. Breakeven: Set Traditional after-tax = Roth net value. $193,484 × (1 - t_future) = $193,484 - $46,436 → t_future = $46,436 / $193,484 = 24.0%.
  5. Conclusion: Under this simplification the breakeven future rate equals the current rate (24%) — both sides scale by the same (1.07)^20, so the horizon and return cancel. In reality the taxable side fund suffers tax drag on its dividends and realized gains, so paying conversion tax from outside funds tilts the comparison toward Roth even when the future rate merely equals the current rate.

Common Pitfalls

  • TLH wash sale violations, including purchases in other accounts, IRAs, or a spouse's account within the 61-day wash-sale window (30 days before through 30 days after the sale)
  • Over-harvesting losses that defer gains to higher tax brackets later (basis step-down compounds)
  • Not considering state taxes in asset location decisions — state tax treatment varies significantly
  • Ignoring the tax benefit of donating appreciated securities vs cash (avoids capital gains and gets full deduction)
  • RMD-driven forced selling at inopportune times — plan withdrawals ahead of deadlines
  • Roth converting too aggressively and pushing into a higher bracket in the conversion year
  • Forgetting the 3.8% Net Investment Income Tax (NIIT) above $250,000 MAGI (MFJ) — a statutory threshold that is not inflation-indexed, so it captures more taxpayers each year
  • Not coordinating tax strategy across spouses' accounts

Cross-References

  • investment-policy (wealth-management plugin): Tax constraint in IPS governs asset location and turnover management
  • performance-attribution (wealth-management plugin): After-tax return attribution requires tax-aware calculations
  • debt-management (wealth-management plugin): Mortgage interest deductibility interacts with tax planning
  • savings-goals (wealth-management plugin): Account type selection (Roth vs Traditional) is a core tax decision
  • liquidity-management (wealth-management plugin): Tax implications of accessing different account types affect liquidity planning
  • tax-loss-harvesting (wealth-management plugin): dedicated TLH workflow skill with detailed candidate identification, wash-sale tracking, and execution planning
  • financial-planning-workflow (advisory-practice plugin): tax-aware strategies are core recommendations in comprehensive financial plans
  • financial-statements (wealth-management plugin): cost basis and embedded capital gains fundamentals behind lot selection and deferral decisions
  • insurance-planning (wealth-management plugin): premium-payer decisions drive taxation of disability benefits, annuity income, and life insurance proceeds
  • estate-gifting (wealth-management plugin): owns the transfer-tax side — lifetime exemption, annual exclusion gifting, basis step-up vs carryover, and estate-level charitable structure choice
  • retirement-decumulation (wealth-management plugin): applies withdrawal sequencing and RMD mechanics to retirement spending plans — guardrails, gap-year bracket-filling, and Social Security timing
  • equity-compensation (wealth-management plugin): RSU/option taxation, AMT on ISO exercises, and charitable use of appreciated employer stock extend tax planning to compensation events

Running the script

Run with uv run scripts/tax_efficiency.py (the PEP 723 header resolves dependencies automatically) or with python3 scripts/tax_efficiency.py after pip install numpy scipy. The bare run prints a demo covering after-tax returns, tax drag, TLH benefit, asset location placement, and Roth conversion breakeven. Pass --verify to assert the demo outputs match this skill's worked examples (prints PASS/FAIL), or --help for an overview of the available classes. The file is primarily meant to be imported as a module (e.g., from tax_efficiency import AfterTaxReturn, AssetLocation, BreakevenAnalysis).

© JoelLewis, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in plugins/wealth-management/skills/tax-efficiency of JoelLewis/finance_skills.

  • SKILL.md
  • scripts/tax_efficiency.py

Open the folder on GitHubat commit 5c498ea

Compare with similar skills

Tax Efficiency next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Tax Efficiency compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Tax Efficiency this skillJoelLewis/finance_skills205—~3kAutomated safety check: PassMIT
Itr Walakaranb192/itr-wala871—~3.6kAutomated safety check: PassMIT
Tax Filingrobbalian/claude-tax-filing174—~2.5kAutomated safety check: PassNone
India Itr CopilotLoki200399/india-itr-copilot147—~2.4kAutomated safety check: PassMIT
Consumption Taxkazukinagata/shinkoku365—~1.8kAutomated safety check: PassMIT
Beancount Optionsbex-co/beancount-io296—~3.7kAutomated safety check: PassMIT

Similar skills

  • Itr Wala

    karanb192/itr-wala

    File Indian income tax returns (ITR) for FY 2025-26 / AY 2026-27.

    871 GitHub stars~3.6k tokensUpdated 5 days ago
    Business, Finance & HRAuto-check passed
  • Tax Filing

    robbalian/claude-tax-filing

    Prepare and fill federal and state tax return PDF forms. An agent skill from robbalian/claude-tax-filing.

    174 GitHub stars~2.5k tokensUpdated 5 mo ago
    Business, Finance & HRAuto-check passed
  • India Itr Copilot

    Loki200399/india-itr-copilot

    Documents-first copilot for preparing Indian Income Tax Returns (ITR-1/2/3/4, any assessment year).

    147 GitHub stars~2.4k tokensUpdated 2 mo ago
    Business, Finance & HRAuto-check passed
  • Consumption Tax

    kazukinagata/shinkoku

    This skill should be used when the user needs to calculate consumption tax (消費税) or determine their tax method (2割特例, 簡易課税, or 本則課税).

    365 GitHub stars~1.8k tokensUpdated 1 mo ago
    Business, Finance & HRAuto-check passed
  • Beancount Options

    bex-co/beancount-io

    Record a described options trade or lifecycle event as validated Beancount transactions through bea, after review and confirmation.

    296 GitHub stars~3.7k tokensUpdated today
    Business, Finance & HRAuto-check passed
  • Invoice Organizer

    davila7/claude-code-templates

    Automatically organizes invoices and receipts for tax preparation by reading messy files, extracting key information, renaming them consistently, and sorting them into logical folders.

    32k GitHub starsUsed in 12 repos~2.9k tokens
    Business, Finance & HRAuto-check passed

More from JoelLewis/finance_skills

All 91 skills in this repo
  • Asset Allocation

    JoelLewis/finance_skills

    Determine how to distribute capital across asset classes using strategic and tactical allocation frameworks.

    205 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed
  • Bet Sizing

    JoelLewis/finance_skills

    Determine how much capital to allocate to individual positions within a portfolio.

    205 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed
  • Commodities

    JoelLewis/finance_skills

    Analyze commodity markets including futures curve dynamics, roll yield, and supply/demand fundamentals.

    205 GitHub stars~1.9k tokensUpdated 2 mo ago
    Auto-check passed
  • Currencies And Fx

    JoelLewis/finance_skills

    Analyze currency markets, exchange rate mechanics, and FX risk management for international portfolios.

    205 GitHub stars~1.9k tokensUpdated 2 mo ago
    Auto-check passed
  • Debt Management

    JoelLewis/finance_skills

    Provide frameworks for managing and paying off personal debt effectively.

    205 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed
  • Diversification

    JoelLewis/finance_skills

    Build diversified portfolios using correlation analysis, efficient frontier construction, and factor-based diversification.

    205 GitHub stars~2.3k tokensUpdated 2 mo ago
    Auto-check passed

Questions about Tax Efficiency

What does Tax Efficiency do?

Maximizes after-tax returns through strategic asset location, gain/loss management, and withdrawal sequencing. Tax Efficiency is an agent skill from JoelLewis/finance_skills. Maximizes after-tax returns through strategic asset location, gain/loss management, and withdrawal sequencing.

When should I use Tax Efficiency?

Tax Efficiency fits situations like: the user asks about asset location; roth conversions; tax-efficient withdrawals; tax lot selection.

How do I install Tax Efficiency in Claude Code?

Run `npx skills add JoelLewis/finance_skills --skill tax-efficiency -a claude-code`. Or copy the skill folder (plugins/wealth-management/skills/tax-efficiency in JoelLewis/finance_skills) into .claude/skills/tax-efficiency in your project. Claude Code loads it when a task matches its description.

How do I install Tax Efficiency in Codex?

Run `npx skills add JoelLewis/finance_skills --skill tax-efficiency -a codex`. Or copy the skill folder (plugins/wealth-management/skills/tax-efficiency in JoelLewis/finance_skills) into .agents/skills/tax-efficiency in your project. Codex loads it when a task matches its description.

Can I use Tax Efficiency in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add JoelLewis/finance_skills --skill tax-efficiency -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tax-efficiency, .gemini/skills/tax-efficiency, .github/skills/tax-efficiency and .opencode/skills/tax-efficiency in your project.

What does Tax Efficiency need to run?

Going by SKILL.md and its folder, Tax Efficiency needs Python for the scripts in its folder and the command-line tools its instructions call (uv, python3 and pip). Our summary lists: Python 3.

Does Tax Efficiency access the network?

SKILL.md contains no URLs. Its commands use uv and pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Tax Efficiency safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Tax Efficiency use?

Tax Efficiency is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Tax Efficiency use?

About 3k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Tax Efficiency?

Skills that share tags, products or a category with Tax Efficiency: Itr Wala (karanb192/itr-wala, 871 stars), Tax Filing (robbalian/claude-tax-filing, 174 stars), India Itr Copilot (Loki200399/india-itr-copilot, 147 stars) and Consumption Tax (kazukinagata/shinkoku, 365 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Tax Efficiency?

JoelLewis (a GitHub user) maintains it in JoelLewis/finance_skills, which has 205 GitHub stars. The repository holds 91 skills in this directory. The repository was last updated on July 18, 2026.

Source: JoelLewis/finance_skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.