### Install and Upgrade Shinkoku CLI

Source: https://github.com/kazukinagata/shinkoku/blob/main/README.md

Use the uv package manager to install or upgrade the shinkoku command-line tool. This is typically handled automatically by setup skills but can be done manually.

```bash
# Install
uv tool install git+https://github.com/kazukinagata/shinkoku

# Update
uv tool upgrade shinkoku
```

--------------------------------

### Shinkoku Setup Completion Message

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/setup/SKILL.md

This message is displayed upon successful setup completion, indicating generated files and suggesting the next steps for the user.

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
セットアップ完了
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ 生成されたファイル:
  → shinkoku.config.yaml（設定ファイル）
  → {db_path}（データベース）

■ 次のステップ:
  1. /assess — 申告要否・種類の判定
  2. /gather — 必要書類の確認・収集
  3. /journal — 仕訳入力・帳簿管理
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

```

--------------------------------

### Install Dependencies

Source: https://github.com/kazukinagata/shinkoku/blob/main/docs/plans/2026-02-07-shinkoku-implementation-plan.md

Command to install project dependencies using uv, including optional extras.

```bash
uv sync --all-extras

```

--------------------------------

### Verify and Install shinkoku CLI

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/setup/SKILL.md

Commands to check for the existence of the shinkoku CLI and either install or upgrade it using uv.

```bash
shinkoku --version
```

```bash
uv tool install git+https://github.com/kazukinagata/shinkoku
```

```bash
uv tool upgrade shinkoku
```

--------------------------------

### Setup Progress File Output

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/setup/SKILL.md

This Markdown file is generated to record the setup step's completion. It includes details about the tax year, database path, output directory, and invoice registration number. It also captures taxpayer information, business details, and document locations. Unset items are marked as '未設定'.

```markdown
---
step: 1
skill: setup
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# セットアップ結果

## 設定内容

- 対象年度: {tax_year}
- データベースパス: {db_path}
- 出力ディレクトリ: {output_dir}
- インボイス登録番号: {invoice_registration_number}

## 納税者情報

- 氏名: {last_name} {first_name}
- 生年月日: {date_of_birth}
- マイナンバー: {登録済み/未登録}
- 寡婦/ひとり親: {widow_status}
- 障害者区分: {disability_status}
- 勤労学生: {working_student}
- 世帯主との続柄: {relationship_to_head}

## 住所

- 自宅: {postal_code} {prefecture}{city}{street}{building}
- 1/1時点の住所: {jan1_address}（同上/異なる住所）
- 事業所住所: {設定あり/自宅と同じ}

## 事業情報

- 屋号: {trade_name}
- 業種: {industry_type}
- 事業内容: {business_description}

## 申告方法

- 提出方法: {submission_method}
- 申告の種類: {return_type}
- 青色申告特別控除: {blue_return_deduction}円
- 所轄税務署: {tax_office_name}

## 控除・申告に影響する重要事項

- 配偶者: {あり（概算所得: ○万円）/ なし}
- 扶養親族: {あり（○人、うち16歳未満○人）/ なし}
- 住宅ローン控除: {適用あり（初年度/2年目以降）/ 適用なし}
- 予定納税: {あり（合計○円）/ なし}
- 世帯主: {本人 / ○○（氏名）}

## 書類ディレクトリ

- 請求書: {invoices_dir}
- 源泉徴収票: {withholding_slips_dir}
- レシート: {receipts_dir}
- 銀行明細: {bank_statements_dir}
- クレカ明細: {credit_card_statements_dir}
- 控除関連: {deductions_dir}
- 過去の申告: {past_returns_dir}

## DB初期化

- 初期化結果: 成功
- 勘定科目マスタ: 登録済み

## 次のステップ

/assess で申告要否・種類を判定する

```

--------------------------------

### Initialize Shinkoku CLI

Source: https://context7.com/kazukinagata/shinkoku/llms.txt

Install the tool and initialize the SQLite database for a specific fiscal year.

```bash
# インストール
uv tool install git+https://github.com/kazukinagata/shinkoku

# バージョン確認
shinkoku --version
# 出力: shinkoku 0.6.5

# データベース初期化
shinkoku ledger init \
  --db-path ./shinkoku.db \
  --fiscal-year 2025
