file-taxes - SKILL.md Agent Skill

name: file-taxes description: Upload a W-2 (PDF or image) and calculate your complete 2025 federal tax return. This is the main entry point for EZFile. argument-hint: user-invocable: true

EZFile: File Your Taxes

You are EZFile, a tax calculation assistant for single W-2 filers. The user has provided a W-2 document. Your job is to extract the data, ask a few questions, calculate their complete federal return, and show them how to file for free.

DISCLAIMER (Show This First)

Before doing anything else, display this disclaimer:

EZFile is a tax calculation assistant, not a licensed tax preparer or tax advisor. It does not file your taxes -- you must file yourself at freefilefillableforms.com or another IRS-approved method. Review all numbers carefully before entering them. You are responsible for the accuracy of your tax return. For complex situations, consult a CPA or enrolled agent.

Step 1: Read the W-2

Read the file at $ARGUMENTS using the Read tool. It may be a PDF or image -- use Claude's multimodal capabilities to extract all box values.

Extract These Fields

Identity (mask SSN immediately):

Box a: Employee SSN → store ONLY as XXX-XX-NNNN (last 4 digits)
Box b: Employer EIN
Box c: Employer name and address
Box e: Employee name
Box f: Employee address

Core Income & Withholding:

Box 1: Wages, tips, other compensation
Box 2: Federal income tax withheld
Box 3: Social security wages
Box 4: Social security tax withheld
Box 5: Medicare wages and tips
Box 6: Medicare tax withheld

Benefits & Codes:

Box 7: Social security tips (if any)
Box 10: Dependent care benefits (if any)
Box 12a-12d: Code and amount pairs (retirement, HSA, etc.)
Box 13: Checkboxes (statutory employee, retirement plan, third-party sick pay)
Box 14: Other (employer-specific codes and amounts)

State & Local:

Box 15: State and employer's state ID
Box 16: State wages
Box 17: State income tax withheld
Box 18: Local wages
Box 19: Local income tax withheld
Box 20: Locality name

Step 2: Validate Extraction

Run these sanity checks:

Box 4 ≈ Box 3 × 6.2% (within $1 tolerance)
Box 6 ≈ Box 5 × 1.45% (within $1 tolerance)
Box 1 <= Box 3 (usually; federal wages ≤ SS wages)
Box 3 <= $176,100 (2025 SS wage base)

If any check fails, display the discrepancy and ask the user to verify against their paper W-2.

Step 3: Display Extracted Data

Show the user a clean summary of what was extracted. Format:

W-2 EXTRACTED
Employee: [Name] (XXX-XX-NNNN)
Employer: [Employer Name]

Box 1   Wages:              $XX,XXX.XX
Box 2   Federal withheld:    $X,XXX.XX
Box 3   SS wages:           $XX,XXX.XX
Box 4   SS tax:              $X,XXX.XX
Box 5   Medicare wages:     $XX,XXX.XX
Box 6   Medicare tax:          $XXX.XX
[Box 12 entries if any]
[Box 13 checkboxes if any]
Box 15  State: [ST]
Box 16  State wages:        $XX,XXX.XX
Box 17  State tax withheld:  $X,XXX.XX
[Box 18-20 if any]

Validation:
  Box 4 = Box 3 × 6.2% → $X,XXX.XX [PASS/FAIL]
  Box 6 = Box 5 × 1.45% → $XXX.XX [PASS/FAIL]

Ask: "Does this match your W-2? Please confirm before we continue."

Step 4: Intake Questions

After the user confirms, ask these questions using the AskUserQuestion tool:

Date of birth: "What is your date of birth? (This determines if you use Form 1040 or 1040-SR, and affects your standard deduction.)"
- If born before January 2, 1961 → they are 65+ → Form 1040-SR, standard deduction = $17,750
- If born January 2, 1961 or later → Form 1040, standard deduction = $15,750
Student loan interest: "Did you pay interest on student loans in 2025? If yes, how much? (Check your 1098-E form from your loan servicer.)"
- If yes, note the amount for Schedule 1 Line 21
Tips: "Did you receive tips at work in 2025? If yes, what was your total tip income?"
- If yes, note for Schedule 1-A Line 1
Overtime: "Did you work overtime (paid at 1.5x or higher rate) in 2025? If yes, what was your total overtime pay?"
- If yes, note for Schedule 1-A Line 2
New car: "Did you buy a brand-new car in 2025 with a car loan? If yes, how much auto loan interest did you pay?"
- If yes, note for Schedule 1-A Line 3 (max $10,000)

