Skip to content
Back to search

file-itr

An agent skill that helps any Indian individual taxpayer prepare and e-file an Income Tax Return (ITR-1/2/3/4) on the official portal — under either the old or the new tax regime. It reconciles…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shivprime94--file-itr/badge.svg)](/listings/shivprime94--file-itr)

HTML

<a href="/listings/shivprime94--file-itr"><img src="/api/listings/shivprime94--file-itr/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Cowork (desktop)

1. Download `itr-india.skill` from this repo. 2. In Cowork, open the chat and use the **"Save skill"** button that appears when a `.skill` file is shared, **or** go to **Settings → Capabilities → Skills** and add it. (You can also drag the `.skill` file into the chat and click *Save skill*.) 3. The skill now appears in your skills list and triggers automatically when you talk about filing Indian taxes.

Claude Code (CLI)

Skills live under a `skills/` directory that Claude Code reads. Either:

**A) Clone into your project's skills folder**

git clone https://github.com/shivprime94/file-itr.git
mkdir -p .claude/skills
cp -r file-itr/skills/itr-india .claude/skills/

**B) Install for all projects (user-level)**

git clone https://github.com/shivprime94/file-itr.git
mkdir -p ~/.claude/skills
cp -r file-itr/skills/itr-india ~/.claude/skills/

Restart Claude Code (or start a new session) and confirm with `/skills` (or however your version lists skills). The skill triggers on ITR/tax-filing requests.

Note: unlike the `.skill` bundle, `cp -r` also copies `engine/`, `evals/`, and `conftest.py` — the skill doesn't load any of these, so it's harmless to have them, but you don't need them for the skill to work.

Any other Claude Agent SDK / custom agent

