tax-harvester
Skill2 starsChanged 5 months agoMITView on GitHub
Tax-loss harvesting analysis: identify unrealized losses in the portfolio that can be realized to offset capital gains, estimate tax savings, and suggest replacement assets to maintain market exposure. Handles Turkish tax rules (Türk vergi mevzuatı) and common international frameworks.
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- chart-readerSkill
- credit-analyzerSkill
- dcf-thinkingSkill
- drip-optimizerSkill
- earnings-reviewerSkill
- finops-agentSkill
- gl-reconcilerSkill
- kyc-screenerSkill
- macro-calendarSkill
- macro-stressSkill
- market-researcherSkill
- ma-screenerSkill
- meeting-preparerSkill
- model-builderSkill
- monte-carloSkill
- month-end-closerSkill
- options-pricerSkill
- pdf-analyzerSkill
- pitch-builderSkill
- statement-auditorSkill
- valuation-reviewerSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Ask the user which framework applies if not evident from the portfolio.
- Very specific: line 40
Read data/portfolio.json. Look for cost_basis field per holding:
- Very specific: line 46
If cost_basis is missing, ask the user to provide purchase prices.
- Very specific: line 49
Read output/latest.json for current prices, or trigger a live refresh via /api/refresh.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Tax-Loss Harvester
What Claude does here: Claude reads the portfolio + cost basis data, applies the relevant tax rules, and reasons through each holding's harvesting potential — including wash-sale equivalents and reinvestment suggestions. No calculator shortcut; each recommendation is reasoned line by line.
Trigger phrases
- "Vergi hasadı fırsatları var mı?"
- "Tax-loss harvesting analizi yap"
- "Hangi pozisyonları zararla kapatabilirim, vergi avantajı ne?"
- "Capital gains offset opportunities"
- "Year-end tax planning — portföy"
Tax frameworks supported
| Framework | Key rules applied |
| Turkey (BIST equities) | Gains on BIST-listed Turkish equities held > 1 year: exempt. Gains < 1 year: taxed at 10% withholding. Foreign equities: taxed at marginal income tax rate (15–40%). |
| Turkey (foreign equities) | USD/EUR-denominated gains translated to TRY at sale date. Losses in foreign equities can offset foreign gains in same year. |
| Turkey (gold) | Physical gold gains taxed at marginal rate; gold ETFs follow equity rules. |
| Turkey (crypto) | As of 2025: crypto gains taxed at 0.03% transaction tax on gross; no capital gains tax yet. Flag if rules change. |
| Generic / international | Long-term vs short-term holding periods, basic offset rules. User specifies jurisdiction. |
Ask the user which framework applies if not evident from the portfolio.
Phases
Phase 1 — Cost basis read
Read data/portfolio.json. Look for cost_basis field per holding:
{ "id": "NVDA", "quantity": 4, "cost_basis_per_unit": 180.00, "cost_basis_ccy": "USD", "purchase_date": "2024-03-15" }If cost_basis is missing, ask the user to provide purchase prices. Do not fabricate cost basis.
Phase 2 — Current value fetch
Read output/latest.json for current prices, or trigger a live refresh via /api/refresh.
Phase 3 — Unrealized P&L per holding
For each holding:
unrealized_gain_loss = (current_price - cost_basis_per_unit) × quantity
holding_period_days = today - purchase_date
short_or_long_term = "short" if days < 365 else "long"
tax_treatment = <per framework above>Phase 4 — Harvest candidates
Identify holdings where:
unrealized_gain_loss < 0(loss position)- Harvesting the loss would offset existing gains elsewhere in the portfolio
- A reasonable replacement asset exists (avoids wash-sale equivalent: same ticker, same ETF, near-identical exposure)
Rank by: |unrealized_loss| × applicable_tax_rate (estimated tax saving).
Phase 5 — Replacement suggestions
For each harvest candidate, suggest a replacement that:
- Maintains similar market exposure
- Is NOT the same security or near-identical ETF (wash-sale risk)
- Is available on the same exchange
| Original | Replacement example |
| NVDA | AMD, SMCI, or a broad semiconductor ETF |
| BIST energy (TUPRS) | Another BIST energy (AYGAZ, PETKM) or BIST100 ETF |
| Gold ETF | Physical gold fund or silver ETF |
| BTC | ETH (different blockchain, different tax lot) |
Phase 6 — Tax savings estimate
harvest_candidate: NVDA
unrealized loss: $X × 4 shares = $Y loss
TRY equivalent: ₺Z (at current USD/TRY)
applicable rate: marginal income tax ~27% (example)
estimated tax saved: ₺W
replacement: AMD (maintain semiconductor exposure)
re-entry suggestion: after 30 days (wash-sale window)Phase 7 — Year-end summary
Total estimated tax saving across all harvest candidates. Flag any gains that should be deferred to next year if close to long-term threshold. Flag any positions where harvesting would trigger a significant bid-ask spread cost > tax benefit.
Phase 8 — Output
Write output/tax-harvest-<YYYY>.md:
# Tax-Loss Harvesting Report <Year>
## Portfolio Overview (realized + unrealized)
## Harvest Candidates (ranked by tax saving)
## Replacement Asset Suggestions
## Estimated Total Tax Saving
## Timing Recommendations
## Assumptions & DisclaimersDisclaimer: Tax rules change. Always consult a licensed tax advisor before executing transactions based on this analysis. This is educational output, not tax advice.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

