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.
jp-freelance-intake.md627 lines29.4 KB
v10Japan
Not yet verified by an accountantContact accountant
| 1 | --- |
| 2 | name: jp-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their Japanese tax returns AND mentions freelancing, self-employment, 個人事業主, フリーランス, sole proprietorship, or kojin jigyounushi. Trigger on phrases like "確定申告を手伝って", "help me file my kakutei shinkoku", "I'm a freelancer in Japan", "prepare my blue return", "I'm self-employed in Japan", or any similar phrasing where the user is a Japan-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Japanese self-employed tax workflow -- every other skill in the stack (japan-consumption-tax, japan-income-tax, japan-social-insurance, jp-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. Japan full-year residents only; self-employed individuals and sole proprietors (個人事業主). |
| 4 | version: 1.0 |
| 5 | jurisdiction: JP |
| 6 | category: orchestrator |
| 7 | --- |
| 8 | |
| 9 | # Japan Self-Employed Intake Skill v1.0 |
| 10 | |
| 11 | ## What this file is |
| 12 | |
| 13 | The intake orchestrator for Japan-resident self-employed individuals. Every downstream Japanese content skill (japan-consumption-tax, japan-income-tax, japan-social-insurance, jp-estimated-tax) and the assembly orchestrator (jp-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 `jp-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 files a blue return, do not later ask about return type. Track what is known. |
| 36 | |
| 37 | **Do not ask about things visible in uploaded documents.** If the bank statement shows 国民年金 (National Pension) debits, do not ask "did you pay pension." 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 税理士 zeirishi 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 Japanese tax 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 税理士 (zeirishi / licensed tax accountant) before you file anything with the 税務署 (tax office). 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: "Business type?" |
| 85 | Options: ["個人事業主 (kojin jigyounushi / sole proprietor)", "フリーランス (freelance, no opening notification filed)", "法人 (houjin / corporation)", "Not sure"] |
| 86 | |
| 87 | Q2: "Revenue range for 2025?" |
| 88 | Options: ["Under ¥10,000,000", "¥10,000,000 -- ¥50,000,000", "Over ¥50,000,000", "Not sure"] |
| 89 | |
| 90 | Q3: "Blue return (青色申告) or white return (白色申告)?" |
| 91 | Options: ["Blue return (青色申告承認申請書 filed)", "White return (白色申告)", "Not sure"] |
| 92 | ``` |
| 93 | |
| 94 | **After the response, evaluate:** |
| 95 | |
| 96 | - **Q1 = 個人事業主** -> continue. Standard sole proprietor. 開業届 (kaigyo todoke) filed with tax office. |
| 97 | - **Q1 = フリーランス (no opening notification)** -> continue with a flag: technically should have filed 開業届 within 1 month of starting business (所得税法第229条). If income qualifies as 事業所得 (business income) vs 雑所得 (miscellaneous income), classification matters. Will evaluate after inference. |
| 98 | - **Q1 = 法人 (corporation)** -> stop. "法人 (corporations) file a separate corporate tax return (法人税申告書). I'm set up for 個人事業主 (sole proprietors) filing 確定申告 (individual income tax). You need a 税理士 who handles 法人税." |
| 99 | - **Q1 = Not sure** -> ask one follow-up: "Did you file an 開業届 (opening notification) with the tax office? Or do you have a 法人番号 (corporate number)? If you filed 開業届, you're a 個人事業主. If you have a corporate number or 登記簿謄本, you're a 法人." |
| 100 | |
| 101 | - **Q2 = Under ¥10M** -> continue. Below consumption tax threshold for base period (基準期間 kijun kikan). |
| 102 | - **Q2 = ¥10M-¥50M** -> continue with flag: consumption tax (消費税) filing likely required if base period revenue (2023 for tax year 2025) exceeded ¥10M (消費税法第9条). Also flag: simplified tax calculation (簡易課税 kan'i kazei) available if base period revenue ≤ ¥50M (消費税法第37条). |
| 103 | - **Q2 = Over ¥50M** -> continue with flag: consumption tax required, simplified calculation NOT available, must use standard (本則課税 honsoku kazei) method. |
| 104 | - **Q2 = Not sure** -> continue, infer from documents. |
| 105 | |
| 106 | - **Q3 = Blue return** -> continue. 青色申告特別控除 (blue return special deduction) available: ¥650,000 (e-Tax + double-entry bookkeeping or 電子帳簿保存), ¥550,000 (double-entry paper filing), or ¥100,000 (simplified bookkeeping). |
| 107 | - **Q3 = White return** -> continue. No special deduction. Simpler 収支内訳書 (income/expense statement) instead of full 青色申告決算書 (blue return financial statements). |
| 108 | - **Q3 = Not sure** -> ask one follow-up: "Did you file a 青色申告承認申請書 (blue return approval application) with the tax office? If you did (usually at the same time as 開業届), you're blue. If not, you're white by default. Check your records or ask your tax office." |
| 109 | |
| 110 | **After Q1-Q3 pass, ask the second batch of scope questions (also batched):** |
| 111 | |
| 112 | ``` |
| 113 | Q4: "Consumption tax and invoice registration?" |
| 114 | Options: ["適格請求書発行事業者 (qualified invoice issuer) registered", "Not registered for invoices (免税事業者 tax-exempt business)", "Registered but considering opting out", "Not sure"] |
| 115 | |
| 116 | Q5: "Marital status and dependents?" |
| 117 | Options: ["Single, no dependents", "Married (配偶者控除 / 配偶者特別控除 eligible spouse)", "Married (spouse earns > ¥2,010,000)", "Have dependent family members (扶養親族)"] |
| 118 | |
| 119 | Q6: "Other income sources in 2025?" |
| 120 | Options: ["None -- self-employment only", "Employment income (給与所得 kyuuyo shotoku)", "Rental income (不動産所得 fudousan shotoku)", "Stock/dividend income (配当所得 haitou shotoku / 譲渡所得 joutsuu shotoku)", "Multiple of the above"] |
| 121 | |
| 122 | Q7: "e-Tax filing preference?" |
| 123 | Options: ["e-Tax (マイナンバーカード + スマホ or ICカードリーダー)", "e-Tax (ID・パスワード方式)", "Paper filing at tax office", "Not sure"] |
| 124 | |
| 125 | Q8: "Prior year's tax payment (2024 確定申告)?" |
| 126 | Options: ["Paid final tax ≥ ¥150,000 (予定納税 yotei nouzei applies)", "Paid final tax < ¥150,000", "First year filing", "Not sure"] |
| 127 | ``` |
| 128 | |
| 129 | **Evaluate Q4:** |
| 130 | - **Registered (適格請求書発行事業者)** -> continue. Issues qualified invoices (適格請求書 / インボイス). Must file consumption tax return even if revenue < ¥10M (irrevocable for registration period). 2割特例 (20% special provision) may apply if was previously 免税事業者 and registered solely for invoice system (available through tax year 2026 returns per 令和5年改正法附則). |
| 131 | - **Not registered (免税事業者)** -> continue. No consumption tax filing obligation (if base period < ¥10M). Cannot issue qualified invoices -- clients cannot claim input tax credit on payments. |
| 132 | - **Registered but considering opting out** -> continue with flag: opting out requires 適格請求書発行事業者の登録の取消しを求める届出書, effective from the start of the following fiscal year if filed ≥ 30 days before end of current year. |
| 133 | - **Not sure** -> ask: "Check the 国税庁 (NTA) invoice registration site (適格請求書発行事業者公表サイト) for your name or registration number (T + 13 digits). If found, you're registered." |
| 134 | |
| 135 | **Evaluate Q5:** |
| 136 | - **Single, no dependents** -> continue. 基礎控除 (basic deduction) ¥480,000 only (if income ≤ ¥24M). |
| 137 | - **Married (spouse eligible)** -> continue. 配偶者控除 (spouse deduction) up to ¥380,000 if spouse income ≤ ¥480,000 (合計所得金額). 配偶者特別控除 (special spouse deduction) if spouse income ¥480,001-¥1,330,000. Taxpayer's own income must be ≤ ¥10M for either deduction. |
| 138 | - **Married (high-earning spouse)** -> continue. No spouse deduction available. |
| 139 | - **Dependent family members** -> continue. 扶養控除: ¥380,000 per dependent (general), ¥630,000 (specific: age 19-22), ¥480,000 (elderly: age 70+), ¥580,000 (elderly living together). |
| 140 | |
| 141 | **Evaluate Q6:** |
| 142 | - All options -> note for multi-schedule return. 給与所得 has its own calculation (給与所得控除). 不動産所得 requires separate schedule. 配当所得 may use 申告分離課税 (separate taxation at 20.315%) or 総合課税 (aggregate taxation with 配当控除). |
| 143 | |
| 144 | **Evaluate Q7:** |
| 145 | - **e-Tax with マイナンバーカード** -> continue. Qualifies for ¥650,000 blue return special deduction (if double-entry bookkeeping maintained). |
| 146 | - **e-Tax ID/password** -> continue. Same e-Tax benefit for blue return deduction. |
| 147 | - **Paper filing** -> continue with flag: blue return special deduction capped at ¥550,000 (double-entry) or ¥100,000 (simplified). Consider switching to e-Tax. |
| 148 | - **Not sure** -> note, will recommend e-Tax in action items. |
| 149 | |
| 150 | **Evaluate Q8:** |
| 151 | - **≥ ¥150,000** -> continue. 予定納税 (estimated tax) applied: two equal instalments (1st period: July, 2nd period: November), each = 1/3 of prior year's 申告納税額. Already paid amounts reduce final balance. |
| 152 | - **< ¥150,000** -> continue. No 予定納税 obligation. |
| 153 | - **First year** -> continue. No 予定納税. |
| 154 | - **Not sure** -> infer from prior year return or bank statements. |
| 155 | |
| 156 | **Total time:** ~60 seconds if the user taps through. |
| 157 | |
| 158 | --- |
| 159 | |
| 160 | ## Section 3 -- The dump |
| 161 | |
| 162 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 163 | |
| 164 | **Example:** |
| 165 | |
| 166 | > Scope is good. Now upload everything you have for 2025 -- drop it all in at once: |
| 167 | > |
| 168 | > - Business bank account statements for all of 2025 (CSV or PDF) |
| 169 | > - Sales invoices issued in 2025 (請求書) |
| 170 | > - Purchase invoices / receipts for business expenses (領収書) |
| 171 | > - Prior year's 確定申告書 (tax return) and 青色申告決算書 or 収支内訳書 |
| 172 | > - 源泉徴収票 (withholding tax certificate) if you received payments with withholding (源泉徴収) |
| 173 | > - 控除証明書 (deduction certificates): 社会保険料, 生命保険料, 地震保険料, 小規模企業共済 |
| 174 | > - 国民健康保険料 (NHI) payment notices from your municipality |
| 175 | > - 国民年金 payment certificates from 日本年金機構 |
| 176 | > - Prior year's 予定納税 notices or payment receipts |
| 177 | > - Accounting software export (freee, Money Forward, やよい, etc.) |
| 178 | > - Any 税務署 correspondence |
| 179 | > - Anything else tax-related you have |
| 180 | > |
| 181 | > Don't worry about labeling or organizing -- I'll figure out what each file is. Drag and drop when ready. |
| 182 | |
| 183 | Then wait. Do not ask any other questions while waiting. |
| 184 | |
| 185 | **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. |
| 186 | |
| 187 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 188 | > Check these places: |
| 189 | > - Business bank: download 2025 statements as CSV or PDF |
| 190 | > - Accounting software (freee, Money Forward クラウド, やよいの青色申告): export 仕訳帳 or 総勘定元帳 |
| 191 | > - e-Tax: download prior year 確定申告書 and 決算書 |
| 192 | > - 年金事務所 or ねんきんネット: download 国民年金控除証明書 |
| 193 | > - Municipality: 国民健康保険料 payment statement |
| 194 | > - Insurance companies: 生命保険料控除証明書, 地震保険料控除証明書 |
| 195 | > - Clients: request 支払調書 (payment records) or check for 源泉徴収票 |
| 196 | > - Email: search for "請求書", "領収書", "確定申告", "税務署" |
| 197 | > |
| 198 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 199 | |
| 200 | --- |
| 201 | |
| 202 | ## Section 4 -- The inference pass |
| 203 | |
| 204 | When documents arrive, parse each one. For each document, extract: |
| 205 | |
| 206 | **Bank statement:** |
| 207 | - Total deposits (candidate 売上 uriage / revenue) |
| 208 | - Recurring inflows (client payments with names) |
| 209 | - Outflows to 税務署 (所得税 income tax payments, 予定納税 estimated tax) |
| 210 | - Outflows to municipality (住民税 juminzei / resident tax) |
| 211 | - Outflows to 国民健康保険 (NHI premiums) |
| 212 | - Outflows to 国民年金 (national pension premiums) |
| 213 | - Outflows to suppliers (business expenses by category: 経費 keihi) |
| 214 | - Equipment purchases (potential 減価償却 genkashoukyaku / depreciation assets) |
| 215 | - Transfers to personal account (事業主貸 jigyounushi kashi) |
| 216 | - SaaS / software subscriptions |
| 217 | - 小規模企業共済 (Small Enterprise Mutual Aid) payments |
| 218 | - iDeCo (個人型確定拠出年金) payments |
| 219 | - 生命保険 (life insurance) premiums |
| 220 | - 地震保険 (earthquake insurance) premiums |
| 221 | |
| 222 | **Sales invoices (請求書):** |
| 223 | - Client names and amounts (税込 tax-included and 税抜 tax-excluded) |
| 224 | - Whether consumption tax was charged (and at what rate: 10% standard, 8% reduced) |
| 225 | - Whether invoices are 適格請求書 (qualified invoices) with registration number |
| 226 | - Total 売上 reconciliation against bank deposits |
| 227 | - Any clients applying 源泉徴収 (withholding): 10.21% on payments up to ¥1M, 20.42% above ¥1M (per specific income types listed in 所得税法第204条) |
| 228 | - Foreign clients (no Japanese consumption tax on exported services per 消費税法第7条) |
| 229 | |
| 230 | **Purchase invoices / receipts (領収書):** |
| 231 | - Expense category (経費科目: 旅費交通費, 通信費, 接待交際費, 消耗品費, etc.) |
| 232 | - Consumption tax paid (仕入税額控除 input tax credit, if consumption tax filer) |
| 233 | - Any items qualifying as 減価償却資産 (depreciable assets): generally ≥ ¥100,000 |
| 234 | - Items ¥100,000-¥299,999: eligible for 一括償却 (3-year straight-line) or 少額減価償却資産の特例 (immediate expensing for blue return filers, up to ¥3M total per year per 租税特別措置法第28条の2) |
| 235 | - Any blocked categories (家事関連費 mixed personal/business without clear business proportion) |
| 236 | |
| 237 | **Prior year 確定申告書 / 青色申告決算書:** |
| 238 | - Prior year 所得金額 (income amount) by category |
| 239 | - Prior year 申告納税額 (tax payable -- drives 予定納税) |
| 240 | - Prior year 青色申告特別控除 amount applied |
| 241 | - 繰越損失 (carryforward losses from prior years -- up to 3 years for blue return filers) |
| 242 | - 減価償却資産 schedule (continuing depreciation) |
| 243 | - Filing method (e-Tax vs paper) |
| 244 | |
| 245 | **源泉徴収票 (withholding certificates):** |
| 246 | - Amount of income subject to withholding |
| 247 | - Amount withheld (源泉徴収税額) |
| 248 | - Client name and address |
| 249 | - Will be credited against final tax liability on 確定申告書 |
| 250 | |
| 251 | **控除証明書 (deduction certificates):** |
| 252 | - 社会保険料控除: 国民健康保険, 国民年金 amounts paid |
| 253 | - 生命保険料控除: 一般, 介護医療, 個人年金 categories and amounts (new system post-2012: max ¥40,000 each, total max ¥120,000) |
| 254 | - 地震保険料控除: amount paid (max ¥50,000) |
| 255 | - 小規模企業共済等掛金控除: 小規模企業共済 and iDeCo amounts (fully deductible) |
| 256 | |
| 257 | **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. |
| 258 | |
| 259 | --- |
| 260 | |
| 261 | ## Section 5 -- The confirmation |
| 262 | |
| 263 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 264 | |
| 265 | **Example summary message:** |
| 266 | |
| 267 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 268 | > |
| 269 | > **Identity** |
| 270 | > - 田中太郎 (Tanaka Taro), married, 1 dependent child |
| 271 | > - Full-year Japan resident (Shibuya-ku, Tokyo) |
| 272 | > - 個人事業主, 開業届 filed |
| 273 | > - 青色申告 (blue return), e-Tax filing |
| 274 | > - 適格請求書発行事業者 registered (T1234567890123) |
| 275 | > |
| 276 | > **Income (from bank statement + invoices)** |
| 277 | > - 売上 (revenue, tax-excluded): ¥12,500,000 |
| 278 | > - ABC株式会社: ¥6,000,000 (monthly retainer, 源泉徴収 ¥612,600) |
| 279 | > - DEF合同会社: ¥4,000,000 (project work) |
| 280 | > - Various smaller clients: ¥2,500,000 |
| 281 | > - 消費税 collected (10%): ¥1,250,000 |
| 282 | > - 源泉徴収 total withheld: ¥612,600 |
| 283 | > |
| 284 | > **Expenses (from bank + receipts, tax-excluded)** |
| 285 | > - 地代家賃 (rent -- home office portion): ¥720,000 (TBD -- need business use %) |
| 286 | > - 通信費 (internet, phone): ¥180,000 (TBD -- need business use %) |
| 287 | > - 旅費交通費 (travel): ¥350,000 |
| 288 | > - 消耗品費 (supplies): ¥120,000 |
| 289 | > - 新聞図書費 (books, subscriptions): ¥85,000 |
| 290 | > - 外注費 (subcontracting): ¥800,000 |
| 291 | > - 減価償却: MacBook Pro ¥280,000 (April 2025) -- 少額減価償却資産特例 eligible (blue return, < ¥300,000) |
| 292 | > - Total deductible expenses (preliminary): ~¥2,535,000 |
| 293 | > |
| 294 | > **Social insurance (from 控除証明書 + bank statement)** |
| 295 | > - 国民健康保険: ¥620,000 |
| 296 | > - 国民年金: ¥203,760 (¥16,980 x 12) |
| 297 | > - 小規模企業共済: ¥840,000 (¥70,000/month) |
| 298 | > - Total 社会保険料控除 + 小規模企業共済等掛金控除: ¥1,663,760 |
| 299 | > |
| 300 | > **Estimated tax (予定納税)** |
| 301 | > - 1st period (July): ¥250,000 |
| 302 | > - 2nd period (November): ¥250,000 |
| 303 | > - Total paid: ¥500,000 |
| 304 | > |
| 305 | > **Prior year (from 2024 確定申告書)** |
| 306 | > - 2024 事業所得: ¥8,200,000 |
| 307 | > - 2024 申告納税額: ¥750,000 |
| 308 | > - 繰越損失: none |
| 309 | > - 青色申告特別控除: ¥650,000 applied |
| 310 | > |
| 311 | > **Consumption tax (消費税)** |
| 312 | > - Revenue > ¥10M in base period (2023): likely consumption tax filer |
| 313 | > - 適格請求書発行事業者 registered |
| 314 | > - 2割特例 (20% special provision): TBD -- check eligibility |
| 315 | > - 簡易課税: TBD -- check if 届出書 was filed and base period ≤ ¥50M |
| 316 | > |
| 317 | > **Flags I already see:** |
| 318 | > 1. Home office -- need business use percentage for rent, internet, phone (家事按分) |
| 319 | > 2. MacBook Pro ¥280,000 -- eligible for 少額減価償却資産の特例 (immediate expensing) since blue return and < ¥300,000. Verify total 少額 assets don't exceed ¥3M for the year. |
| 320 | > 3. 源泉徴収 ¥612,600 from ABC株式会社 -- will be credited against final tax. Verify 支払調書 matches. |
| 321 | > 4. Consumption tax method needs determination: 本則課税 vs 簡易課税 vs 2割特例 |
| 322 | > 5. Revenue ¥12.5M -- above ¥10M threshold, so 2027 will definitely require consumption tax filing regardless of invoice registration |
| 323 | > |
| 324 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 325 | |
| 326 | --- |
| 327 | |
| 328 | ## Section 6 -- Gap filling |
| 329 | |
| 330 | 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. |
| 331 | |
| 332 | **Things that usually cannot be inferred:** |
| 333 | |
| 334 | 1. **Home office (家事按分 kaji anbun)** -- business-use percentage of rent, utilities, internet. |
| 335 | 2. **Vehicle use** -- business-use percentage if applicable. |
| 336 | 3. **Consumption tax calculation method** -- whether 簡易課税届出書 was filed, whether 2割特例 is preferred. |
| 337 | 4. **Dependents detail** -- ages, income levels, living arrangements (同居 vs 別居) for correct 扶養控除 amount. |
| 338 | 5. **Spouse income** -- exact amount for 配偶者控除 / 配偶者特別控除 determination. |
| 339 | 6. **Medical expenses** -- 医療費控除 (medical expense deduction) if total exceeds ¥100,000 or 10% of income. |
| 340 | 7. **ふるさと納税 (hometown tax donations)** -- 寄附金控除 (donation deduction) certificates. |
| 341 | 8. **生命保険 / 地震保険** -- if certificates not in upload, ask whether applicable. |
| 342 | |
| 343 | **Home office gap-filling example:** |
| 344 | |
| 345 | Call `ask_user_input_v0` with: |
| 346 | |
| 347 | ``` |
| 348 | Q: "Home office (自宅兼事務所) setup?" |
| 349 | Options: [ |
| 350 | "Dedicated room, used ONLY for work", |
| 351 | "Dedicated desk/area in a room", |
| 352 | "Shared space (living room, kitchen)", |
| 353 | "Separate office or coworking space (not at home)", |
| 354 | "No fixed workspace" |
| 355 | ] |
| 356 | ``` |
| 357 | |
| 358 | If option 1 -> ask for room area and total home area for 家事按分 percentage. Commonly accepted: room area / total area. |
| 359 | If option 2 -> flag for reviewer: partial room use. Often 30-50% of room, then room/total for overall percentage. Conservative approach recommended. |
| 360 | If option 3 -> flag: shared space makes 家事按分 harder to defend. Conservative percentage (10-20%) with documentation. |
| 361 | If option 4 -> rent already captured in business expenses. No 家事按分 needed. |
| 362 | If option 5 -> skip home office entirely. |
| 363 | |
| 364 | **Consumption tax method example:** |
| 365 | |
| 366 | Call `ask_user_input_v0` with: |
| 367 | |
| 368 | ``` |
| 369 | Q: "Consumption tax (消費税) calculation method?" |
| 370 | Options: [ |
| 371 | "簡易課税 (simplified) -- filed 届出書 with tax office", |
| 372 | "本則課税 (standard) -- actual input tax credits", |
| 373 | "2割特例 (20% special provision) -- was 免税事業者 before invoice registration", |
| 374 | "Not sure -- help me choose" |
| 375 | ] |
| 376 | ``` |
| 377 | |
| 378 | If "Not sure" -> compute under all eligible methods and recommend the one producing the lowest tax. Note in reviewer brief. |
| 379 | |
| 380 | **Medical expenses example:** |
| 381 | |
| 382 | Call `ask_user_input_v0` with: |
| 383 | |
| 384 | ``` |
| 385 | Q: "Medical expenses (医療費) in 2025?" |
| 386 | Options: [ |
| 387 | "Over ¥100,000 for the household", |
| 388 | "Under ¥100,000", |
| 389 | "Used セルフメディケーション税制 (OTC medicine deduction)", |
| 390 | "Not sure" |
| 391 | ] |
| 392 | ``` |
| 393 | |
| 394 | If over ¥100,000 -> request 医療費の明細書 or individual receipts. Deduction = total - ¥100,000 (or total - 10% of income if income < ¥2M). |
| 395 | |
| 396 | --- |
| 397 | |
| 398 | ## Section 7 -- The final handoff |
| 399 | |
| 400 | Once gap-filling is done, produce a final handoff message and hand off to `jp-return-assembly`. |
| 401 | |
| 402 | **Example handoff message:** |
| 403 | |
| 404 | > Intake complete. Here's what's going to the return assembly: |
| 405 | > |
| 406 | > 個人事業主, blue return (青色申告), married with 1 dependent, e-Tax filing, 適格請求書発行事業者. Revenue ¥12.5M tax-excluded, estimated 事業所得 ~¥9.3M before blue return deduction. Consumption tax filer. |
| 407 | > |
| 408 | > I'm now going to run the full Japanese return preparation. This covers: |
| 409 | > 1. 消費税 (consumption tax) return |
| 410 | > 2. 所得税 確定申告書 (income tax return) with 青色申告決算書 |
| 411 | > 3. 社会保険 reconciliation (国民健康保険, 国民年金) |
| 412 | > 4. 予定納税 and estimated payments for 2026 |
| 413 | > |
| 414 | > You'll get back: |
| 415 | > 1. A working paper with all forms and computations |
| 416 | > 2. A reviewer brief with positions, citations, and flags for your 税理士 |
| 417 | > 3. A filing calendar with all upcoming deadlines |
| 418 | > |
| 419 | > Starting now. |
| 420 | |
| 421 | Then internally invoke `jp-return-assembly` with the structured intake package. |
| 422 | |
| 423 | --- |
| 424 | |
| 425 | ## Section 8 -- Structured intake package (internal format) |
| 426 | |
| 427 | The downstream skill (`jp-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 428 | |
| 429 | ```json |
| 430 | { |
| 431 | "jurisdiction": "JP", |
| 432 | "tax_year": 2025, |
| 433 | "taxpayer": { |
| 434 | "name": "", |
| 435 | "name_kana": "", |
| 436 | "date_of_birth": "", |
| 437 | "my_number": "", |
| 438 | "marital_status": "single | married", |
| 439 | "spouse_income": 0, |
| 440 | "dependents": [], |
| 441 | "residency": "full_year", |
| 442 | "address": "", |
| 443 | "tax_office": "", |
| 444 | "business_type": "kojin_jigyounushi | freelance_no_kaigyo", |
| 445 | "blue_return": true, |
| 446 | "blue_return_deduction_level": "650000 | 550000 | 100000", |
| 447 | "invoice_registered": true, |
| 448 | "invoice_registration_number": "", |
| 449 | "filing_method": "e_tax_mynumber | e_tax_id_password | paper" |
| 450 | }, |
| 451 | "income": { |
| 452 | "jigyou_shotoku": { |
| 453 | "uriage_zeikomi": 0, |
| 454 | "uriage_zeinuki": 0, |
| 455 | "consumption_tax_collected": 0, |
| 456 | "client_breakdown": [], |
| 457 | "gensen_choushu_total": 0 |
| 458 | }, |
| 459 | "other_income": { |
| 460 | "kyuuyo_shotoku": 0, |
| 461 | "fudousan_shotoku": 0, |
| 462 | "haitou_shotoku": 0, |
| 463 | "zatsu_shotoku": 0 |
| 464 | } |
| 465 | }, |
| 466 | "expenses": { |
| 467 | "keihi_by_category": {}, |
| 468 | "kaji_anbun": { |
| 469 | "rent_business_pct": 0, |
| 470 | "internet_business_pct": 0, |
| 471 | "phone_business_pct": 0, |
| 472 | "utilities_business_pct": 0 |
| 473 | }, |
| 474 | "depreciation_assets": [], |
| 475 | "shougaku_assets": [] |
| 476 | }, |
| 477 | "consumption_tax": { |
| 478 | "filing_required": true, |
| 479 | "method": "honsoku | kani | niwari_tokurei", |
| 480 | "kani_gyoushu": 0, |
| 481 | "base_period_revenue": 0, |
| 482 | "was_menzei_before_invoice": false |
| 483 | }, |
| 484 | "deductions": { |
| 485 | "shakai_hokenryo": { |
| 486 | "kokumin_kenko_hoken": 0, |
| 487 | "kokumin_nenkin": 0, |
| 488 | "other": 0 |
| 489 | }, |
| 490 | "shokibo_kigyou_kyousai": 0, |
| 491 | "ideco": 0, |
| 492 | "seimei_hokenryo": { |
| 493 | "ippan": 0, |
| 494 | "kaigo_iryou": 0, |
| 495 | "kojin_nenkin": 0 |
| 496 | }, |
| 497 | "jishin_hokenryo": 0, |
| 498 | "iryouhi_koujo": 0, |
| 499 | "furusato_nouzei": 0, |
| 500 | "haigusha_koujo": 0, |
| 501 | "fuyou_koujo": 0, |
| 502 | "kiso_koujo": 480000 |
| 503 | }, |
| 504 | "estimated_tax": { |
| 505 | "prior_year_shinkoku_nouzei": 0, |
| 506 | "yotei_nouzei_1st": 0, |
| 507 | "yotei_nouzei_2nd": 0, |
| 508 | "total_paid": 0 |
| 509 | }, |
| 510 | "prior_year": { |
| 511 | "jigyou_shotoku": 0, |
| 512 | "shinkoku_nouzei_gaku": 0, |
| 513 | "kurikoshi_songaku": 0, |
| 514 | "depreciation_schedule": [] |
| 515 | }, |
| 516 | "open_flags": [], |
| 517 | "refusals_triggered": [], |
| 518 | "documents_received": [] |
| 519 | } |
| 520 | ``` |
| 521 | |
| 522 | --- |
| 523 | |
| 524 | ## Section 9 -- Refusal handling |
| 525 | |
| 526 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., corporate structure discovered in documents). |
| 527 | |
| 528 | **Refusal catalogue:** |
| 529 | |
| 530 | - **R-JP-1 -- 法人 (corporation).** "法人 (corporations) file 法人税申告書 (corporate tax return) with different forms, deadlines, and rates. I'm set up for 個人事業主 filing 確定申告. You need a 税理士 who handles 法人税." |
| 531 | - **R-JP-2 -- Agriculture (農業所得).** "農業所得 has its own computation method and may involve 農業所得用 収支内訳書 with specific rules. Outside my current scope." |
| 532 | - **R-JP-3 -- Non-resident.** "Non-residents (非居住者) are taxed only on Japan-source income with different rates and withholding rules (所得税法第164条). I'm set up for full-year Japan residents only." |
| 533 | - **R-JP-4 -- Estate / inheritance.** "相続税 (inheritance tax) and 贈与税 (gift tax) are separate tax systems with their own returns. Not in scope." |
| 534 | - **R-JP-5 -- Real estate capital gains.** "不動産の譲渡所得 (capital gains from property sale) requires 分離課税 (separate taxation) with complex holding-period rules. Flag for 税理士." |
| 535 | - **R-JP-6 -- Foreign tax credits (外国税額控除) involving complex treaty application.** "Simple foreign tax credits can be handled, but complex multi-country treaty situations need a 税理士 specializing in international tax." |
| 536 | |
| 537 | When a refusal fires: |
| 538 | 1. Stop the workflow |
| 539 | 2. State the specific reason in one sentence |
| 540 | 3. Recommend the path forward (specific practitioner type) |
| 541 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 542 | |
| 543 | **Do not:** |
| 544 | - Apologize profusely |
| 545 | - Try to work around the refusal |
| 546 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 547 | - Continue silently |
| 548 | |
| 549 | --- |
| 550 | |
| 551 | ## Section 10 -- Self-checks |
| 552 | |
| 553 | **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. |
| 554 | |
| 555 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 556 | |
| 557 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 558 | |
| 559 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 560 | |
| 561 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "did you pay 国民年金" after the bank statement showed pension debits, check fails. |
| 562 | |
| 563 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 564 | |
| 565 | **Check IN7 -- Handoff to `jp-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. |
| 566 | |
| 567 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned 税理士 signoff. |
| 568 | |
| 569 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 570 | |
| 571 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 572 | |
| 573 | **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. |
| 574 | |
| 575 | **Check IN12 -- Blue/white return status was established.** 青色 vs 白色 was confirmed before inference, as it changes deduction levels and bookkeeping expectations. |
| 576 | |
| 577 | **Check IN13 -- Consumption tax method was determined.** 本則課税 vs 簡易課税 vs 2割特例 vs exempt was confirmed or flagged for computation comparison. |
| 578 | |
| 579 | --- |
| 580 | |
| 581 | ## Section 11 -- Performance targets |
| 582 | |
| 583 | For a prepared user (documents in a folder, ready to upload): |
| 584 | - **Refusal sweep**: 60 seconds (1-2 interactive turns) |
| 585 | - **Document upload**: 2 minutes (1 upload turn) |
| 586 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 587 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 588 | - **Handoff**: immediate |
| 589 | - **Total**: ~7 minutes |
| 590 | |
| 591 | For an unprepared user (has to go fetch documents): |
| 592 | - Refusal sweep: same |
| 593 | - Document discovery: 10-20 minutes offline |
| 594 | - Rest: same |
| 595 | - **Total**: 15-25 minutes |
| 596 | |
| 597 | --- |
| 598 | |
| 599 | ## Section 12 -- Cross-skill references |
| 600 | |
| 601 | **Inputs:** User-provided documents and answers. |
| 602 | |
| 603 | **Outputs:** Structured intake package consumed by `jp-return-assembly`. |
| 604 | |
| 605 | **Downstream skills triggered (via jp-return-assembly):** |
| 606 | - `japan-consumption-tax` -- 消費税確定申告書 (consumption tax return) |
| 607 | - `japan-income-tax` -- 所得税確定申告書 with 青色申告決算書 or 収支内訳書 |
| 608 | - `japan-social-insurance` -- 社会保険料 reconciliation (国民健康保険, 国民年金, 小規模企業共済) |
| 609 | - `jp-estimated-tax` -- 予定納税 and estimated payments schedule |
| 610 | |
| 611 | --- |
| 612 | |
| 613 | ### Change log |
| 614 | |
| 615 | - **v1.0 (May 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on mt-freelance-intake v0.1. |
| 616 | |
| 617 | ## End of Intake Skill v1.0 |
| 618 | |
| 619 | |
| 620 | --- |
| 621 | |
| 622 | ## Disclaimer |
| 623 | |
| 624 | 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. |
| 625 | |
| 626 | 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. |
| 627 |
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 Japanese tax returns AND mentions freelancing, self-employment, 個人事業主, フリーランス, sole proprietorship, or kojin jigyounushi. Trigger on phrases like "確定申告を手伝って", "help me file my kakutei shinkoku", "I'm a freelancer in Japan", "prepare my blue return", "I'm self-employed in Japan", or any similar phrasing where the user is a Japan-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Japanese self-employed tax workflow -- every other skill in the stack (japan-consumption-tax, japan-income-tax, japan-social-insurance, jp-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. Japan full-year residents only; self-employed individuals and sole proprietors (個人事業主).
JPty-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.