Skip to main content
skill CX Codex

retirement-planner — Claude Code skill: what it does, how to install

retirement-planner builds a detailed retirement readiness plan featuring a 13-tab Excel model with Monte Carlo simulation, an explanatory guide, and a dated checklist.

MIT 1 installs updated 2026-07-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rssaghafi/retirement-planner --skill retirement-planner -a claude-code
Open on GitHub

What retirement-planner does

The skill processes household financial inputs, custodian statements, and spending targets to execute a deterministic Monte Carlo analysis using scripts/retirement_engine.py. Computations run in constant real purchasing power, stripping inflation from return assumptions so results remain grounded and interpretable. It outputs a 13-tab workbook alongside two Word documents containing narrative guidance and scheduled action steps.

The resulting spreadsheet evaluates fixed withdrawal rates from 3% to 4%, tests Guyton-Klinger guardrails, and identifies the minimum portfolio needed to meet spending targets. It also evaluates Social Security timing to safeguard surviving spouses, schedules a Roth conversion ladder below IRMAA thresholds, and maps the health coverage transition from ACA subsidies to Medicare.

Local Python is required to run the simulation engine before building the report. The spreadsheet design enforces strict consistency: the Assumptions sheet serves as the single source of truth, and any unresolved formula error invalidates the deliverable.

What it helps with

  • Calculate safe withdrawal rates across market scenarios using Monte Carlo simulations
  • Determine the optimal claiming age for Social Security benefits and spousal protections
  • Schedule a multi-year Roth conversion ladder within targeted tax and IRMAA brackets
  • Bridge medical coverage from employer plans and ACA subsidies to Medicare

Example prompts for the agent

  • Help me build a retirement plan and determine my safe spending rate
  • Evaluate whether I should claim Social Security at 62, full retirement age, or 70
  • Model a Roth conversion ladder that accounts for ACA healthcare subsidies and IRMAA limits

How to install retirement-planner

1Skills CLI (Vercel)

npx skills add rssaghafi/retirement-planner --skill retirement-planner -a claude-code

2Manually: put the files in place

~/.claude/skills/retirement-planner/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/retirement-planner/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about retirement-planner

How do I install retirement-planner in Claude Code?

Run npx skills add rssaghafi/retirement-planner --skill retirement-planner -a claude-code in your terminal. The configuration is stored at ~/.claude/skills/retirement-planner/SKILL.md.

What outputs does retirement-planner generate?

It produces a formula-driven 13-tab Excel model with Monte Carlo outputs, an explanatory narrative guide in Word format, and a dated action checklist.

What dependencies are needed to run retirement-planner?

The skill relies on local Python to run python scripts/retirement_engine.py profile.json -o results.json before building the spreadsheet and reports.

Source text

