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
npx skills add rssaghafi/retirement-planner --skill retirement-planner -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/retirement-planner/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/retirement-planner/
1Skills CLI (Vercel)
npx skills add rssaghafi/retirement-planner --skill retirement-planner -a codex2Manually: put the files in place
.agents/skills/retirement-planner/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rssaghafi/retirement-planner --skill retirement-planner -a cursor2Manually: put the files in place
.cursor/skills/retirement-planner/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rssaghafi/retirement-planner retirement-planner2Manually: put the files in place
.github/skills/retirement-planner/SKILL.md1Skills CLI (Vercel)
npx skills add rssaghafi/retirement-planner --skill retirement-planner -a gemini-cli2Platform CLI
gemini skills install https://github.com/rssaghafi/retirement-plannerManually: put the files in place
.devin/skills/retirement-planner/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rssaghafi/retirement-planner --skill retirement-planner -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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