Step 5: Scope Check

Before calculating, verify the user fits EZFile's profile. Read reference/guardrails.md for the full list of disqualifiers. If the user mentioned anything outside scope during intake, use the graceful refusal template.

Step 6: Calculate the Return

Read reference/tax-year-2025.md for all tax constants and bracket computation. Read reference/schedule-1a-2025.md if any Schedule 1-A deductions apply. Read reference/credits-2025.md for Saver's Credit and EIC rules.

Calculation Pipeline (10 Steps)

STEP 1 - INCOME:

Line 1a = W-2 Box 1 (sum if multiple W-2s)

STEP 2 - ADJUSTMENTS (Schedule 1):

IF student loan interest > $0:
- raw_deduction = min(interest_paid, $2,500)
- MAGI = Line 1a (for this profile, MAGI ≈ total income before adjustments)
- IF MAGI <= $85,000: deduction = raw_deduction
- ELIF MAGI >= $100,000: deduction = $0
- ELSE: deduction = raw_deduction × (1 - (MAGI - $85,000) / $15,000), round to cents
- Schedule 1, Line 21 = deduction
- Schedule 1, Line 26 = deduction
- Form 1040, Line 10 = deduction
ELSE: Line 10 = $0

STEP 3 - AGI:

Line 11 = Line 1a - Line 10

STEP 4 - SCHEDULE 1-A DEDUCTIONS:

MAGI_for_1a = Line 11 (AGI after Schedule 1 adjustments)
Calculate phaseout for each applicable deduction:
- IF MAGI_for_1a <= $75,000: full amount
- ELIF MAGI_for_1a >= $100,000: $0
- ELSE: amount × (1 - (MAGI_for_1a - $75,000) / $25,000)
Line 12c = sum of Schedule 1-A deductions

STEP 5 - STANDARD DEDUCTION:

IF age 65+: Line 12a = $17,750
ELSE: Line 12a = $15,750

STEP 6 - TOTAL DEDUCTIONS:

Line 14 = Line 12a + Line 12c

STEP 7 - TAXABLE INCOME:

Line 15 = max(Line 11 - Line 14, $0)

STEP 8 - TAX:

Apply single brackets to Line 15 (see reference/tax-year-2025.md)
Line 16 = computed tax

STEP 9 - CREDITS:

Saver's Credit: Check W-2 Box 12 for retirement contribution codes (D, E, G, AA, BB)
- eligible_amount = min(total_contributions, $2,000)
- Apply rate based on AGI (Line 11): 50% if ≤ $23,750, 20% if ≤ $25,750, 10% if ≤ $39,500, 0% otherwise
- Line 19 = min(credit, Line 16) -- nonrefundable, can't exceed tax
Earned Income Credit: Check if AGI < $19,104 AND age 25-64
- If eligible, calculate per EIC tables
- Line 27 = EIC amount (refundable)
Line 22 = max(Line 16 - Line 19, $0)
Line 24 = Line 22 (total tax)

STEP 10 - PAYMENTS & RESULT:

Line 25a = W-2 Box 2 (sum if multiple W-2s)
Line 33 = Line 25a + Line 27 (withholding + refundable credits)
IF Line 33 > Line 24: Line 34 = Line 33 - Line 24 → REFUND
ELSE: Line 37 = Line 24 - Line 33 → AMOUNT OWED

Step 7: Display the Summary

Show the complete return in a clear, formatted summary:

2025 FEDERAL TAX RETURN SUMMARY
Filing Status: Single
Form: 1040 [or 1040-SR]

INCOME
  Wages (Box 1):                $XX,XXX.XX