Place the `skills/itr-india/` folder wherever your agent loads skills from (the directory containing per-skill folders, each with a `SKILL.md`). The agent reads the YAML frontmatter `description` to decide when to trigger, and loads `SKILL.md` + the `references/` files as needed.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 208 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # file-itr
  2. An agent **skill** that helps **any** Indian individual taxpayer prepare and
  3. e-file an Income Tax Return (ITR-1/2/3/4) — under **either the old or the new
  4. tax regime**.
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [![Skill Bundle](https://github.com/shivprime94/file-itr/actions/workflows/skill-bundle.yml/badge.svg)](https://github.com/shivprime94/file-itr/actions/workflows/skill-bundle.yml)
  7. [![Engine Tests](https://github.com/shivprime94/file-itr/actions/workflows/engine-tests.yml/badge.svg)](https://github.com/shivprime94/file-itr/actions/workflows/engine-tests.yml)
  8. [![GitHub stars](https://img.shields.io/github/stars/shivprime94/file-itr?style=social)](https://github.com/shivprime94/file-itr/stargazers)
  9. [Install](#install) · [Use](#use) · [What it covers](#what-it-covers) · [Scope](#scope-and-limitations) · [Repo structure](#repository-structure) · [Contributing](#contributing)
  10. ## What people say
  11. <table>
  12. <tr>
  13. <td width="50%"><img src="docs/testimonials/panman.png" alt='PanMan: "It worked pretty well. Filed for myself and wife."'></td>
  14. <td width="50%"><img src="docs/testimonials/akshith-bellare.png" alt="Akshith Bellare: used it alongside a CA and spotted a mismatch the CA had missed"></td>
  15. </tr>
  16. <tr>
  17. <td width="50%"><img src="docs/testimonials/sidharth-rajmohan.png" alt='Sidharth Rajmohan: "It was pretty helpful, filed my tax with that"'></td>
  18. <td width="50%"><img src="docs/testimonials/chandan-kumar-linkedin.png" alt="Chandan Kumar on LinkedIn: added file-itr as a Claude skill and let Claude file the return via the browser"></td>
  19. </tr>
  20. </table>
  21. <sub>Replies from [this X thread](https://x.com/neembu_paani31/status/2082884544185987480) and a LinkedIn post by Chandan Kumar, who filed a complicated return (large tax-free gratuity, dividends from demerged unlisted shares) with the skill.</sub>
  22. ## About
  23. It reconciles salary + freelance/creator/business income + capital gains +
  24. interest into a correct, fully-verified return, **compares both regimes and
  25. proactively asks for the deduction proofs that lower tax legally**, fills the
  26. portal schedule-by-schedule, fixes validation defects, and guides the user
  27. through payment and e-verification.
  28. Its aim is the **lowest legal tax** — claim every deduction the user genuinely
  29. has and pick the cheaper regime — never to fabricate or inflate anything.
  30. The skill lives in [`skills/itr-india/`](skills/itr-india/), distilled from a
  31. real end-to-end ITR-3 filing (salaried + content-creator under 44ADA +
  32. listed-share STCG + bank interest) and generalised to cover both regimes and
  33. all common filer types.
  34. > ⚠️ **Not professional tax advice.** This skill makes a return *accurate and
  35. > defensible*, not minimised at any cost. Indian tax rules change every
  36. > assessment year — always re-confirm current-year slabs, limits, and forms. The
  37. > taxpayer remains responsible for the figures filed. The agent will never enter
  38. > your password/OTP, make the payment, or submit/e-verify on your behalf — those
  39. > are your actions by design.
  40. ## Install
  41. ### Claude Cowork (desktop)
  42. 1. Download `itr-india.skill` from this repo.
  43. 2. In Cowork, open the chat and use the **"Save skill"** button that appears when
  44. a `.skill` file is shared, **or** go to **Settings → Capabilities → Skills**
  45. and add it. (You can also drag the `.skill` file into the chat and click
  46. *Save skill*.)
  47. 3. The skill now appears in your skills list and triggers automatically when you
  48. talk about filing Indian taxes.
  49. ### Claude Code (CLI)
  50. Skills live under a `skills/` directory that Claude Code reads. Either:
  51. **A) Clone into your project's skills folder**
  52. ```bash
  53. git clone https://github.com/shivprime94/file-itr.git
  54. mkdir -p .claude/skills
  55. cp -r file-itr/skills/itr-india .claude/skills/
  56. ```
  57. **B) Install for all projects (user-level)**
  58. ```bash
  59. git clone https://github.com/shivprime94/file-itr.git
  60. mkdir -p ~/.claude/skills
  61. cp -r file-itr/skills/itr-india ~/.claude/skills/
  62. ```
  63. Restart Claude Code (or start a new session) and confirm with `/skills` (or
  64. however your version lists skills). The skill triggers on ITR/tax-filing
  65. requests.
  66. Note: unlike the `.skill` bundle, `cp -r` also copies `engine/`, `evals/`, and
  67. `conftest.py` — the skill doesn't load any of these, so it's harmless to have
  68. them, but you don't need them for the skill to work.
  69. ### Any other Claude Agent SDK / custom agent
  70. Place the `skills/itr-india/` folder wherever your agent loads skills from (the
  71. directory containing per-skill folders, each with a `SKILL.md`). The agent reads
  72. the YAML frontmatter `description` to decide when to trigger, and loads
  73. `SKILL.md` + the `references/` files as needed.
  74. ## Use
  75. Once installed, just talk to your agent naturally, e.g.:
  76. - "Help me file my ITR for FY 2025-26 — I'm salaried and also do freelance
  77. content work, and I sold some shares this year."
  78. - "I'm a YouTuber, new tax regime, can you do my income tax return in India?"
  79. - "Reconcile my 26AS and AIS and tell me my total income and tax."
  80. - "I'm stuck on a validation error on the income tax portal for my 44ADA return."
  81. - "I traded crypto on an Indian exchange — made profit on some coins, lost on
  82. others, 1% TDS was deducted. How is it taxed and which ITR form?"
  83. - "My father is 67, gets pension + FD interest, paid health insurance — old or new
  84. regime, and how much tax?"
  85. - "I have 80C, a home loan and HRA — is the old or new regime cheaper for me?"
  86. The agent will gather your documents, reconcile income, compute tax, walk the
  87. portal with you, and stop at the payment/submit/e-verify steps for you to
  88. complete.
  89. ### What you'll need to provide
  90. Form 16(s), Form 26AS, AIS/TIS, bank statements for the financial year, any
  91. broker/capital-gains statement, and any platform payout files (Stripe/YouTube/
  92. X/etc.). For the portal steps, you log in yourself and the agent drives the form.
  93. ## What it covers
  94. - Picking the right form (ITR-1/2/3/4) and **comparing old vs new regime**
  95. (115BAC / Form 10-IEA) on the user's real numbers to choose the cheaper one.
  96. - **Old-regime deduction catalogue** (80C, 80D, 80CCD/NPS, HRA, home-loan
  97. interest, 80G, 80E, 80TTA/TTB, …) and a **proactive checklist of documents to
  98. ask for** so no legitimate deduction is missed.
  99. - Reconciling income to source documents (Form 16, 26AS, AIS, bank statements,
  100. platform payout files) — one number per head, each tied to a document.
  101. - Presumptive taxation for creators/freelancers/small business (44AD/44ADA,
  102. CBDT code 16021).
  103. - Capital gains on listed equity/MF/property (111A/112A special rates,
  104. quarterly breakup for 234C), virtual digital assets/crypto (115BBH), and
  105. interest/dividends in Schedule OS.
  106. - Independent tax computation (both regimes) to verify the portal's math —
  107. backed by a separately tested rule engine (see
  108. [Repository structure](#repository-structure) below).
  109. - Driving the e-filing portal, with workarounds for its known quirks
  110. (logout pop-ups, mat-select dropdowns, the trailing-zero bug, silent
  111. schedule un-confirmation, and the no-account balance-sheet validation defect).
  112. - Handing off payment, submission, and e-verification cleanly.
  113. ## Scope and limitations
  114. - **The verified engine** (`skills/itr-india/engine/`) is scoped to AY 2026-27,
  115. resident individuals, both regimes, and structurally refuses — fail-loud, not
  116. a guess — non-residents, business/house-property/foreign income, Chapter
  117. VI-A deductions beyond what's modeled, AMT, clubbing provisions, and Section
  118. 89 relief. See [`engine/README.md`](skills/itr-india/engine/README.md) for
  119. the exact boundary.
  120. - **The skill's reference material** (`skills/itr-india/references/`) covers
  121. domestic salary/freelance/business income, capital gains, deductions, and
  122. VDA/crypto in depth. It recognises RNOR/non-resident status and foreign
  123. assets/income as real scenarios — they're documented ITR-4 disqualifiers
  124. that route to ITR-2/3 — but there's no dedicated Schedule FA/FSI/TR
  125. reference yet, so that coverage is thinner than the domestic-filer material
  126. and should be verified independently or with a CA.
  127. - **India personal income tax only** — not GST, TDS returns (24Q/26Q), or
  128. company/firm returns.
  129. - Complex F&O/intraday trading, tax-audit applicability, and multi-year
  130. brought-forward-loss continuity should be verified with a CA — the skill
  131. helps reconcile and file, it doesn't replace judgment on edge cases.
  132. ## Repository structure
  133. - [`skills/itr-india/`](skills/itr-india/) — the skill itself. Start with
  134. `SKILL.md` (workflow + judgment), then `references/` for regime, deduction,
  135. presumptive-taxation, capital-gains/VDA, and portal-workflow detail. This is
  136. what ships inside `itr-india.skill`.
  137. - [`skills/itr-india/engine/`](skills/itr-india/engine/) — a separate, tested
  138. Python engine (scope check → bucketing → set-off → rates → interest) that
  139. independently recomputes the tax to audit the skill's numbers. It is **not**
  140. part of the installable bundle. See its own
  141. [README](skills/itr-india/engine/README.md), and run its tests with
  142. `pytest skills/itr-india/engine/tests -v`.
  143. - [`itr-india.skill`](itr-india.skill) — the zipped, one-click-install bundle.
  144. CI rebuilds it deterministically whenever `SKILL.md`, `references/`, or
  145. `evals/` change — never hand-edit it.
  146. - [`scripts/`](scripts/) — bundle build tooling.
  147. - [`.github/workflows/`](.github/workflows/) — CI.
  148. ## Star History
  149. <a href="https://www.star-history.com/?repos=shivprime94%2Ffile-itr&type=date&legend=top-left">
  150. <picture>
  151. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=shivprime94/file-itr&type=date&theme=dark&legend=top-left" />
  152. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=shivprime94/file-itr&type=date&legend=top-left" />
  153. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=shivprime94/file-itr&type=date&legend=top-left" />
  154. </picture>
  155. </a>
  156. ## Contributing
  157. Bug reports, corrected reference material, and engine improvements are
  158. welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, running the
  159. test suite, and commit/PR conventions.
  160. ## License
  161. MIT — see [LICENSE](LICENSE).
  162. ## Disclaimer
  163. This project is provided "as is", without warranty of any kind. It is not a
  164. substitute for a chartered accountant or a registered tax practitioner. Verify
  165. every figure before filing. The authors are not liable for any filing made using
  166. this skill.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.