# 出力:
# {"status": "ok", "message": "DB initialized for fiscal year 2025", "db_path": "./shinkoku.db"}
```

--------------------------------

### Set up Development Environment

Source: https://github.com/kazukinagata/shinkoku/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the project directory, and install dependencies using uv. Configure pre-commit hooks for automated checks.

```bash
git clone https://github.com/kazukinagata/shinkoku.git
cd shinkoku
uv sync --all-extras
uv run pre-commit install
```

--------------------------------

### Install Shinkoku Skill for AI Agents

Source: https://github.com/kazukinagata/shinkoku/blob/main/README.md

Install the Shinkoku skill package using the skills CLI. This allows compatibility with over 40 AI coding agents that support the SKILL.md open standard.

```bash
# Install interactively
npx skills add kazukinagata/shinkoku

# Install globally for specific agents
npx skills add kazukinagata/shinkoku -g -a claude-code -a cursor

# List available skills
npx skills add kazukinagata/shinkoku --list
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/kazukinagata/shinkoku/blob/main/CLAUDE.md

Common CLI commands for ledger management, tax calculation, data import, and utility functions.

```bash
# 帳簿 CRUD
uv run shinkoku ledger init --db-path shinkoku.db --fiscal-year 2025
uv run shinkoku ledger journal-add --db-path shinkoku.db --input journal.json
uv run shinkoku ledger trial-balance --db-path shinkoku.db --fiscal-year 2025

# 税額計算
uv run shinkoku tax calc-income --input income_params.json

# データ取込
uv run shinkoku import csv --file-path transactions.csv

# ふるさと納税
uv run shinkoku furusato summary --db-path shinkoku.db --fiscal-year 2025

# PDF ユーティリティ
uv run shinkoku pdf extract-text --file-path document.pdf
uv run shinkoku pdf to-image --file-path document.pdf --output-dir output/images

# プロファイル
uv run shinkoku profile --config shinkoku.config.yaml
```

--------------------------------

### Project Initialization Commit

Source: https://github.com/kazukinagata/shinkoku/blob/main/docs/plans/2026-02-07-shinkoku-implementation-plan.md

Git commit message for the initial project setup, including structure and dependencies.

```git
git add pyproject.toml .claude-plugin/ .mcp.json .gitignore src/ tests/
git commit -m "feat: initialize project structure and dependencies"

```

--------------------------------

### Update Progress Summary

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/furusato/SKILL.md

Example of updating the overall progress summary file. This file tracks the status of all completed steps in the Shinkoku process.

```yaml
fiscal_year: {tax_year}
last_updated: "{当日日付}"
current_step: furusato

```

--------------------------------

### Initialize Shinkoku Project

Source: https://github.com/kazukinagata/shinkoku/blob/main/README.md

Prepare your project directory for Shinkoku by initializing it. This includes setting up configuration files and initializing the database.

```bash
# Create and navigate to a working directory
mkdir ~/kakuteishinkoku && cd ~/kakuteishinkoku

# Initialize git repository (recommended)
git init

# Run setup command
/setup
```

--------------------------------

### Preview Configuration and Save

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/setup/SKILL.md

This step involves previewing the collected settings in YAML format and saving them to `shinkoku.config.yaml` in the current working directory after user confirmation.

```text
shinkoku.config.yaml
```

--------------------------------

### Install Playwright CLI for Browser Automation

Source: https://github.com/kazukinagata/shinkoku/blob/main/README.md

Install the Playwright CLI globally and its associated skills. This is required for browser automation if not using Claude in Chrome or Antigravity Browser Sub-Agent.

```bash
# Install package
npm install -g @playwright/cli@latest

# Install skills
playwright-cli install --skills

# Install Chromium browser
npx playwright install chromium
```

--------------------------------

### Add and Install Shinkoku Claude Code Plugin

Source: https://github.com/kazukinagata/shinkoku/blob/main/README.md

To use Shinkoku with its full features, including OCR, add the marketplace and then install the plugin within your Claude Code environment.

```bash
# Add marketplace
/plugin marketplace add kazukinagata/shinkoku

# Install plugin
/plugin install shinkoku@shinkoku
```

--------------------------------

### Initialize Shinkoku Database

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/setup/SKILL.md

