Use this skill with your AI agent
Paste this skill into your AI agent's context, or save the file to your project. Works with any AI agent that reads markdown.
nl-freelance-intake.md644 lines29.4 KB
v10Netherlands
Not yet verified by an accountantContact accountant
| 1 | --- |
| 2 | name: nl-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their Netherlands tax returns AND mentions freelancing, self-employment, ZZP, eenmanszaak, or sole proprietorship. Trigger on phrases like "help me do my taxes", "prepare my IB-aangifte", "I'm a ZZP'er in the Netherlands", "I'm a freelancer in the Netherlands", "do my taxes as a contractor", "prepare my BTW return and income tax", or any similar phrasing where the user is a Netherlands-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Netherlands self-employed tax workflow -- every other skill in the stack (nl-btw-return, nl-income-tax, nl-zvw, nl-return-assembly) depends on this skill running first to produce a structured intake package. Uses upload-first workflow -- the user dumps all their documents and the skill infers as much as possible before asking questions. Uses ask_user_input_v0 for structured questions instead of one-at-a-time prose. Built for speed. Netherlands full-year residents only; self-employed individuals and sole proprietors. |
| 4 | version: 1.0 |
| 5 | jurisdiction: NL |
| 6 | category: orchestrator |
| 7 | --- |
| 8 | |
| 9 | # Netherlands Self-Employed Intake Skill v1.0 |
| 10 | |
| 11 | ## What this file is |
| 12 | |
| 13 | The intake orchestrator for Netherlands-resident self-employed individuals. Every downstream Netherlands content skill (nl-btw-return, nl-income-tax, nl-zvw) and the assembly orchestrator (nl-return-assembly) depend on this skill running first to produce a structured intake package. |
| 14 | |
| 15 | This skill does not compute any tax figures. Its job is to collect all the facts, parse all the documents, confirm everything with the user, and hand off a clean intake package to `nl-return-assembly`. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Design principles |
| 20 | |
| 21 | v1.0 follows the upload-first, inference-then-confirm pattern: |
| 22 | |
| 23 | 1. **Compact refusal sweep** using `ask_user_input_v0` -- 3 interactive questions, ~30 seconds. |
| 24 | 2. **Upload-first workflow** -- after the refusal check, the user dumps everything they have. |
| 25 | 3. **Inference pass** -- Claude parses every document and extracts as much as possible. |
| 26 | 4. **Gap-filling only** -- Claude asks the user ONLY about what is missing, ambiguous, or needs confirmation. |
| 27 | 5. **Single confirmation pass** at the end -- show the full picture, let the user correct anything wrong, hand off to downstream skills. |
| 28 | |
| 29 | Target: intake completes in 5 minutes for a prepared user, 15 minutes for a user who has to go fetch documents. |
| 30 | |
| 31 | ## Critical operating principles |
| 32 | |
| 33 | **Do not narrate the workflow.** Do not say "Phase 1," "Phase 2," "Now I'll ask you about deductions." Just do the work. |
| 34 | |
| 35 | **Do not ask questions that have already been answered.** If the refusal check established the user is a ZZP'er with BTW registration, do not later ask about VAT registration type. Track what is known. |
| 36 | |
| 37 | **Do not ask about things visible in uploaded documents.** If the bank statement shows quarterly BTW payments to Belastingdienst, do not ask "did you pay BTW." Confirm what you see, do not re-ask. |
| 38 | |
| 39 | **Use `ask_user_input_v0` for any multiple-choice question.** Text input is only for genuinely open-ended data (names, addresses, specific amounts when they cannot be inferred). |
| 40 | |
| 41 | **Prefer batching.** Ask 3 related questions in a single message when they do not depend on each other's answers. |
| 42 | |
| 43 | **Be terse but complete.** No hedging, no "let me know if you have questions," no "I hope this helps." |
| 44 | |
| 45 | **Exception for blocking decisions.** If a single question determines whether the user is in-scope or out-of-scope, ask it standalone. |
| 46 | |
| 47 | --- |
| 48 | |
| 49 | ## Section 1 -- The opening |
| 50 | |
| 51 | When triggered, respond with ONE message that: |
| 52 | |
| 53 | 1. One-line greeting (no paragraph of expectation-setting) |
| 54 | 2. One-line summary of the flow (scope check -> upload -> gaps -> handoff to return assembly) |
| 55 | 3. One-line reviewer reminder (must be reviewed by qualified belastingadviseur before filing) |
| 56 | 4. Launch the refusal sweep immediately using `ask_user_input_v0` |
| 57 | |
| 58 | **Example first message:** |
| 59 | |
| 60 | > Let's get your 2025 Netherlands returns ready. Quick scope check, then you upload your documents, then I fill in the gaps. Target time: 10 minutes. |
| 61 | > |
| 62 | > Reminder: everything I produce needs to be reviewed and signed off by a qualified belastingadviseur before you file anything with the Belastingdienst. I'm not a substitute for review. |
| 63 | > |
| 64 | > Scope check: |
| 65 | |
| 66 | Then immediately call `ask_user_input_v0` with the refusal questions. |
| 67 | |
| 68 | **Do NOT:** |
| 69 | - Write a welcome paragraph |
| 70 | - Explain the phases |
| 71 | - Ask "are you ready to start" |
| 72 | - List what documents you will eventually need |
| 73 | - Give a disclaimer beyond the one reviewer line |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | ## Section 2 -- Refusal sweep (compact) |
| 78 | |
| 79 | Present the refusal sweep as a single `ask_user_input_v0` call with 3 questions, all single-select. |
| 80 | |
| 81 | **The 3 questions to ask first:** |
| 82 | |
| 83 | ``` |
| 84 | Q1: "Netherlands residency in 2025?" |
| 85 | Options: ["Full year", "Part year (immigrated/emigrated)", "Did not live in the Netherlands"] |
| 86 | |
| 87 | Q2: "Business structure?" |
| 88 | Options: ["ZZP / eenmanszaak (sole proprietor)", "VOF (vennootschap onder firma)", "BV (besloten vennootschap)", "Not sure"] |
| 89 | |
| 90 | Q3: "Employment status in 2025?" |
| 91 | Options: ["Fully self-employed (no employer)", "Employed + side self-employment", "Employed only (no self-employment income)"] |
| 92 | ``` |
| 93 | |
| 94 | **After the response, evaluate:** |
| 95 | |
| 96 | - **Q1 = Full year** -> continue |
| 97 | - **Q1 = Part year** -> stop. "I'm set up for full-year Netherlands residents only. Part-year residents have M-biljet (migratieaangifte) requirements with different rules around worldwide vs Dutch-source income. You need a belastingadviseur who handles M-biljetten." |
| 98 | - **Q1 = Did not live in the Netherlands** -> stop. "Non-residents file C-biljet (buitenlandse belastingplicht) with different rules. You need a belastingadviseur who handles non-resident returns." |
| 99 | |
| 100 | - **Q2 = ZZP / eenmanszaak** -> continue |
| 101 | - **Q2 = VOF** -> stop. "VOF partnerships file separately with joint and individual obligations (firmantenaangifte). You need a belastingadviseur familiar with VOF returns." |
| 102 | - **Q2 = BV** -> stop. "I don't cover corporate returns. BVs file vennootschapsbelasting (VPB) returns with separate rules for DGA salaries, dividends, and Box 2 income. You need a belastingadviseur." |
| 103 | - **Q2 = Not sure** -> ask one follow-up: "Do you invoice clients in your own name (or a trade name registered at KvK), or do you have a BV registered at KvK? If you invoice in your own name with a KvK eenmanszaak registration, you're ZZP/eenmanszaak. If you have a BV, you're a limited company." |
| 104 | |
| 105 | - **Q3 = Fully self-employed** -> continue |
| 106 | - **Q3 = Employed + side self-employment** -> continue with a flag: urencriterium (1,225 hours) may not be met, affecting zelfstandigenaftrek eligibility. Will evaluate after inference. |
| 107 | - **Q3 = Employed only** -> stop. "You don't have self-employment income. This workflow is for self-employed individuals. Your employer handles your tax through loonheffing deductions. If you have other income (rental, investments, Box 3 assets), you need a belastingadviseur for your aangifte inkomstenbelasting." |
| 108 | |
| 109 | **After Q1-Q3 pass, ask the second batch of scope questions (also batched):** |
| 110 | |
| 111 | ``` |
| 112 | Q4: "BTW (omzetbelasting) status?" |
| 113 | Options: ["Regular BTW registration (quarterly/monthly filing)", "Kleineondernemersregeling (KOR) -- BTW exempt", "Not BTW registered", "Not sure"] |
| 114 | |
| 115 | Q5: "Marital status / fiscal partner?" |
| 116 | Options: ["Single (no fiscal partner)", "Married / registered partner", "Living together with fiscal partner (notarial cohabitation contract or joint ownership)", "Living together without fiscal partner status"] |
| 117 | |
| 118 | Q6: "KvK registration?" |
| 119 | Options: ["Yes, registered at KvK", "No, not registered", "Not sure"] |
| 120 | ``` |
| 121 | |
| 122 | **Evaluate Q4:** |
| 123 | - **Regular BTW** -> continue. Standard quarterly or monthly BTW-aangifte. |
| 124 | - **KOR** -> continue. No BTW-aangifte filing required, no input BTW recovery, turnover must remain under EUR 20,000 per calendar year. |
| 125 | - **Not BTW registered** -> continue with a flag: if turnover exceeds EUR 20,000, KOR exemption is automatically revoked. If no BTW registration at all and not KOR, may need registration. |
| 126 | - **Not sure** -> ask one follow-up: "Do you charge 21% BTW on your invoices? If yes, you have regular BTW registration. If your invoices say 'BTW verlegd' or show no BTW and your annual revenue is under EUR 20,000, you may be on the KOR." |
| 127 | |
| 128 | **Evaluate Q5:** |
| 129 | - **Single** -> continue. No partner allocation. |
| 130 | - **Married / registered partner** -> continue. Fiscal partner allocation applies (income from own dwelling Box 1, Box 3 assets, heffingskortingen can be optimised). |
| 131 | - **Living together with fiscal partner** -> continue. Same as married for tax purposes. |
| 132 | - **Living together without fiscal partner status** -> continue. No partner allocation. |
| 133 | |
| 134 | **Evaluate Q6:** |
| 135 | - **Yes** -> continue. Standard ZZP path. |
| 136 | - **No** -> flag: without KvK registration, the Belastingdienst may classify income as resultaat uit overige werkzaamheden (ROW) rather than winst uit onderneming, disqualifying zelfstandigenaftrek, startersaftrek, and MKB-winstvrijstelling. |
| 137 | - **Not sure** -> "Check kvk.nl/zoeken with your name. If you have a registration with an active eenmanszaak, you're registered." |
| 138 | |
| 139 | **Total time:** ~45 seconds if the user taps through. |
| 140 | |
| 141 | --- |
| 142 | |
| 143 | ## Section 3 -- The dump |
| 144 | |
| 145 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 146 | |
| 147 | **Example:** |
| 148 | |
| 149 | > Scope is good. Now upload everything you have for 2025 -- drop it all in at once: |
| 150 | > |
| 151 | > - Business bank statement(s) for all of 2025 (CSV or PDF) |
| 152 | > - Sales invoices (verkoopfacturen) issued in 2025 |
| 153 | > - Purchase invoices / receipts (inkoopfacturen) for business expenses |
| 154 | > - Prior year aangifte inkomstenbelasting (IB-aangifte) or voorlopige aanslag |
| 155 | > - Prior BTW-aangiften for 2025 (if regular BTW registration) |
| 156 | > - Jaaropgave(n) from any employment income |
| 157 | > - KvK uittreksel (extract) |
| 158 | > - WOZ-beschikking (property valuation, if claiming eigen woning aftrek) |
| 159 | > - Mortgage annual statement (jaaroverzicht hypotheek) if applicable |
| 160 | > - Capital asset purchase receipts (computers, equipment) |
| 161 | > - Health insurance (zorgverzekering) statements |
| 162 | > - Any Belastingdienst correspondence or voorlopige aanslagen |
| 163 | > - Anything else tax-related you have |
| 164 | > |
| 165 | > Don't worry about labeling or organizing -- I'll figure out what each file is. Drag and drop when ready. |
| 166 | |
| 167 | Then wait. Do not ask any other questions while waiting. |
| 168 | |
| 169 | **If the user uploads a partial dump and says "that's what I have":** move to inference. Do not demand more. Request specific missing items during gap-filling. |
| 170 | |
| 171 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 172 | > Check these places: |
| 173 | > - Business bank: download 2025 statements as PDF or CSV |
| 174 | > - MijnBelastingdienst portal: download prior IB-aangifte and voorlopige aanslagen |
| 175 | > - Email: search for "factuur", "BTW", "Belastingdienst", "KvK", "jaaropgave" |
| 176 | > - Your boekhouder from last year, if you had one |
| 177 | > - Dropbox / Google Drive for saved invoices |
| 178 | > - Hypotheekverstrekker portal for jaaroverzicht |
| 179 | > |
| 180 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 181 | |
| 182 | --- |
| 183 | |
| 184 | ## Section 4 -- The inference pass |
| 185 | |
| 186 | When documents arrive, parse each one. For each document, extract: |
| 187 | |
| 188 | **Bank statement:** |
| 189 | - Total deposits (candidate gross receipts) |
| 190 | - Recurring inflows (client payments with names) |
| 191 | - Outflows to Belastingdienst (inkomstenbelasting voorlopige aanslag payments, BTW payments) |
| 192 | - Outflows for ZVW (zorgverzekeringswet bijdrage) |
| 193 | - Outflows to suppliers (business expenses by category) |
| 194 | - Equipment purchases (potential capital items) |
| 195 | - Transfers to personal account (privé-opnames) |
| 196 | - Rent payments (zakelijke huur or home office) |
| 197 | - SaaS / software subscriptions |
| 198 | - Professional memberships (NBA, NOB, etc.) |
| 199 | - Insurance payments (aansprakelijkheidsverzekering, arbeidsongeschiktheidsverzekering) |
| 200 | - Pensioenpremie payments (lijfrente, FOR) |
| 201 | |
| 202 | **Sales invoices (verkoopfacturen):** |
| 203 | - Client names and amounts |
| 204 | - Whether BTW was charged (regular registration indicator) |
| 205 | - BTW rate applied (21% standaard, 9% laag, 0% export/intracommunautair) |
| 206 | - Whether invoices show "BTW verlegd" (reverse charge) |
| 207 | - Total turnover reconciliation against bank deposits |
| 208 | - Any foreign clients (EU with BTW-id or non-EU -- ICP opgave implications) |
| 209 | |
| 210 | **Purchase invoices (inkoopfacturen):** |
| 211 | - Expense category (bedrijfskosten, investeringen, voorraad) |
| 212 | - BTW amount on each (reclaimable for regular registration, cost for KOR) |
| 213 | - Supplier location (Dutch, EU, non-EU) |
| 214 | - Any items qualifying as bedrijfsmiddel (business asset for afschrijving) |
| 215 | - Any blocked categories (representatiekosten 80% limitation, private use) |
| 216 | |
| 217 | **Prior year IB-aangifte:** |
| 218 | - Prior year winst uit onderneming |
| 219 | - Prior year zelfstandigenaftrek and MKB-winstvrijstelling applied |
| 220 | - Prior year capital allowances schedule (restwaarde, afschrijving) |
| 221 | - Filing status and fiscal partner allocation |
| 222 | - Box 3 assets and threshold |
| 223 | - Eigenwoningforfait and hypotheekrenteaftrek if applicable |
| 224 | |
| 225 | **Prior BTW-aangiften:** |
| 226 | - Quarterly/monthly turnover and BTW collected |
| 227 | - Voorbelasting (input BTW) claimed |
| 228 | - Any suppletie-aangifte filed |
| 229 | - ICP leveringen/diensten reported |
| 230 | |
| 231 | **Jaaropgave (employment income):** |
| 232 | - Loon, loonheffing withheld, ZVW bijdrage |
| 233 | - Employer details |
| 234 | |
| 235 | **WOZ-beschikking and hypotheek jaaroverzicht:** |
| 236 | - WOZ-waarde (for eigenwoningforfait calculation) |
| 237 | - Hypotheekrente paid (for eigen woning aftrek Box 1) |
| 238 | - Eigenwoningschuld outstanding |
| 239 | |
| 240 | **After parsing everything, build an internal inference object.** Do not show the raw inference yet -- transform it into a compact summary for the user in Section 5. |
| 241 | |
| 242 | --- |
| 243 | |
| 244 | ## Section 5 -- The confirmation |
| 245 | |
| 246 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 247 | |
| 248 | **Example summary message:** |
| 249 | |
| 250 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 251 | > |
| 252 | > **Identity** |
| 253 | > - Jan de Vries, single (no fiscal partner) |
| 254 | > - Full-year Netherlands resident (Amsterdam) |
| 255 | > - ZZP / eenmanszaak, KvK 12345678 |
| 256 | > - BTW: Regular registration (NL123456789B01), quarterly filing |
| 257 | > |
| 258 | > **Income -- Winst uit onderneming (from bank statement + invoices)** |
| 259 | > - Omzet (turnover ex-BTW): ~EUR 68,000 |
| 260 | > - TechCorp BV: EUR 36,000 (monthly retainer) |
| 261 | > - DesignStudio: EUR 22,000 (project work) |
| 262 | > - Various smaller clients: EUR 10,000 |
| 263 | > - BTW collected (21%): ~EUR 14,280 |
| 264 | > |
| 265 | > **Expenses -- Bedrijfskosten (from bank statement + purchase invoices)** |
| 266 | > - Kantoorhuur (office rent): EUR 6,000 |
| 267 | > - Software / SaaS: EUR 2,400 |
| 268 | > - Aansprakelijkheidsverzekering (PI insurance): EUR 600 |
| 269 | > - Boekhouder (accountancy fees): EUR 1,200 |
| 270 | > - Telefoon / internet: EUR 840 (TBD -- need zakelijk gebruik %) |
| 271 | > - Auto: EUR 3,600 fuel + EUR 800 onderhoud (TBD -- need zakelijk gebruik % or km-registratie) |
| 272 | > - Laptop: EUR 1,800 (April 2025) -- bedrijfsmiddel, afschrijving 20% per jaar |
| 273 | > - Voorbelasting (input BTW): ~EUR 3,200 (reclaimable) |
| 274 | > |
| 275 | > **Ondernemersaftrek** |
| 276 | > - Zelfstandigenaftrek: EUR 2,470 (2025 rate) -- need to confirm urencriterium (1,225+ hours) |
| 277 | > - Startersaftrek: TBD -- need to confirm if within first 5 years and not claimed 3x |
| 278 | > - MKB-winstvrijstelling: 13.31% of remaining winst after zelfstandigenaftrek |
| 279 | > |
| 280 | > **Eigen woning (from WOZ + hypotheek)** |
| 281 | > - WOZ-waarde: EUR 320,000 |
| 282 | > - Eigenwoningforfait: EUR 1,760 (0.55% x EUR 320,000 -- 2025 rate) |
| 283 | > - Hypotheekrente betaald: EUR 8,400 |
| 284 | > - Eigen woning aftrek: EUR 6,640 (aftrek) |
| 285 | > |
| 286 | > **Voorlopige aanslag / voorheffingen (from bank statement)** |
| 287 | > - Voorlopige aanslag IB 2025 paid: EUR 4,200 |
| 288 | > - Voorlopige aanslag ZVW 2025 paid: EUR 1,800 |
| 289 | > |
| 290 | > **Prior year (from 2024 IB-aangifte)** |
| 291 | > - 2024 winst uit onderneming: EUR 52,000 |
| 292 | > - 2024 belastbaar inkomen Box 1: EUR 38,000 |
| 293 | > - Capital allowances continuing: laptop EUR 1,440 WDV |
| 294 | > |
| 295 | > **BTW (from prior BTW-aangiften)** |
| 296 | > - Q1-Q3 2025 filed |
| 297 | > - Q4 outstanding |
| 298 | > - No suppletie required based on current data |
| 299 | > |
| 300 | > **Flags I already see:** |
| 301 | > 1. Telefoon/internet -- need zakelijk gebruik percentage |
| 302 | > 2. Auto -- need zakelijk gebruik percentage and km-registratie (or consider forfaitaire autokosten EUR 0.23/km) |
| 303 | > 3. Urencriterium -- need confirmation of 1,225+ hours for zelfstandigenaftrek |
| 304 | > 4. Startersaftrek eligibility -- need to confirm year count |
| 305 | > 5. Q4 2025 BTW-aangifte not yet filed -- will prepare as part of this workflow |
| 306 | > 6. Box 3 vermogensrendementsheffing -- need to check bank/beleggingen saldi on 1 January 2025 and 2026 |
| 307 | > |
| 308 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 309 | |
| 310 | --- |
| 311 | |
| 312 | ## Section 6 -- Gap filling |
| 313 | |
| 314 | After the user confirms the summary (or corrects it), ask about things that cannot be inferred from documents. Use `ask_user_input_v0` where possible. |
| 315 | |
| 316 | **Things that usually cannot be inferred:** |
| 317 | |
| 318 | 1. **Urencriterium** -- 1,225 hours devoted to the onderneming. Cannot tell from documents alone. |
| 319 | 2. **Startersaftrek eligibility** -- Whether the user is within their first 5 years of self-employment and has not claimed startersaftrek more than 2 times before. |
| 320 | 3. **Home office (werkruimte)** -- Whether a dedicated werkruimte exists and qualifies (zelfstandige werkruimte criteria). |
| 321 | 4. **Private use percentage** -- Phone, internet, auto zakelijk gebruik split. |
| 322 | 5. **FOR (fiscale oudedagsreserve)** -- Whether the user wants to reserve FOR (maximum 9.44% of winst, up to EUR 9,632 in 2025). |
| 323 | 6. **Lijfrentepremie** -- Payments toward lijfrente (pension) for jaarruimte/reserveringsruimte deduction. |
| 324 | 7. **Box 3 vermogen** -- Bank balances, beleggingen, overige bezittingen, and schulden on peildatum 1 January 2025 and 1 January 2026. |
| 325 | 8. **Other income** -- Employment income, rental income, periodic payments (alimentatie). |
| 326 | 9. **Fiscal partner allocation** -- If fiscal partner exists, how to split Box 3, eigen woning, and heffingskortingen. |
| 327 | |
| 328 | **Urencriterium gap-filling example:** |
| 329 | |
| 330 | Call `ask_user_input_v0` with: |
| 331 | |
| 332 | ``` |
| 333 | Q: "Did you work at least 1,225 hours on your business in 2025?" |
| 334 | Options: [ |
| 335 | "Yes, comfortably above 1,225 hours (full-time self-employed)", |
| 336 | "Yes, but it's close (part-time self-employed, around 1,225)", |
| 337 | "No, under 1,225 hours", |
| 338 | "Not sure" |
| 339 | ] |
| 340 | ``` |
| 341 | |
| 342 | If option 1 -> zelfstandigenaftrek qualifies. Note T2: reviewer should confirm urenadministratie exists. |
| 343 | If option 2 -> flag T2: marginal case, urenadministratie is critical. Reviewer must verify. |
| 344 | If option 3 -> no zelfstandigenaftrek, no startersaftrek, no FOR. MKB-winstvrijstelling still applies. Income is still winst uit onderneming if KvK-registered. |
| 345 | If option 4 -> "The urencriterium requires you to have spent at least 1,225 hours on your business. Full-time freelancers almost always meet it. If you also had employment, count only the hours on your business. Do you think you're above or below?" |
| 346 | |
| 347 | **Startersaftrek gap-filling example:** |
| 348 | |
| 349 | Call `ask_user_input_v0` with: |
| 350 | |
| 351 | ``` |
| 352 | Q: "Startersaftrek eligibility?" |
| 353 | Options: [ |
| 354 | "Started in 2025 (first year)", |
| 355 | "2nd or 3rd year, have not claimed startersaftrek 3 times yet", |
| 356 | "Started more than 5 years ago", |
| 357 | "Already claimed startersaftrek 3 times", |
| 358 | "Not sure" |
| 359 | ] |
| 360 | ``` |
| 361 | |
| 362 | If option 1 or 2 -> EUR 2,123 startersaftrek on top of zelfstandigenaftrek (2025). |
| 363 | If option 3 or 4 -> no startersaftrek. |
| 364 | If not sure -> "When did you register at KvK? The 5-year window starts from your first year of claiming zelfstandigenaftrek." |
| 365 | |
| 366 | **Werkruimte (home office) gap-filling example:** |
| 367 | |
| 368 | Call `ask_user_input_v0` with: |
| 369 | |
| 370 | ``` |
| 371 | Q: "Home office (werkruimte)?" |
| 372 | Options: [ |
| 373 | "Separate room with own entrance -- qualifies as zelfstandige werkruimte", |
| 374 | "Dedicated room, no separate entrance, but I earn >70% of income there", |
| 375 | "Dedicated room, but I earn <70% of income there or also use it privately", |
| 376 | "Separate business premises (not at home)", |
| 377 | "No fixed workspace" |
| 378 | ] |
| 379 | ``` |
| 380 | |
| 381 | If option 1 -> qualifies as zelfstandige werkruimte. Ask for percentage of home floor area. Deduction for proportional huur/hypotheekrente/eigenwoningforfait/gas/elektra/water. |
| 382 | If option 2 -> qualifies if >70% income earned there AND >30% total income comes from this workspace. Ask for floor area percentage. T2 flag for reviewer. |
| 383 | If option 3 -> does not qualify as zelfstandige werkruimte. No home office deduction under Dutch rules. |
| 384 | If option 4 -> rent already captured in business expenses. No home office calculation needed. |
| 385 | If option 5 -> skip werkruimte entirely. |
| 386 | |
| 387 | **FOR (fiscale oudedagsreserve):** |
| 388 | |
| 389 | Call `ask_user_input_v0` with: |
| 390 | |
| 391 | ``` |
| 392 | Q: "Do you want to reserve FOR (fiscale oudedagsreserve) for 2025?" |
| 393 | Options: [ |
| 394 | "Yes, maximum allowed", |
| 395 | "Yes, specific amount (I'll tell you)", |
| 396 | "No", |
| 397 | "What is FOR?" |
| 398 | ] |
| 399 | ``` |
| 400 | |
| 401 | If "What is FOR?" -> "FOR lets you reserve up to 9.44% of your winst (max EUR 9,632 in 2025) as a tax-deductible pension reserve. It defers tax, not eliminates it -- you pay tax when you convert it to a lijfrente or at age 67. The maximum applies only if you meet the urencriterium and are under AOW age." |
| 402 | |
| 403 | Flag all private-use percentages as T2 -- belastingadviseur must confirm the percentage is reasonable and documented. |
| 404 | |
| 405 | --- |
| 406 | |
| 407 | ## Section 7 -- The final handoff |
| 408 | |
| 409 | Once gap-filling is done, produce a final handoff message and hand off to `nl-return-assembly`. |
| 410 | |
| 411 | **Example handoff message:** |
| 412 | |
| 413 | > Intake complete. Here's what's going to the return assembly: |
| 414 | > |
| 415 | > ZZP/eenmanszaak, single, regular BTW registration, full-year Netherlands resident. Omzet EUR 68,000, estimated winst ~EUR 52,000 before ondernemersaftrek. |
| 416 | > |
| 417 | > I'm now going to run the full Netherlands return preparation. This covers: |
| 418 | > 1. BTW-aangifte (Q4 2025 or suppletie) |
| 419 | > 2. Aangifte inkomstenbelasting (IB) -- Box 1 (winst, eigen woning), Box 3 (vermogen) |
| 420 | > 3. ZVW (zorgverzekeringswet) bijdrage reconciliation |
| 421 | > 4. Voorlopige aanslag 2026 recommendation |
| 422 | > |
| 423 | > You'll get back: |
| 424 | > 1. An Excel working paper with all forms and live formulas |
| 425 | > 2. A reviewer brief with positions, citations, and flags for your belastingadviseur |
| 426 | > 3. A filing calendar with all upcoming deadlines |
| 427 | > |
| 428 | > Starting now. |
| 429 | |
| 430 | Then internally invoke `nl-return-assembly` with the structured intake package. |
| 431 | |
| 432 | --- |
| 433 | |
| 434 | ## Section 8 -- Structured intake package (internal format) |
| 435 | |
| 436 | The downstream skill (`nl-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 437 | |
| 438 | ```json |
| 439 | { |
| 440 | "jurisdiction": "NL", |
| 441 | "tax_year": 2025, |
| 442 | "taxpayer": { |
| 443 | "name": "", |
| 444 | "bsn": "", |
| 445 | "birth_year": 0, |
| 446 | "marital_status": "single | married | registered_partner | fiscal_partner", |
| 447 | "residency": "full_year", |
| 448 | "kvk_nummer": "", |
| 449 | "btw_nummer": "", |
| 450 | "btw_registration_type": "regular | kor | unregistered", |
| 451 | "employment_status": "self_employed | employed_plus_side", |
| 452 | "industry": "", |
| 453 | "entity_type": "eenmanszaak" |
| 454 | }, |
| 455 | "income": { |
| 456 | "omzet_ex_btw": 0, |
| 457 | "btw_collected": 0, |
| 458 | "employment_income": 0, |
| 459 | "loonheffing_withheld": 0, |
| 460 | "other_income": 0, |
| 461 | "client_breakdown": [] |
| 462 | }, |
| 463 | "expenses": { |
| 464 | "fully_deductible": [], |
| 465 | "mixed_use": [], |
| 466 | "blocked": [], |
| 467 | "capital_items": [], |
| 468 | "representatiekosten": 0 |
| 469 | }, |
| 470 | "ondernemersaftrek": { |
| 471 | "urencriterium_met": true, |
| 472 | "zelfstandigenaftrek": 0, |
| 473 | "startersaftrek_eligible": false, |
| 474 | "startersaftrek": 0, |
| 475 | "mkb_winstvrijstelling_pct": 13.31, |
| 476 | "for_dotatie": 0 |
| 477 | }, |
| 478 | "btw": { |
| 479 | "filing_frequency": "quarterly | monthly", |
| 480 | "returns_filed": [], |
| 481 | "voorbelasting_reclaimable": 0, |
| 482 | "icp_leveringen": 0, |
| 483 | "icp_diensten": 0, |
| 484 | "suppletie_required": false |
| 485 | }, |
| 486 | "eigen_woning": { |
| 487 | "woz_waarde": 0, |
| 488 | "eigenwoningforfait": 0, |
| 489 | "hypotheekrente": 0, |
| 490 | "eigen_woning_aftrek": 0 |
| 491 | }, |
| 492 | "box3": { |
| 493 | "peildatum_1jan_2025": { |
| 494 | "bank_en_spaartegoeden": 0, |
| 495 | "beleggingen": 0, |
| 496 | "overige_bezittingen": 0, |
| 497 | "schulden": 0 |
| 498 | }, |
| 499 | "peildatum_1jan_2026": { |
| 500 | "bank_en_spaartegoeden": 0, |
| 501 | "beleggingen": 0, |
| 502 | "overige_bezittingen": 0, |
| 503 | "schulden": 0 |
| 504 | }, |
| 505 | "heffingsvrij_vermogen": 0 |
| 506 | }, |
| 507 | "voorlopige_aanslag": { |
| 508 | "ib_paid": 0, |
| 509 | "zvw_paid": 0 |
| 510 | }, |
| 511 | "prior_year": { |
| 512 | "winst_uit_onderneming": 0, |
| 513 | "belastbaar_inkomen_box1": 0, |
| 514 | "capital_allowances_schedule": [] |
| 515 | }, |
| 516 | "werkruimte": { |
| 517 | "qualifies": false, |
| 518 | "type": "zelfstandige_werkruimte | none", |
| 519 | "percentage": 0 |
| 520 | }, |
| 521 | "private_use": { |
| 522 | "auto_zakelijk_pct": 0, |
| 523 | "telefoon_zakelijk_pct": 0, |
| 524 | "internet_zakelijk_pct": 0 |
| 525 | }, |
| 526 | "fiscal_partner": { |
| 527 | "has_partner": false, |
| 528 | "partner_income": 0, |
| 529 | "allocation_preferences": {} |
| 530 | }, |
| 531 | "open_flags": [], |
| 532 | "refusals_triggered": [], |
| 533 | "documents_received": [] |
| 534 | } |
| 535 | ``` |
| 536 | |
| 537 | --- |
| 538 | |
| 539 | ## Section 9 -- Refusal handling |
| 540 | |
| 541 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., BV structure discovered in documents). |
| 542 | |
| 543 | When a refusal fires: |
| 544 | 1. Stop the workflow |
| 545 | 2. State the specific reason in one sentence |
| 546 | 3. Recommend the path forward (specific practitioner type) |
| 547 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 548 | |
| 549 | **Do not:** |
| 550 | - Apologize profusely |
| 551 | - Try to work around the refusal |
| 552 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 553 | - Continue silently |
| 554 | |
| 555 | **Refusals:** |
| 556 | |
| 557 | **R-NL-1 -- BV with employees > 5.** "Stop -- you have a BV with more than 5 employees. I'm set up for ZZP/eenmanszaak sole proprietors only. BVs with employees involve vennootschapsbelasting, loonbelasting, and werknemersverzekeringen. You need a belastingadviseur familiar with BV/werkgever returns." |
| 558 | |
| 559 | **R-NL-2 -- Holding structures.** "Stop -- you have a holding/werkmaatschappij structure. Multi-entity structures involve intercompany transactions, fiscal unity (fiscale eenheid), and participation exemption (deelnemingsvrijstelling). You need a belastingadviseur who specialises in holding structures." |
| 560 | |
| 561 | **R-NL-3 -- International payroll.** "Stop -- you have international payroll obligations. Cross-border employment involves 30% ruling, social security coordination (A1 detachering), and tax treaties. You need a belastingadviseur with international expertise." |
| 562 | |
| 563 | **Sample refusal:** |
| 564 | |
| 565 | > Stop -- you have a registered BV. I'm set up for ZZP/eenmanszaak sole proprietors only. BVs file vennootschapsbelasting returns with different rules for DGA-salaris, dividendbelasting, and Box 2 income. You need a belastingadviseur familiar with BV returns. |
| 566 | > |
| 567 | > I can't help with this one. |
| 568 | |
| 569 | --- |
| 570 | |
| 571 | ## Section 10 -- Self-checks |
| 572 | |
| 573 | **Check IN1 -- No one-question-at-a-time prose in the refusal sweep.** If the skill asked "Question 1 of 10" or walked through questions as separate messages, check fails. |
| 574 | |
| 575 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 576 | |
| 577 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 578 | |
| 579 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 580 | |
| 581 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "did you pay BTW" after the bank statement showed Belastingdienst payments, check fails. |
| 582 | |
| 583 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 584 | |
| 585 | **Check IN7 -- Handoff to `nl-return-assembly` is explicit.** The user was told "I'm now going to run the return preparation," and the downstream orchestrator was explicitly invoked with the intake package. |
| 586 | |
| 587 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned belastingadviseur signoff. |
| 588 | |
| 589 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 590 | |
| 591 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 592 | |
| 593 | **Check IN11 -- Total user-facing turn count is low.** Target: 8 turns or fewer from start to handoff for a prepared user (1 refusal batch + 1 upload + 1 confirmation + 1-3 gap fills + 1 handoff). More than 12 turns for a normal intake is a check failure. |
| 594 | |
| 595 | **Check IN12 -- BTW registration type was established.** Regular vs KOR was confirmed before inference, as it changes how every transaction is classified. |
| 596 | |
| 597 | --- |
| 598 | |
| 599 | ## Section 11 -- Performance targets |
| 600 | |
| 601 | For a prepared user (documents in a folder, ready to upload): |
| 602 | - **Refusal sweep**: 45 seconds (1-2 interactive turns) |
| 603 | - **Document upload**: 2 minutes (1 upload turn) |
| 604 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 605 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 606 | - **Handoff**: immediate |
| 607 | - **Total**: ~6 minutes |
| 608 | |
| 609 | For an unprepared user (has to go fetch documents): |
| 610 | - Refusal sweep: same |
| 611 | - Document discovery: 10-20 minutes offline |
| 612 | - Rest: same |
| 613 | - **Total**: 15-25 minutes |
| 614 | |
| 615 | --- |
| 616 | |
| 617 | ## Section 12 -- Cross-skill references |
| 618 | |
| 619 | **Inputs:** User-provided documents and answers. |
| 620 | |
| 621 | **Outputs:** Structured intake package consumed by `nl-return-assembly`. |
| 622 | |
| 623 | **Downstream skills triggered (via nl-return-assembly):** |
| 624 | - `nl-btw-return` -- BTW-aangifte (quarterly/monthly or KOR annual) |
| 625 | - `nl-income-tax` -- Aangifte inkomstenbelasting (Box 1/2/3) |
| 626 | - `nl-zvw` -- Zorgverzekeringswet bijdrage reconciliation |
| 627 | |
| 628 | --- |
| 629 | |
| 630 | ### Change log |
| 631 | |
| 632 | - **v1.0 (May 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on mt-freelance-intake v0.1. |
| 633 | |
| 634 | ## End of Intake Skill v1.0 |
| 635 | |
| 636 | |
| 637 | --- |
| 638 | |
| 639 | ## Disclaimer |
| 640 | |
| 641 | This skill and its outputs are provided for informational and computational purposes only and do not constitute tax, legal, or financial advice. Open Accountants and its contributors accept no liability for any errors, omissions, or outcomes arising from the use of this skill. All outputs must be reviewed and signed off by a qualified professional (such as a CPA, EA, tax attorney, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 642 | |
| 643 | The most up-to-date, verified version of this skill is maintained at [openaccountants.com](https://openaccountants.com). Log in to access the latest version, request a professional review from a licensed accountant, and track updates as tax law changes. |
| 644 |
Run this skill, then get an accountant to check it
After running the full skill pack in your AI agent, sign up and upload your worksheet. We'll connect you with a trusted accountant in our network who can review your numbers before you file.
Verification status
Research-verified
Drafted from authoritative sources (tax authority sites, Big-4 summaries). Awaiting credentialed sign-off.
Needs section-by-section practitioner review to reach accountant-verified.
Section review progress
0/19
About
ALWAYS USE THIS SKILL when a user asks for help preparing their Netherlands tax returns AND mentions freelancing, self-employment, ZZP, eenmanszaak, or sole proprietorship. Trigger on phrases like "help me do my taxes", "prepare my IB-aangifte", "I'm a ZZP'er in the Netherlands", "I'm a freelancer in the Netherlands", "do my taxes as a contractor", "prepare my BTW return and income tax", or any similar phrasing where the user is a Netherlands-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Netherlands self-employed tax workflow -- every other skill in the stack (nl-btw-return, nl-income-tax, nl-zvw, nl-return-assembly) depends on this skill running first to produce a structured intake package. Uses upload-first workflow -- the user dumps all their documents and the skill infers as much as possible before asking questions. Uses ask_user_input_v0 for structured questions instead of one-at-a-time prose. Built for speed. Netherlands full-year residents only; self-employed individuals and sole proprietors.
NLty-2025
Use this skill
This skill is open source and free to use in any AI agent. Copy it, download it, or clone the repo. If you find an error, report an issue — a licensed accountant will review.