SKILL.md · MIT
---
name: retirement-planner
description: >-
  Comprehensive retirement-readiness analysis. Use whenever someone wants to know if they can afford
  to retire, is planning retirement, asks "am I on track / what's my number," or wants a
  safe-withdrawal-rate analysis, Social Security claiming-age advice, a Roth conversion ladder, a
  healthcare/ACA bridge to Medicare, an RMD or IRMAA strategy, an asset-allocation glide path, or a
  survivorship / long-term-care check. Trigger even when the request is partial or casual ("help me
  figure out retirement," "claim Social Security at 62 or 70," "how much can I safely spend") and even
  if they name only one piece. Do NOT trigger for one-off questions a quick answer handles: a lone
  "what age are RMDs" or "Roth vs traditional" definition, a 401(k) match question, a general budget,
  a standalone rebalancing trade, or picking a Medicare Part D or active-employee plan. Produces a
  formula-driven, non-expert-friendly workbook (plus guide and dated checklist) backed by a
  real-dollar Monte Carlo simulation.
---

# Retirement Planner

This skill turns a household's real financial data into an honest, defensible retirement plan: a
13-tab Excel model driven by a Monte Carlo simulation, plus a plain-English guide and a dated action
checklist. It works for any household — the numbers below are illustrative only.

Your job is to be an **intelligent analyst, not a cheerleader**. Retirees are often over-saved and
under-optimized: the interesting answer is usually not "can I retire?" (frequently yes) but "how do I
stop overpaying tax, stop being too conservative, and protect the surviving spouse?" Lead with the
finding that actually matters, even if it's not what they asked.

## The workflow

1. **Intake.** Gather the inputs in `references/intake.md`. Ask in grouped batches, not one at a time.
   If the user has uploaded statements (brokerage, 401k, Social Security, expenses), read those first and
   only ask for what's missing. Reconcile conflicting balances to the primary custodian statement and say so.
2. **Confirm the judgment calls** that materially change the answer before building: target monthly spend,
   life-expectancy/longevity outlook (drives Social Security timing), state of residence (drives ACA + state
   tax on conversions), and whether either spouse lacks their own Social Security record.
3. **Run the engine.** Build a profile JSON and run `scripts/retirement_engine.py` (see below). This does
   every Monte Carlo computation deterministically so you never hand-simulate.
4. **Build the workbook** from `references/workbook_spec.md` — 13 tabs, fully formula-driven, Assumptions tab
   as the single source of truth. Debug to zero formula errors.
5. **Write the two Word documents** — the narrative guide and the dated action checklist.
6. **Verify** cross-tab consistency and deliver all three files.

Order matters only loosely: Roth-conversion sizing, the withdrawal plan, and Social Security timing are
interdependent, so expect to iterate. Read `references/methodology.md` for how each piece is calculated and
why — that file is the analytical backbone; consult it whenever you're unsure how to compute or explain a piece.

## Running the engine

```bash
python scripts/retirement_engine.py profile.json -o results.json
python scripts/retirement_engine.py --example        # prints a sample profile to copy
```

The engine works entirely in **real (today's) dollars** — spending, Social Security (which has a COLA), and
rental/pension income are held flat in today's money, and portfolio returns use real means (nominal minus
inflation). This is deliberate: a non-expert can read "$1.04M in today's dollars" and understand it, whereas a
nominal projection looks alarmingly large for no real reason. It returns: success rate at the current portfolio
(current *and* target allocation), the **true number** (smallest portfolio clearing the success target), a
spending-sensitivity table, fixed-rate withdrawal scenarios (3/3.5/4%), a Guyton-Klinger guardrails run, and
year-by-year percentile paths (P10–P90). Feed those results straight into the Monte Carlo, Withdrawal Scenarios,
and Readiness tabs.

## The six questions every plan should answer

Cover all of these even if the user asked about only one — this is the heart of the value:

1. **Withdrawal scenarios & safe spending** — 4% / 3.5% / 3% / variable-% / guardrails, plus sequence-of-returns risk.
2. **The "true number"** — the portfolio needed to hit the success target at the desired lifestyle.
3. **Social Security timing** — claim now vs FRA vs 70, with breakeven ages, lifetime totals, and — critically —
   the **survivor** consequence for a lower-earning or non-earning spouse. This is usually the single highest-leverage decision.
4. **Roth conversion ladder** — fill the tax-deferred accounts down during the low-income window (post-retirement,
   pre-Social-Security, pre-RMD), sized to a **tax bracket and IRMAA** ceiling. See methodology for the bracket/IRMAA logic.
5. **Healthcare bridge to Medicare** — COBRA → ACA → Medicare timeline, ACA-subsidy-vs-conversion tension, HSA strategy.
6. **Asset-allocation glide path** — most retirees with a large guaranteed-income floor are far too conservative;
   the real long-horizon risk is inflation, not a crash.

## Non-negotiable modeling rules

These prevent the errors that quietly make a plan wrong. Full detail in `references/workbook_spec.md`.

- **The Assumptions tab is the single source of truth.** Every value used in more than one tab is a cell reference
  to Assumptions — never a hardcoded number in another tab. The whole model must recalculate when an assumption changes.
- **Use NET rental cash flow, not NOI.** Net = gross rent − operating expenses − management fee − mortgage P&I.
  Using NOI (which ignores the mortgage) overstates income and can dangerously overstate a survivor's security.
- **Roth-conversion tax is real money leaving the household.** When tax is paid from the IRA, compute the actual
  convertible amount proportionally: `actual_conversion = available / (1 + tax_rate)`; if the account is exhausted,
  the conversion and its tax are both zero — never leave a phantom tax.
- **Two projection tabs must agree.** The detailed account-by-account Withdrawal Strategy and the aggregate
  Year-by-Year tab must reconcile to the dollar for every year. If they diverge, a driver is inconsistent — find it.
- **Zero formula errors before delivery.** Recalculate the file and fix every `#REF!/#DIV/0!/#VALUE!/#N/A/#NAME?`.
  A clean recalc proves formulas *evaluate*, not that they're *right* — spot-check a few cells against the engine output.
- **Partial first year.** If they retire mid-year, the first calendar year is a partial year of spending, and their
  wages/severance that year affect that year's conversion headroom and IRMAA — don't model a full year of draws.

## Tone and honesty

Write for a smart non-expert. Explain *why*, not just *what*. Take a position and defend it with the numbers.
Flag the real trade-offs (IRMAA vs conversion size; ACA subsidy vs conversion; longevity vs claiming age) rather
than hiding them. This is educational analysis of the user's own data — **not** tax, legal, or investment advice;
say so, and point them to a fee-only fiduciary and a CPA for execution. Never invent liabilities or assets the
user didn't give you; if something is an assumption, label it as one where the reader will see it.

## Deliverables

Three files, named for the household (e.g. `Smith_`):

| File | What it is |
|---|---|
| `<Name>_Retirement_Analysis.xlsx` | The 13-tab formula-driven model — the analytical engine |
| `<Name>_Retirement_Plan_Guide.docx` | Narrative companion: explains every tab, the key decisions, a glossary |
| `<Name>_Retirement_Action_Checklist.docx` | Chronological, dated checklist with checkboxes and tab references |

## Reference files

- `references/intake.md` — the full input checklist and the clarifying questions to ask.
- `references/methodology.md` — how each calculation works and how to explain it (withdrawal rates, sequence risk,
  Social Security & survivor math, Roth ladder with bracket/IRMAA logic, RMDs, healthcare bridge, glide path, LTC/life).
- `references/workbook_spec.md` — the 13-tab layout, column-by-column, with formula patterns and the critical rules.

© rssaghafi · MIT · rssaghafi/retirement-planner

Similar skills

All skills for Finance and business →
retirement-decumulation JoelLewis retirement-decumulation helps calculate sustainable retirement drawdowns from investment portfolios. It models safe withdrawal rates, Guyton-Klinger guardrails, Social Security claiming ages, and RMD requirements. CX Codex +1 382installs Cinderfi — Retirement Planning cinderfi Cinderfi — Retirement Planning is an MCP server for Claude Code that models retirement plans in Canada and the US, including tax scenarios and benefit timing. It needs a Cinderfi API key. CX Codex +1 ★ 2repo stars financial-planning-workflow JoelLewis financial-planning-workflow walks an advisor through the whole planning engagement: intake, cash flow, retirement modeling, Monte Carlo, withdrawal sequencing and Roth conversion. CX Codex +1 786installs budget-planner genspark-ai budget-planner turns a business plan or project spend into an Excel budget with account lines, a monthly spread, summaries and a separate assumptions sheet. CX Codex +1 ★ 12,746repo stars financial-scenario-planner travisjneuman financial-scenario-planner runs a financial plan through bear, base and bull cases, then adds sensitivity tables, break-even and a runway check. Useful when the assumptions behind a model need testing. CX Codex +1 156installs financial-goal-planner OneWave-AI financial-goal-planner is a Claude Code skill that plans savings for a home down payment, retirement, or college. It sets timelines and monthly targets, suggests investment strategies, and tracks milestones. CX Codex +1 373installs

Project sponsors

Companies that keep this analytics open