Initializes the Shinkoku database using the `ledger.py init` command. It requires the database path and the fiscal year as arguments.

```bash
shinkoku ledger init --db-path DB --fiscal-year YEAR
```

--------------------------------

### Antigravity Browser Sub-Agent Operation Examples

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/e-tax/SKILL.md

Examples of high-level task descriptions for Antigravity's `browser_subagent` to interact with the tax return portal. These commands are delegated to the `browser_subagent` for execution.

```plaintext
- 「https://www.keisan.nta.go.jp/kyoutu/ky/sm/top_web#bsctrl を開く」
- 「『マイナンバーカードをお持ちですか』で『はい』のラジオボタンをクリック」
- 「name='sonekiKeisansyoFromMonth' の入力欄に '1' を入力」
```

--------------------------------

### Simplified Qualified Invoice Example

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/invoice-system/references/btoc-and-pricing-strategy.md

An example of a simplified qualified invoice suitable for BtoC businesses, demonstrating the required fields and format, including handling of different tax rates and reduced tax rates.

```text
━━━━━━━━━━━━━━━━━━
○○ Cafe
T1234567890123
━━━━━━━━━━━━━━━━━━
November 15, 2025

Coffee (※)     ¥440
Sandwich (※)  ¥550
Cake Set       ¥660

8%対象 (※)  ¥990  内消費税 ¥73
10%対象      ¥660  内消費税 ¥60
━━━━━━━━━━━━━━━━━━
Total         ¥1,650
Received     ¥2,000
Change       ¥350
※ applies to reduced tax rate (8%)
━━━━━━━━━━━━━━━━━━
```

--------------------------------

### Initialize MCP Server

Source: https://github.com/kazukinagata/shinkoku/blob/main/docs/plans/2026-02-07-shinkoku-implementation-plan.md

Entry point for the MCP server using FastMCP.

```python
from mcp.server.fastmcp import FastMCP
from shinkoku.tools import ledger, import_data, tax_calc, document

mcp = FastMCP("shinkoku", json_response=True)

def register_tools():
    ledger.register(mcp)
    import_data.register(mcp)
    tax_calc.register(mcp)
    document.register(mcp)

def main():
    register_tools()
    mcp.run()
```

--------------------------------

### Initialize Shinkoku Database

Source: https://context7.com/kazukinagata/shinkoku/llms.txt

Initializes the Shinkoku database for a specific fiscal year. This is typically the first step in setting up a new fiscal year.

```bash
shinkoku ledger init --db-path ./shinkoku.db --fiscal-year 2025
```

--------------------------------

### GET /ledger/trial-balance

Source: https://context7.com/kazukinagata/shinkoku/llms.txt

Generates a trial balance report for the fiscal year.

```APIDOC
## GET /ledger/trial-balance

### Description
Outputs the trial balance including debit/credit totals and balances for each account.

### Method
GET

### Endpoint
shinkoku ledger trial-balance

### Parameters
#### Query Parameters
- **db-path** (string) - Required - Path to the database.
- **fiscal-year** (integer) - Required - Fiscal year.
- **format** (string) - Optional - Output format (e.g., 'csv').

### Response
#### Success Response (200)
- **status** (string) - Status of the operation.
- **accounts** (array) - List of account balances.
```

--------------------------------

### GET /ledger/search

Source: https://context7.com/kazukinagata/shinkoku/llms.txt

Searches for journal entries based on specific criteria.

```APIDOC
## GET /ledger/search

### Description
Searches registered journal entries by date range, account code, or description keywords.

### Method
GET

### Endpoint
shinkoku ledger search

### Parameters
#### Query Parameters
- **db-path** (string) - Required - Path to the database.
- **input** (string) - Required - Path to the JSON file containing search parameters.
- **format** (string) - Optional - Output format (e.g., 'csv').

### Response
#### Success Response (200)
- **status** (string) - Status of the operation.
- **journals** (array) - List of matching journal entries.
```

--------------------------------

### Deductions Input JSON Structure

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/income-tax/SKILL.md

Example input JSON for the calc-deductions command.

