itr-prep-skill — Claude Code skill for Indian Income Tax Returns (ITR-1/2/3/4)
A Claude Code skill that takes a user from raw documents (Form 16, AIS, Form 26AS, broker Tax P&L,
payslips) to a fully reconciled, schedule-by-schedule computation and a portal-ready data-pack JSON
— designed to be handed to another agent (or a human) that fills the e-filing portal.
Scope
- Form selection (ITR-1/2/3/4), old-vs-new regime comparison by actual computation
- Multi-employer salary (regime rebuild, single standard deduction, 10(10AA) etc.)
- Capital gains (equity/debt/property/gold/crypto-VDA), F&O & business income, audit applicability
- Loss set-off + carry-forward (CYLA/BFLA/CFL, prior-year ITR parsing, Schedule UD)
- Foreign assets/income (Schedule FA/FSI/TR, Form 67)
- Interest 234A/B/C, AIS/26AS reconciliation, verification of a drafted portal JSON
- Output boundary: the annotated data-pack JSON. Portal data entry is intentionally out of scope.
Rates/limits in the reference files are treated as shape, not truth — the skill mandates verifying
every rate against official sources (incometaxindia.gov.in / incometax.gov.in) per assessment year and
recording them in a rules_verification block in the output.
Quickstart — for non-technical users (clean machine, end to end)
No coding needed. You'll copy-paste a few commands into the terminal and then just talk to Claude.
1. Install Claude Code (needs a Claude subscription — sign in when it asks):
2. Make a folder for your tax documents (e.g. ITR on your Desktop) and drop everything in:
Form 16 from every employer this year, AIS (JSON preferred) + Form 26AS from incometax.gov.in,
broker Tax P&L (Zerodha Console → Reports → Tax P&L), last year's ITR if you have it.
Don't worry about completeness — Claude tells you what's missing.
3. Start Claude in that folder. In the same terminal:
cd ~/Desktop/ITR
claude --dangerously-skip-permissions
(The flag skips per-action approval prompts for a smoother run. It disables all permission prompts
session-wide — this skill only reads your documents, verifies rates online, and writes the data pack
locally — but skip the flag if you prefer approving each step; everything still works.)
4. Install this skill by just asking. Type into Claude:
Install the skill from https://github.com/NidheeshJain/itr-prep-skill into my Claude skills folder, then prepare my income tax return from the documents in this folder.
Claude fetches the skill, reads your documents, asks you simple questions (job changes? sold shares?),
verifies current tax rules online, and produces ITR_datapack_<PAN>_AY<year>.json — every number
traced to your documents, with anything unresolved flagged for you.
5. Pay and file. Claude will tell you if tax is still payable (pay it on the portal when told,
before filing). Then either fill the portal yourself using the data pack as your cheat-sheet, or hand
it to a browser agent ("Handing off" below). You always do the payment, the final Submit, and e-verify.
Handing off to the filling agent
The data pack is designed to be consumed by a second agent with browser access — e.g. Claude in
Chrome (install the Claude Chrome extension) or a cowork session. Attach the data-pack JSON (and
optionally the raw documents for spot-checks). A prep run ends by showing you this prompt pre-filled
for your case — just copy-paste it; the generic version:
I need you to fill my Indian Income Tax Return on https://eportal.incometax.gov.in using the attached
data pack: ITR_datapack_<PAN>_AY<year>.json. It was prepared by another agent after full reconciliation
of my Form 16s, AIS, 26AS and broker statements — treat its figures as authoritative and fill each
schedule with these EXACT numbers. The JSON's comments explain where each figure goes.
Rules:
1. I will log in myself — never ask for or handle my password or OTP.
2. Work schedule by schedule in the portal's Return Summary; after editing any schedule, re-confirm
downstream schedules (the portal silently un-confirms them).
3. The portal pre-fills from AIS — where pre-fill disagrees with the data pack, the data pack wins;
tell me about any disagreement instead of silently accepting either.
4. Resolve every item in `verification_checklist_before_submit` and every TODO/VERIFY flag with me
before proceeding.
5. When validation shows 0 errors, STOP. Show me the final computed tax vs the pack's
`tax_computation` and `balance_and_interest` figures. I will make the payment, click Submit,
and e-verify myself.
6. For Schedule 112A, don't type rows manually: use the portal's "Download CSV Template" and fill it
from the pack's `csv_ready_112A` block (follow `csv_generation_notes`). If any field is missing or
you need to reconcile a figure at runtime, use the attached broker tax report.
7. Once everything is filled and the portal validates with 0 errors, download the portal's JSON so I
can take it back to my prep agent for a final line-by-line reconciliation and sign-off before I
pay and submit.
The prep agent stays with you to the end: bring the portal JSON back to it for the final
reconciliation, and if validation errors come up, either let the filling agent fix them or send the
prep agent a screenshot — it will fix the pack or tell the filling agent exactly what to do.
If anything in the pack looks wrong mid-fill, the filling agent should stop and flag it — the pack
carries source attribution for every figure so discrepancies can be traced.
Layout
SKILL.md — 8-phase workflow orchestratorreferences/01–10 — per-domain depth, loaded lazily by profilescripts/decrypt_ais.py — decrypts the portal's encrypted AIS JSON (PAN + DOB)
Manual install: git clone https://github.com/NidheeshJain/itr-prep-skill.git ~/.claude/skills/itr-prep-skill
(Python deps self-install on first run.)
Disclaimer
This is a careful preparer, not a chartered accountant. Users remain legally responsible for filed
figures. Audit cases, HUF/deceased filings, and contested notices are explicitly escalated to a CA.
Contributing
Field reports from real filings are the most valuable contribution — see CONTRIBUTING.md.
Licensed under MIT.
