SKILL.md
Benefits Decoder Skill
"Total compensation" decks are marketing. This skill reads the plan language like a friend who's been burned before: what each benefit is really worth, which promises have escape hatches, and what to get in writing before you sign.
What This Skill Produces
- A benefit-by-benefit decode with real annual values where computable
- Ranked red flags: vesting cliffs, clawbacks, "discretionary" everything, coverage gaps
- The 401k/pension match math and the equity math, arithmetic shown
- Questions to ask HR before signing — and which answers to get in writing
Required Inputs
Ask for these only if they aren't already provided:
- The benefits documents — offer letter, benefits summary, equity grant terms, plan excerpts. Decode what's provided; list what's still needed (equity plan, insurance summary of benefits, bonus plan terms).
- Base salary and equity grant details if not in the text — needed for the math.
- Their situation — dependents/health needs, how long they realistically expect to stay.
Framework: Severity Scale
- 🔴 Can cost you real money — vesting cliffs vs. their expected tenure, clawbacks (signing bonus, relocation, tuition, even vested equity on "cause" triggers), bonuses payable only if "employed on payment date," short post-exit equity exercise windows, high deductibles behind a good headline, match forfeiture via vesting.
- 🟡 Unusual — clarify before signing — "discretionary" bonus language (decode it plainly: a target, not a promise), unlimited PTO (decode the economics: no accrued payout at exit), benefits changeable "at company discretion," waiting periods.
- 🟢 Standard — normal enrollment windows, standard vesting shapes, typical plan boilerplate; label them so the reader knows what's fine.
Always show the math:
- Match math — e.g. "50% of the first 6%" = X/year at their salary; note the match's own vesting and what leaving at year N forfeits.
- Equity math — grant ÷ vesting years = annual value at stated valuation, with the cliff scenario ("leave at month 11 = 0"); mark valuation-dependent numbers
[to confirm]. - Insurance actual-coverage read — premium share, deductible, out-of-pocket max: the worst-case year in dollars, not the brochure line.
- PTO economics — unlimited vs. accrued: the exit-payout difference in dollars.
Output Format
Benefits Decode: [company / offer]
1. The verdict — what this package is really worth per year (range, assumptions stated), and the two things to resolve before signing.
2. Benefit-by-benefit decode
| Benefit | What the document says | What it's really worth / really means | Severity |
|---|
3. 🚩 Red flags, ranked — quoted language, the scenario where it bites, its dollar cost.
4. The math section — match, equity, insurance worst-case, PTO — arithmetic shown.
5. Questions for HR before signing — 4–7, ordered by money at stake; mark which answers to get in writing (bonus terms, equity plan document, clawback triggers).
6. What's negotiable — typically the one-time items (signing bonus, equity, start date, relocation) more than the plans themselves.
End the artifact with, verbatim: "This is a plain-language reading, not legal/financial advice — laws vary by jurisdiction; confirm anything load-bearing with a qualified professional."
Quality Checks
- Every valuation is shown as arithmetic with stated assumptions, not asserted
- "Discretionary" and "employed on payment date" language is quoted and decoded bluntly
- Cliff/clawback flags are tied to the user's stated expected tenure
- Missing documents and unverifiable numbers are listed as
[to confirm] - Genuinely standard terms are marked 🟢 — not everything is a trap
- The disclaimer line appears verbatim in the artifact
Anti-Patterns
- Do not invent benefits or terms that aren't in the documents
- Do not soften a red flag to seem balanced — "discretionary" means no bonus is owed; say it
- Do not present jurisdiction-dependent rules (PTO payout, clawbacks) as universal
- Do not take equity at face value without flagging the valuation assumption
- Do not let the "total comp" headline stand — rebuild it from the plan language
Based On
Offer-review practice — total-comp reconstruction, plan-language decoding, pre-signing question lists.