```json
{
  "total_income": 5000000,
  "social_insurance": 700000,
  "life_insurance_premium": 80000,
  "earthquake_insurance_premium": 30000,
  "medical_expenses": 200000,
  "furusato_nozei": 50000,
  "housing_loan_balance": 0,
  "spouse_income": null,
  "ideco_contribution": 276000,
  "dependents": [],
  "fiscal_year": 2025,
  "housing_loan_detail": null,
  "donations": null
}
```

--------------------------------

### Initialize Database Connection

Source: https://github.com/kazukinagata/shinkoku/blob/main/docs/plans/2026-02-07-shinkoku-implementation-plan.md

Sets up a SQLite connection with WAL mode and foreign key support enabled.

```python
import sqlite3
from pathlib import Path

SCHEMA_PATH = Path(__file__).parent / "schema.sql"

def get_connection(db_path: str) -> sqlite3.Connection:
    conn = sqlite3.connect(db_path)
    conn.execute("PRAGMA journal_mode=WAL")
    conn.execute("PRAGMA foreign_keys=ON")
    conn.row_factory = sqlite3.Row
    return conn

def migrate(conn: sqlite3.Connection) -> int:
    # schema_version テーブルの存在確認 → なければ初期スキーマ適用
    ...

def init_db(db_path: str) -> sqlite3.Connection:
    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
    conn = get_connection(db_path)
    migrate(conn)
    return conn
```

--------------------------------

### Sanity Check Input JSON Structure

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/income-tax/SKILL.md

Example input JSON for the sanity-check command.

```json
{
  "input": { ... },
  "result": { ... }
}
```

--------------------------------

### Income Tax Input JSON Structure

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/income-tax/SKILL.md

Example input JSON for the calc-income command.

```json
{
  "fiscal_year": 2025,
  "salary_income": 5000000,
  "business_revenue": 3000000,
  "business_expenses": 1000000,
  "blue_return_deduction": 650000,
  "social_insurance": 700000,
  "life_insurance_premium": 80000,
  "earthquake_insurance_premium": 30000,
  "medical_expenses": 0,
  "furusato_nozei": 50000,
  "housing_loan_balance": 0,
  "spouse_income": null,
  "ideco_contribution": 276000,
  "withheld_tax": 100000,
  "business_withheld_tax": 30000,
  "estimated_tax_payment": 0,
  "loss_carryforward_amount": 0
}
```

--------------------------------

### In-Person Submission Guide

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/submit/SKILL.md

Details the benefits, requirements, and steps for submitting at a tax office.

```text
メリット:
  - その場で受付印をもらえる
  - 不備があればその場で指摘される

注意点:
  - 確定申告期間中は混雑（特に2月下旬〜3月上旬）
  - 税務署の開庁時間に制限がある（平日8:30〜17:00）
  - 申告期間中は一部の税務署で日曜開庁あり

手順:
  1. 申告書を印刷
  2. 添付書類を準備
  3. 控え（コピー）を持参
  4. 所轄税務署の窓口に提出
  5. 控えに受付印をもらう
```

--------------------------------

### shinkoku CLIによるローン情報登録

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/tax-housing-loan-context/references/housing-loan.md

購入分およびリフォーム分の住宅ローン情報をCLI経由でデータベースに登録する手順。

```bash
# 購入分登録
uv run shinkoku ledger hl-add --db-path shinkoku.db --fiscal-year 2025 \
  --input purchase.json

# purchase.json:
# {
#   "housing_type": "used",
#   "housing_category": "general",
#   "move_in_date": "2025-04-01",
#   "year_end_balance": 15151931,
#   "is_new_construction": false,
#   "dual_application_group": "loan-01",
#   "cost_for_proration": 42800000
# }

# リフォーム分登録
uv run shinkoku ledger hl-add --db-path shinkoku.db --fiscal-year 2025 \
  --input renovation.json

# renovation.json:
# {
#   "housing_type": "renovation",
#   "housing_category": "general",
#   "move_in_date": "2025-04-01",
#   "year_end_balance": 15151931,
#   "is_new_construction": false,
#   "dual_application_group": "loan-01",
#   "cost_for_proration": 5000000
# }
```

--------------------------------

### e-Tax Submission Guide

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/submit/SKILL.md

Details the benefits, requirements, and steps for submitting via e-Tax.

