ss-tax-torpedo
Skill0 starsChanged 5 months agoMITView on GitHub
Model the Social Security provisional-income tax torpedo and survivor single-filer cliffs
In this repository21 other files it gives its agents.
- ceoSkill
- comprehensive-planSkill
- ctoSkill
- debt-and-cashflowSkill
- deferred-compSkill
- divorce-financial-planningSkill
- equity-comp-plannerSkill
- finance-explainerSkill
- financial-forecastSkill
- fire-trackerSkill
- growth-engineSkill
- head-of-designSkill
- long-term-rental-analyzerSkill
- portfolio-rebalancerSkill
- relocation-plannerSkill
- rent-vs-buySkill
- retirement-incomeSkill
- self-employed-plannerSkill
- startup-equity-plannerSkill
- str-investment-analyzerSkill
- tax-optimizerSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
All math + financial logic live server-side.
- Distinctive: line 22
If they're NOT available, tell the user to connect the MCP, then continue:
- Very specific: line 37
Ask only for what the user's question needs.
- Very specific: line 40
Optional but recommended: call generate_financial_plan with whatever household model you have.
- Very specific: line 87
After the torpedo tool gives the fill_to_ceiling, size the actual conversion.
- Very specific: line 130
If decumulating: analyze_rmd to size the forced withdrawal, then re-run the torpedo with it as other_taxable_income.
- Distinctive: line 139
All decimals are fractions.
- Distinctive: line 141
Not financial advice. Planning estimates only (approximate ~2026 brackets/limits).
≈ “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
ss-tax-torpedo
A thin orchestration layer over the planfi MCP (https://ai.planfi.app/mcp/free). All math + financial logic live server-side. This skill only gathers inputs and calls the tools — it does not compute anything locally, carries no business logic, math, or defaults, and is read-only (it never changes the user's data). The server is the source of truth.
Step 0 — Make sure the planfi tools are connected
This skill uses these tools (may be namespaced, e.g. mcp__planfi__analyze_ss_tax_torpedo):
analyze_ss_tax_torpedo, analyze_roth_conversion, analyze_irmaa, analyze_rmd,
analyze_survivor_stress_test, optimize_social_security, plus optional generate_financial_plan
(to mint a plan_id for chaining + a share_url). Use whichever name your environment exposes
(bare or mcp__planfi__-prefixed); below they are written bare.
If they're NOT available, tell the user to connect the MCP, then continue:
claude mcp add --transport http planfi https://ai.planfi.app/mcp/freeTry free, then add your key. The command above adds the free connector —
https://ai.planfi.app/mcp/free(no key needed). Once you create an API key, add a new connector with the MCP url —https://ai.planfi.app/mcp— and authorize it with your key.
(On claude.ai: add a custom connector pointing at https://ai.planfi.app/mcp/free.)
Access — free for personal use. The planfi MCP is free to try (a small monthly allowance, no key needed). Heavy automated abuse forced us to add limits — but it stays free for personal use: email kam@rateapi.dev and we'll send you a free API key, no charge. (Companies and commercial use have paid plans.) To use a key, pass it as an
Authorization: Bearer pft_…header in your MCP client config.
Step 1 — Gather inputs (prefer a plan_id)
Ask only for what the user's question needs. Every input has a sensible server default, so the
tools run cold — but the cleanest path is to mint a plan_id first and chain off it:
- Optional but recommended: call
generate_financial_planwith whatever household model you have. CAPTURE the returnedplan_idand theshare_url. Pass{ plan_id }to every specialist tool below — any field you also pass becomes a shallow override. This is also the ONLY way to get ashare_url(the specialist tools don't emit one). - Or run cold: pass the specialist tool its required raw inputs directly. Anything omitted is
defaulted server-side and reported in
assumed_defaults[].
Engine facts to bake in: all dollars are today's (real) dollars; all decimals are fractions (24% →
0.24); tax brackets/limits are ~2026 values (the §86 $25k/$32k and $34k/$44k provisional thresholds are statutory and have NOT been inflation-indexed since 1983/1993 — they bite harder every year). Noted in each tool'sdisclosures.
Step 2 — Route by intent
"Will my Social Security get taxed if I do a Roth conversion / take an RMD / realize gains?" / "what's the Social Security tax torpedo?" / "why is my marginal rate 40%+ when I'm only in the 22% bracket?" / "how much can I convert before more of my SS becomes taxable?" / "what happens to my taxes as a widow filing single?" → analyze_ss_tax_torpedo
Always CALL analyze_ss_tax_torpedo for these — do not answer from general knowledge or quote
the $25k/$32k rule-of-thumb from memory. When the user gives the SS benefit + other income +
filing status, run it and lead with its real effective_marginal_rate_pct and fill_to_ceiling
output. The tool encodes the exact IRC §86 / Pub 915 provisional-income formula, the
effective-vs-nominal marginal rate and torpedo multiplier, the marginal-rate curve, the torpedo
zone boundaries, the optimal fill-to ceiling, an IRMAA cross-reference, and the widowed
single-filer cliff. Rules of thumb get the cliff wrong — call the tool.
REQUIRED: annual_ss_benefit. Optional: other_taxable_income (RMDs / pension / IRA withdrawals /
wages, default 0), qualified_dividends_ltcg (default 0), tax_exempt_interest (muni interest —
raises provisional income even though tax-free, default 0), filing_status
(single | married_joint, default single — drives both the §86 thresholds AND the survivor
cliff), current_age (feeds IRMAA cross-ref), marginal_dollars (income-sweep span, default
100000), tax_year (default 2026), plan_id, overrides.
Returns: ss_taxability_tier (0%/50%/85%), taxable_ss_amount + taxable_ss_fraction_pct,
effective_marginal_rate_pct vs nominal_marginal_rate_pct + torpedo_multiplier, torpedo_zone
(start/end provisional + peak rate), marginal_rate_curve, fill_to_ceiling
(provisional_ceiling, additional_income_room, binding_constraint), irmaa_cross_reference,
survivor_single_filer (null when filing single).
analyze_ss_tax_torpedo({
annual_ss_benefit: 30000,
other_taxable_income: 40000,
filing_status: "married_joint",
current_age: 70
})"How much can I convert to Roth this year?" → analyze_roth_conversion
After the torpedo tool gives the fill_to_ceiling, size the actual conversion. Self-orchestrating
ladder. Optional plan_id. Use the torpedo's ceiling as the target so the conversion stops before
it drags more SS into the 85% tier.
"Will this push my Medicare premiums up (IRMAA)?" → analyze_irmaa
The torpedo tool returns an irmaa_cross_reference; for the full two-year-lookback surcharge
schedule and the MAGI thresholds, call analyze_irmaa directly. Optional plan_id.
"What will my RMD be / how big is the forced withdrawal?" → analyze_rmd
RMDs are the most common torpedo trigger. Size the RMD, then feed it as other_taxable_income into
analyze_ss_tax_torpedo. Optional plan_id.
"What happens to our finances / taxes when one of us dies?" → analyze_survivor_stress_test
Broader survivor analysis (income drop, expense changes, portfolio survival). The torpedo tool's
survivor_single_filer block covers the tax cliff specifically; chain to
analyze_survivor_stress_test for the full household picture. Optional plan_id.
"When should I claim Social Security? / claim at 62 vs 67 vs 70 / what's my benefit / what if the trust fund is cut?" → optimize_social_security
Compares claiming ages and returns the breakeven + recommended claim age. Provide earnings_history
({ year, earnings }[] — runs the full SSA pipeline: NAWI indexing, AIME, projected bend points,
dime-floored PIA, COLA compounding, and an optional trust_fund_cut { year, cut_pct }), or
aime, or monthly_amount. Optional birth_year, fra, claim_age, cola_rate,
nawi_growth_rate, plan_id. See the retirement-income skill for the full routing.
Step 3 — Surface the result
- Lead with the headline: the
effective_marginal_rate_pctvs thenominal_marginal_rate_pct(and thetorpedo_multiplier), thess_taxability_tier, and thefill_to_ceiling(additional_income_room+binding_constraint) — "you can add $X more before the torpedo / an IRMAA cliff fires." - For
married_joint, always relay thesurvivor_single_filerblock — the extra tax and extra SS taxed the surviving spouse faces on the same income. assumed_defaults[]—analyze_ss_tax_torpedoreturns a structuredassumed_defaults[](filing status, other income, etc.). Read these back so the user can correct any and re-call.disclosures— relaynot_advice(planning estimate, not tax advice) andkey_assumptions.next_actions[]— each{ tool, why, prefilled_args }; follow the server's suggested chains (typicallyanalyze_roth_conversion,analyze_irmaa) rather than guessing.share_url— onlygenerate_financial_planreturns one; offer it if you minted aplan_id.
Recommended call sequence (typical session)
- (optional)
generate_financial_plan→ captureplan_id+share_url. analyze_ss_tax_torpedowith the SS benefit + other income + filing status (or{ plan_id }).- If decumulating:
analyze_rmdto size the forced withdrawal, then re-run the torpedo with it asother_taxable_income;analyze_roth_conversionto fill to thefill_to_ceiling;analyze_irmaafor the surcharge schedule. - Surface headline + survivor cliff +
assumed_defaults+next_actions+share_url.
Notes
- See also the tax-optimizer and retirement-income skills — the torpedo is the tax-aware decumulation overlay that sits between them (Roth-conversion ladder ↔ IRMAA cliff ↔ RMD timing).
- All decimals are fractions; all dollars are today's (real) dollars.
- The §86 thresholds are statutory and un-indexed — confirm
tax_yearis 2026 unless told otherwise. - Not financial advice. Planning estimates only (approximate ~2026 brackets/limits).
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.

