tax-filing
United States federal income tax filing assistant for US citizens, resident aliens, and nonresident aliens. Guides users through the entire IRS filing workflow: determining filer type and filing status, identifying which forms and schedules are needed, calculating amounts from source documents (W-2, 1099s, etc.), and filling IRS PDF forms using pypdf. This skill covers US federal taxes only — not state, local, or non-US tax systems. Use this skill whenever the user mentions taxes, tax returns, 1040, 1040-NR, filing status, "which forms do I need", "help me file my taxes", "tax prep", deductions, NRA tax filing, nonresident alien taxes, treaty-based returns, "check my tax forms", "review my 1040-NR", or any request related to preparing a US federal tax return — even if they don't specify their filer type. This skill handles the routing and covers both citizen/RA (Form 1040) and NRA (Form 1040-NR) workflows end to end, including PDF form filling and validation.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/irreel/tax-filingTax Filing
A guided workflow for preparing US federal income tax returns. This skill covers all filer types — US citizens, resident aliens (RA), and nonresident aliens (NRA) — by first determining the correct filer type, then routing to the appropriate forms and procedures. Both citizen/RA and NRA workflows are fully self-contained in this skill, including PDF form field mappings, cross-form validation, and the safe update_form.py script.
Step 1: Gather Source Documents
Before anything else, ask the user what documents they have. Common source docs:
| Document | What it tells you |
|---|---|
| W-2 | Wages, federal/state tax withheld, employer HSA contributions |
| 1099-NEC | Contractor / self-employment income |
| 1099-INT | Bank interest |
| 1099-DIV | Dividends (qualified and ordinary) |
| 1099-B | Stock/crypto sales (proceeds and cost basis) |
| 1099-MISC | Other income (royalties, rents, etc.) |
| 1099-SA / 5498-SA | HSA distributions and contributions |
| 1098 | Mortgage interest paid |
| 1098-T | Tuition paid (education credits) |
| I-94 | Travel history (needed for NRA determination) |
If the user has an I-94 or mentions a visa type, that's a strong signal they may be NRA — proceed to Step 2 with that in mind.
Step 2: Determine Filer Type
This is the critical routing decision. Read references/filing-status.md for the full decision tree. The short version:
- US citizen or green card holder → Resident. File Form 1040. Go to Step 3a.
- Visa holder (F-1, J-1, H-1B, OPT, etc.) → Apply the Substantial Presence Test (SPT):
- Count days present: current year days + (1/3 × prior year days) + (1/6 × two years ago days)
- If total ≥ 183 → Resident alien (unless an exemption applies). File Form 1040. Go to Step 3a.
- F-1 and J-1 students are exempt from SPT for their first 5 calendar years. They remain NRA. File Form 1040-NR. Go to Step 3b.
- If total < 183 → Nonresident alien. File Form 1040-NR. Go to Step 3b.
- Dual-status (changed status mid-year) → complex case. Note it for the user and suggest professional review for the transition period.
Ask the user directly if unclear. Don't assume.
Step 3a: Citizen / Resident Alien Workflow (Form 1040)
Read references/form-routing.md to determine which schedules and forms are needed based on the user's income types. For field-level details on individual schedule lines and common pitfalls, read references/common-schedules.md when filling specific forms.
Workflow
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-irreel-tax-filing": {
"enabled": true,
"auto_update": true
}
}
}