```text
メリット:
  - 24時間提出可能（提出期間中）
  - 添付書類の提出省略が可能（5年間保存義務あり）
  - 青色申告特別控除65万円の要件を満たせる
  - 還付金の処理が早い（通常3週間程度、書面は1〜2か月）
  - 自宅から完結

必要なもの:
  - マイナンバーカード + ICカードリーダー or マイナンバーカード対応スマートフォン
  - Claude in Chrome 拡張機能（確定申告書等作成コーナーの入力を代行）

手順:
  1. Chrome で確定申告書等作成コーナーにアクセス
     （https://www.keisan.nta.go.jp/）
  2. Claude in Chrome の /e-tax スキルで入力を代行
     - shinkoku の税計算結果を基に各画面のフォームに自動入力
     - 画面遷移・入力値はユーザーが目視確認
  3. マイナンバーカードでログイン・電子署名（手動操作）
  4. 送信前に内容を最終確認
  5. 電子署名を付与して送信
  6. 受付番号を控える（送信後に表示）
  7. 受信通知を確認（メッセージボックスに届く）
```

--------------------------------

### Initialize Ledger

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/journal/SKILL.md

Initializes the bookkeeping database for a specific fiscal year.

```bash
shinkoku ledger init \
  --db-path /path/to/shinkoku.db \
  --fiscal-year 2025
```

--------------------------------

### Database Initialization and Connection (db.py)

Source: https://github.com/kazukinagata/shinkoku/blob/main/docs/plans/2026-02-07-shinkoku-implementation-plan.md

Provides functions for initializing the SQLite database, establishing connections, and managing schema migrations.

```python
import sqlite3
from pathlib import Path

DB_SCHEMA_FILE = "schema.sql"

def init_db(db_path: str | Path) -> sqlite3.Connection:
    """Initializes the database if it doesn't exist and applies the schema."""
    db_path = Path(db_path)
    db_path.parent.mkdir(parents=True, exist_ok=True)

    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()

    # Check if schema needs to be applied
    cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'")
    if cursor.fetchone() is None:
        print(f"Applying schema to {db_path}...")
        with open(DB_SCHEMA_FILE, 'r') as f:
            schema_sql = f.read()
        cursor.executescript(schema_sql)
        cursor.execute("INSERT INTO schema_version (version) VALUES (1)")
        conn.commit()
        print("Schema applied.")
    else:
        print("Database already initialized.")

    # Ensure foreign keys are enabled
    conn.execute("PRAGMA foreign_keys = ON")
    conn.commit()

    return conn

def get_connection(db_path: str | Path) -> sqlite3.Connection:
    """Gets a database connection, ensuring foreign keys are enabled."""
    conn = sqlite3.connect(db_path)
    conn.execute("PRAGMA foreign_keys = ON")
    conn.commit()
    return conn

def migrate(conn: sqlite3.Connection):
    """Placeholder for future database migrations."""
    # TODO: Implement migration logic
    pass


```

--------------------------------

### Mail Submission Guide

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/submit/SKILL.md

Details the benefits, requirements, and steps for submitting via postal mail.

```text
メリット:
  - 税務署に行く必要がない
  - 通信日付印が提出日になる（期限日の消印有効）

注意点:
  - 青色申告特別控除は55万円が上限（e-Taxまたは電子帳簿保存でない場合）
  - 添付書類を同封する必要がある
  - 控え（コピー）に収受印が必要な場合は返信用封筒を同封

手順:
  1. 申告書を印刷（A4白黒で可）
  2. 添付書類を台紙に貼付
  3. 確定申告書の控え（コピー）を作成
  4. 以下を封筒に同封:
     - 確定申告書（原本）
     - 添付書類（各種証明書等）
     - マイナンバーカードの写し（表裏）
     - 控えが必要な場合: 確定申告書の控え + 返信用封筒（切手貼付）
  5. 所轄税務署宛に郵送（「確定申告書在中」と記載）
  6. 簡易書留または特定記録郵便を推奨（発送の証拠を残すため）

宛先の確認:
  国税庁「税務署の所在地などを知りたい方」で所轄税務署を検索
```

--------------------------------

### Record import source

Source: https://github.com/kazukinagata/shinkoku/blob/main/skills/journal/SKILL.md

Log the import history after successful registration.

```bash
shinkoku import record-source \
  --db-path DB --file-path /path/to/file.csv --source-type csv
```