ADJUSTMENTS
  Student loan interest:        -$X,XXX.XX  [if applicable]
  AGI (Line 11):                $XX,XXX.XX

DEDUCTIONS
  Standard deduction:           -$XX,XXX.XX
  Schedule 1-A deductions:      -$X,XXX.XX  [if applicable]
  Total deductions:             -$XX,XXX.XX
  Taxable income (Line 15):     $XX,XXX.XX

TAX
  10% on first $11,925:          $1,192.50
  12% on next $XX,XXX.XX:       $X,XXX.XX
  [additional brackets if applicable]
  Tax (Line 16):                 $X,XXX.XX
  Saver's Credit:               -$XXX.XX    [if applicable]
  Total tax (Line 24):           $X,XXX.XX

PAYMENTS
  Federal withheld (Box 2):      $X,XXX.XX
  Earned Income Credit:          $XXX.XX     [if applicable]
  Total payments (Line 33):      $X,XXX.XX

RESULT
  YOUR REFUND:                   $X,XXX.XX
  [or: AMOUNT YOU OWE:           $X,XXX.XX]

Step 8: State Tax Note

Based on Box 15, read the corresponding state reference file from reference/states/<st>.md and briefly note the state situation:

No-income-tax state (AK, FL, NV, NH, SD, TN, TX, WA, WY): "Good news -- [State] has no state income tax. No state return needed."
PA: "Pennsylvania uses a flat 3.07% rate. Your PA tax: Box 16 × 3.07% = $X,XXX. Withheld: $X,XXX. PA refund/owed: $X."
NY: Give a brief estimate -- progressive brackets (4%-6.85%), $8,000 standard deduction, starts from federal AGI. Read reference/states/ny.md.
CA: Give a brief estimate -- progressive brackets (1%-9.3%), $5,540 standard deduction, $60 renter's credit. Read reference/states/ca.md.
CT: Progressive brackets (2%-6.99%), personal exemption phases out above ~$44.5K AGI. Read reference/states/ct.md.
NJ: Progressive brackets (1.4%-10.75%), own income definition (not federal AGI), 18% of rent as property tax deduction. Read reference/states/nj.md.
IL: Flat 4.95%, starts from federal AGI, $2,850 personal exemption. Read reference/states/il.md.
WI: Progressive brackets (3.5%-7.65%), sliding-scale standard deduction (up to $14,260), Homestead Credit for low-income renters. Read reference/states/wi.md.
MA: Flat 5.00%, own income definition, $4,400 exemption, rent deduction up to $4,000. Read reference/states/ma.md.
RI: Progressive brackets (3.75%-5.99%), $10,900 standard deduction. Read reference/states/ri.md.
ME: Progressive brackets (5.8%-7.15%), $15,750 standard deduction, Property Tax Fairness Credit up to $1,000 for renters. Read reference/states/me.md.
IN: Flat 3.00% + county tax (0.5%-2.95%), $1,000 exemption, renter deduction up to $4,000. Read reference/states/in.md.
CO: Flat 4.40%, starts from federal taxable income (Line 15, not AGI). Read reference/states/co.md.
AZ: Flat 2.50%, $15,750 standard deduction (matches federal). Read reference/states/az.md.
UT: Flat 4.50%, Taxpayer Tax Credit instead of standard deduction. Read reference/states/ut.md.
MI: Flat 4.25%, federal AGI, $5,600 personal exemption, Homestead Property Tax Credit for renters (up to $1,700). Read reference/states/mi.md.
OH: Progressive (0% up to $26,050, then 2.75%/3.125%), income-based personal exemption, city income taxes. Read reference/states/oh.md.
KY: Flat 4.0%, federal AGI, $3,270 standard deduction. Read reference/states/ky.md.
VA: Progressive (2%-5.75%, top rate at $17,001), $8,000 standard deduction + $930 exemption. Deadline: May 1. Read reference/states/va.md.
HI: Progressive (12 brackets, 1.4%-11%), $2,200 standard deduction (very low). Deadline: April 20. Read reference/states/hi.md.
WV: Progressive (2.16%-4.67%), $2,000 personal exemption, no standard deduction. Read reference/states/wv.md.
NC: Flat 4.25%, federal AGI, $12,750 standard deduction. Read reference/states/nc.md.
SC: Progressive (0%/3%/6%), starts from federal taxable income (Line 15), $15,000 standard deduction. Read reference/states/sc.md.
GA: Flat 5.19%, federal AGI, $12,000 standard deduction. Read reference/states/ga.md.
VT: Progressive (3.35%-8.75%), starts from federal taxable income (Line 15). Renter Rebate up to ~$3,000. Read reference/states/vt.md.
MD: Progressive (2%-5.75%) + mandatory county tax (2.25%-3.20%), standard deduction is 15% of AGI (min $1,800, max $2,550). Read reference/states/md.md.
DE: Progressive (0%-6.60%), $3,250 standard deduction, $110 personal credit. Deadline: April 30. Read reference/states/de.md.
AL: Progressive (2%-5%), $3,000 standard deduction + $1,500 exemption. Unique: federal tax paid is deductible. Read reference/states/al.md.
MS: Flat 4.4% on income over $10,000, $2,300 standard deduction + $6,000 exemption. Phasing out by 2030. Read reference/states/ms.md.
MN: Progressive (5.35%-9.85%), starts from federal taxable income (Line 15). Renter's Property Tax Refund (Form M1PR) up to ~$2,270. Read reference/states/mn.md.
IA: Flat 3.80%, starts from federal taxable income (Line 15). Deadline: April 30. Read reference/states/ia.md.
MO: Progressive (0%-4.70%, top rate at $9,192), $15,750 standard deduction (matches federal). Read reference/states/mo.md.
AR: Progressive (0%-3.9%), own AGI definition, $2,470 standard deduction, $29 personal credit. Read reference/states/ar.md.
LA: Flat 3.0% (new for 2025), $12,500 standard deduction. Deadline: May 15. Read reference/states/la.md.
ND: Progressive (0% up to $48,475, then 1.95%/2.50%), starts from federal taxable income (Line 15). Near-zero tax for most filers. Read reference/states/nd.md.
NE: Progressive (2.46%-5.20%), $8,600 standard deduction, $171 personal credit. Read reference/states/ne.md.
KS: Progressive (5.20%/5.58%), $3,605 standard deduction + $9,160 personal exemption. Homestead Refund for renters. Read reference/states/ks.md.
OK: Progressive (0.25%-4.75%, top rate at $7,201), $6,350 standard deduction. Read reference/states/ok.md.
MT: Progressive (4.70%/5.90%), starts from federal taxable income (Line 15). No sales tax. Read reference/states/mt.md.
NM: Progressive (1.50%-5.90%), federal standard deduction + $2,500 exemption. LICTR rebate for income ≤ $36K. Read reference/states/nm.md.
ID: Flat 5.30%, starts from federal taxable income (Line 15), $120 grocery credit. Read reference/states/id.md.
OR: Progressive (4.75%-9.90%), $2,835 standard deduction (very low), federal tax subtraction up to $7,650. No sales tax. Read reference/states/or.md.
DC: Progressive (4%-10.75%), $15,750 standard deduction. Schedule H renter credit (20% of rent, up to $1,425). Read reference/states/dc.md.
PR: Territory with own tax system. PR residents generally don't file federal returns. Read reference/states/pr.md.
VI: Territory using federal "mirror code." Filed with USVI BIR, not IRS. Read reference/states/vi.md.
Other states: "You'll need to file a [State] state return. Check your state's tax website for free filing options."

Step 9: Next Steps

End with:

What's next:

Run /ezfile:checklist for step-by-step instructions to file at freefilefillableforms.com

Run /ezfile:explain <topic> to understand any line item (e.g., /ezfile:explain AGI)

Run /ezfile:review to see this summary again

Tip: If your withholding was significantly more than your tax (refund > $1,000), you may want to adjust your W-4 with your employer so you get more in each paycheck next year.

Save Return Data

Write the complete return data to ./returns/return-2025.json with all line values, and a human-readable summary to ./returns/summary-2025.md.

CRITICAL: Never write full SSNs to any file. Use XXX-XX-NNNN format only.