agentleFS
KameronKalesKameronKales/planfi-skills/skills/ss-tax-torpedo/SKILL.md

ss-tax-torpedo

Skill0 starsChanged 5 months agoMITView on GitHub

Model the Social Security provisional-income tax torpedo and survivor single-filer cliffs

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
  1. Distinctive:

    All math + financial logic live server-side.

    line 10
  2. Distinctive:

    If they're NOT available, tell the user to connect the MCP, then continue:

    line 22
  3. Very specific:

    Ask only for what the user's question needs.

    line 37
  4. Very specific:

    Optional but recommended: call generate_financial_plan with whatever household model you have.

    line 40
  5. Very specific:

    After the torpedo tool gives the fill_to_ceiling, size the actual conversion.

    line 87
  6. Very specific:

    If decumulating: analyze_rmd to size the forced withdrawal, then re-run the torpedo with it as other_taxable_income.

    line 130
  7. Distinctive:

    All decimals are fractions.

    line 139
  8. Distinctive:

    Not financial advice. Planning estimates only (approximate ~2026 brackets/limits).

    line 141

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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/free

Try 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_plan with whatever household model you have. CAPTURE the returned plan_id and the share_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 a share_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's disclosures.

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_pct vs the nominal_marginal_rate_pct (and the torpedo_multiplier), the ss_taxability_tier, and the fill_to_ceiling (additional_income_room + binding_constraint) — "you can add $X more before the torpedo / an IRMAA cliff fires."
  • For married_joint, always relay the survivor_single_filer block — the extra tax and extra SS taxed the surviving spouse faces on the same income.
  • assumed_defaults[] — analyze_ss_tax_torpedo returns a structured assumed_defaults[] (filing status, other income, etc.). Read these back so the user can correct any and re-call.
  • disclosures — relay not_advice (planning estimate, not tax advice) and key_assumptions.
  • next_actions[] — each { tool, why, prefilled_args }; follow the server's suggested chains (typically analyze_roth_conversion, analyze_irmaa) rather than guessing.
  • share_url — only generate_financial_plan returns one; offer it if you minted a plan_id.

Recommended call sequence (typical session)

  1. (optional) generate_financial_plan → capture plan_id + share_url.
  2. analyze_ss_tax_torpedo with the SS benefit + other income + filing status (or { plan_id }).
  3. If decumulating: analyze_rmd to size the forced withdrawal, then re-run the torpedo with it as other_taxable_income; analyze_roth_conversion to fill to the fill_to_ceiling; analyze_irmaa for the surcharge schedule.
  4. 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_year is 2026 unless told otherwise.
  • Not financial advice. Planning estimates only (approximate ~2026 brackets/limits).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.