Journal Entry & Ledger Management

This skill imports data from CSV files, receipts, or invoices, and registers journal entries after user confirmation. It also supports ledger initialization, as well as searching, modifying, and deleting journal entries.

CLI Scripts

This skill uses the following CLI scripts:

Ledger Management:
```
shinkoku ledger <subcommand> [args]
```
Data Import:
```
shinkoku import <subcommand> [args]
```

All commands output JSON to stdout. Input can be passed via command-line arguments or the

--input <json_file>

option.

Loading Configuration (Execute First)

Load
```
shinkoku.config.yaml
```
using the Read tool
If the file does not exist, guide the user to run the
```
/setup
```
skill and exit
Understand the configuration values, and convert relative paths to absolute paths based on the CWD:
- ```
db_path
```
  : Used for the
```
--db-path
```
  argument of CLI scripts
- ```
output_dir
```
  : Base directory for outputting progress files, etc.
- Each directory: Used when referencing files

Path Resolution Example (db_path)

db_path

in the config is

./shinkoku.db

and the CWD is

/home/user/tax-2025/

, pass the absolute path

/home/user/tax-2025/shinkoku.db

via the

--db-path

option to the CLI script. Use the same absolute path for all commands:

init

journal-add

journal-batch-add

search

journal-update

journal-delete

Loading Progress Information

After loading the configuration, load handover files to understand the results of the previous step.

Load
```
.shinkoku/progress/progress-summary.md
```
using the Read tool (if it exists)
Load the following handover files using the Read tool (if they exist):
- ```
.shinkoku/progress/01-setup.md
```
Utilize the loaded information in subsequent steps (to avoid re-asking the user)
If the files do not exist, skip this step and directly confirm necessary information with the user

Basic Principles

The basic workflow consists of three steps: CSV import → user confirmation → journal entry registration
Account items comply with the master data in references/account-master.md
Always confirm the content with the user before registering journal entries (no automatic registration)
Accurately set the consumption tax classification (taxable / non-taxable / exempt / outside scope)
Verify the consistency of date, amount, and account items before calling the tool
When an error occurs, clearly communicate the error content in Japanese and propose correction methods

Checking Prerequisites

Before starting journal entry registration, confirm the following:

Is the ledger initialized?: If not initialized, guide the user to initialize it using the
```
init
```
command
Fiscal year: Confirm the target fiscal year (e.g., 2025)
Blue return or white return: The bookkeeping method varies depending on whether it's double-entry bookkeeping (¥650,000 blue return deduction) or simplified bookkeeping

Step 1: Initialize Ledger

Initialize the ledger during first-time use or when starting a new fiscal year.

init

Command

bash

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

Execute after confirming the fiscal year and storage path with the user
If an existing database exists, display an overwrite warning
After initialization, confirm that the account master data has been registered

Step 2: Import Data

Select the appropriate import tool based on the format of the user's transaction data.

2-1. CSV Import (

csv

Command)

Import credit card statements, bank transaction statements, export data from accounting software, etc.

bash

shinkoku import csv \
  --file-path /path/to/transactions.csv

Return Value (JSON):

```
headers
```
: List of detected column headers
```
rows
```
: Parsed data for each row
```
encoding
```
: Automatically detected encoding
```
row_count
```
: Number of rows

Post-Import Processing Steps:

Display a preview of the imported data (first 5-10 rows)
Identify the columns for date, amount, and description, and confirm with the user
Estimate the account item for each row and present candidates
Clearly state the basis for estimation (e.g., keyword matching in the description)
Convert to journal entry data after the user confirms or modifies the account items

Account Estimation Rules:

If the description contains "train", "bus", "taxi", or "JR" → Travel & Transportation Expenses (5130)
If the description contains "Amazon" or "Yodobashi" → Consumable Supplies Expense (5190) or Office Supplies Expense (5360)
If the description contains "Docomo", "au", or "SoftBank" → Communication Expenses (5140)
If the description contains "Tokyo Electric Power", "gas", or "water" → Utilities Expenses (5120)
If the description contains "rent" or "lease" → Rent & Land Lease Expenses (5250)
If estimation is not possible, mark as "Unknown" and present a list of candidates for the user to select

2-2. Receipt Import (

receipt

Command)

Extract data from image files of paper receipts or receipts using OCR.

bash

shinkoku import receipt \
  --file-path /path/to/receipt.jpg

Important: Image reading is delegated to the corresponding reading- skill.*

For a Single Receipt

Confirm the existence of the file using the
```
receipt
```
command
Use the
```
/reading-receipt
```
skill to read the image file. Follow the skill's instructions to perform dual verification (comparing results from two independent readings) and obtain the result.
Result Comparison: Compare
```
total_amount
```
,
```
date
```
, and
```
vendor
```
from both reading results
If results match: Adopt the result as-is. Report "Results matched in two independent readings"

If results do not match: Present the original image path and both results to the user, and ask them to select the correct one:
- Clearly indicate the fields with differences
- Present three options via AskUserQuestion: Adopt A / Adopt B / Manual Input
Analyze the content of the
```
---RECEIPT_DATA---
```
block in the reading result
Display the date, amount, and store name to the user to confirm correctness
Estimate the account item from the items
Confirm the need for household cost allocation (e.g., when using a home office)
Convert to journal entry data after confirmation

Bulk Processing of Multiple Receipts

Obtain a list of receipt images using the Glob tool (e.g.,
```
receipts/*.jpg
```
,
```
receipts/*.png
```
)
Confirm the existence of each file using the
```
receipt
```
command
Use the
```
/reading-receipt
```
skill to read the image files. Follow the skill's instructions to perform dual verification (comparing results from two independent readings) and obtain the results.
Result Comparison: Compare
```
total_amount
```
,
```
date
```
, and
```
vendor
```
from both reading results for each file
If results match: Adopt the result as-is. Report "Results matched in two independent readings"

If results do not match: For files with mismatches, present the original image path and both results to the user, and ask them to select the correct one:
- Clearly indicate the fields with differences
- Present three options via AskUserQuestion: Adopt A / Adopt B / Manual Input
Summarize the results of each receipt and present them to the user
Estimate the account item for each receipt and confirm with the user in a list
After confirmation, register in bulk using the
```
journal-batch-add
```
command

2-3. Invoice Import (

invoice

Command)

Extract text from PDF invoices.

bash

shinkoku import invoice \
  --file-path /path/to/invoice.pdf

Return Value (JSON):

```
vendor
```
: Billing party
```
date
```
: Billing date
```
due_date
```
: Payment due date
```
amount
```
: Billing amount
```
tax_amount
```
: Consumption tax amount
```
items
```
: Detail lines
```
raw_text
```
: Extracted raw text

For Image Files: OCR Reading

extracted_text

is empty (image file or scanned PDF), use the

/reading-invoice

skill to read the image. Follow the skill's instructions to perform dual verification (comparing results from two independent readings) and obtain the result.

Result Comparison: Compare

total_amount

tax_amount

date

, and

vendor

from both reading results

If results match: Adopt the result as-is. Report "Results matched in two independent readings"

If results do not match: Present the original image path and both results to the user, and ask them to select the correct one:

Clearly indicate the fields with differences
Present three options via AskUserQuestion: Adopt A / Adopt B / Manual Input

Post-Import Processing Steps:

Display the extraction result and confirm that the amount, date, and counterparty are correct
Confirm the presence of an invoice number (T+13 digits)
Confirm the consumption tax rate classification (10% / 8% reduced tax rate)
Confirm whether to record accounts payable on an accrual basis or process on a cash basis
Convert to journal entry data after confirmation

Step 2.5: Duplicate Check (During CSV Import)

Incorporate duplicate checking into the CSV import workflow:

File Duplicate Check: Confirm the file hash using the
```
check-imported
```
command
bash
```
shinkoku import check-imported \
  --db-path DB --file-path /path/to/file.csv
```
- If the file has already been imported, warn the user and confirm their intention to re-import
Automatic Check During Journal Entry Registration:
```
journal-batch-add
```
automatically detects duplicates
- exact (exact match): Block registration and display the existing journal entry ID
- similar (similar): Display a warning and ask the user for confirmation
- If the user answers "Register", re-execute with the
```
--force
```
  option

Import Record: After successful registration, record the import history using the

record-source

command

bash

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

Duplicate Check Before Filing

Before closing the books, execute the

check-duplicates

command to display a list of journal entry pairs suspected of being duplicates.

bash

shinkoku ledger check-duplicates \
  --db-path DB --fiscal-year 2025

After confirming with the user, delete unnecessary duplicates using the

journal-delete

command.

Step 3: Register Journal Entries

3-1. Register a Single Journal Entry (

journal-add

)

bash

# Describe the JournalEntry in journal.json
shinkoku ledger journal-add \
  --db-path DB --fiscal-year 2025 --input journal.json

Format of

journal.json

json

{
  "date": "2025-01-15",
  "description": "Description text",
  "lines": [
    {"side": "debit", "account_code": "5200", "amount": 1000},
    {"side": "credit", "account_code": "1100", "amount": 1000}
  ]
}

3-2. Bulk Register Journal Entries (

journal-batch-add

)

Use this when registering multiple journal entries at once, such as after CSV import.

bash

# Describe an array of JournalEntry in entries.json
shinkoku ledger journal-batch-add \
  --db-path DB --fiscal-year 2025 --input entries.json [--force]

Pre-Registration Checks:

Present a summary of the number of entries to be registered and the total amount
Confirm with the user: "Will you register the following N journal entries?"
Execute
```
journal-batch-add
```
only after obtaining explicit approval from the user

Validation Rules During Registration

Verify the following and warn the user before registration if there are any deficiencies:

Date validity: Whether the date is within the fiscal year range (e.g., 2025-01-01 to 2025-12-31)
Account existence: Whether the debit/credit account codes exist in the master data
Positive amount: Whether the amount is a positive integer
Debit-credit balance: For compound journal entries, whether total debit amount equals total credit amount
Consumption tax classification consistency: Whether the combination of the account's tax_category and tax rate is valid

Step 4: Search Journal Entries

Search for registered journal entries.

search

Command

bash

# Describe JournalSearchParams in search_params.json
shinkoku ledger search \
  --db-path DB --input search_params.json

Format of

search_params.json

json

{
  "fiscal_year": 2025,
  "date_from": "2025-01-01",
  "date_to": "2025-03-31",
  "account_code": "5200",
  "description_contains": "Amazon"
}

Displaying Search Results:

Display search results as a list sorted by date
Display the journal_id for each journal entry (used for modification/deletion)
Display the total amount at the end

Step 5: Modify or Delete Journal Entries

5-1. Modify Journal Entry (

journal-update

)

bash

shinkoku ledger journal-update \
  --db-path DB --fiscal-year 2025 --journal-id 42 --input updated.json

Display the differences before and after modification for confirmation
Recommend adding the modification reason to the description

5-2. Delete Journal Entry (

journal-delete

)

bash

shinkoku ledger journal-delete \
  --db-path DB --journal-id 42

Display the content of the journal entry to be deleted for confirmation
Final confirmation: "Will you delete this journal entry?"
Warn the user that deletion cannot be undone

Common Journal Entry Patterns

Recording Sales

Debit: Accounts Receivable (1010) / Credit: Sales (4001)  Amount: ¥110,000  Tax Rate: 10%
Description: Website production fee for XX Co., Ltd. Invoice No.2025-001

Paying Expenses (From Business Account)

Debit: Consumable Supplies Expense (5190) / Credit: Ordinary Deposit (1002)  Amount: ¥5,500  Tax Rate: 10%
Description: Amazon Wireless Keyboard

Paying Business Expenses From Personal Wallet

Debit: Travel & Transportation Expenses (5130) / Credit: Owner's Draw (3010)  Amount: ¥1,200  Tax Rate: 10%
Description: JR Shinjuku→Shibuya Round trip for meeting

Using Business Funds for Personal Use

Debit: Owner's Contribution (1200) / Credit: Ordinary Deposit (1002)  Amount: ¥50,000
Description: Withdrawal for living expenses

Guidance for Next Steps

After completing journal entry registration, guide the user to:

Perform closing adjustments and prepare financial statements using the
```
settlement
```
skill
Verify for missing journal entries by checking the trial balance using the
```
trial-balance
```
command:
bash
```
shinkoku ledger trial-balance \
  --db-path DB --fiscal-year 2025
```
Proceed to closing only after confirming that all transactions have been registered

Output Handover Documents

After presenting the summary, output the following files using the Write tool. This allows results to be carried over to the next step even if the session is interrupted or compacted.

Output Step-Specific Files

Output to

.shinkoku/progress/04-journal.md

in the following format:

---
step: 4
skill: journal
status: completed
completed_at: "{current date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# Results of Journal Entry & Ledger Management

## Imported Sources

| Source Name | Count | Import Date |
|---------|------|------------|
| {CSV name, receipt, etc.} | {count} | {date} |

## Registered Journal Entries

- Total number of journal entries: {count} entries

## Balance of Major Account Items (Trial Balance Snapshot)

| Account Item | Code | Balance |
|---------|--------|------|
| {account name} | {code} | ¥{balance} |
(Record major items such as sales, major expenses, cash & deposits, accounts receivable, accounts payable, etc.)

## Duplicate Check Results

- Check performed: {Completed/Not Performed}
- Suspected duplicates: {None/Yes (count)}

## Unprocessed Items

- {Record if any, otherwise "None"}

## Next Steps

Perform closing adjustments and prepare financial statements with /settlement

Update Progress Summary

Update

.shinkoku/progress/progress-summary.md

(create a new file if it does not exist):

YAML frontmatter: fiscal_year, last_updated (current date), current_step: journal
Table: Update the status of all steps (mark journal as completed)
Guidance for next steps

Post-Output Guidance

After outputting the files, inform the user:

"Handover documents have been saved to
```
.shinkoku/progress/
```
. Even if the session is interrupted, the results can be carried over to the next skill."
Guidance for next steps

journal

NPX Install

Tags

SKILL.md Content (Chinese)

Journal Entry & Ledger Management

CLI Scripts

Loading Configuration (Execute First)

Path Resolution Example (db_path)

Loading Progress Information

Basic Principles

Checking Prerequisites

Step 1: Initialize Ledger

init Command

Step 2: Import Data

2-1. CSV Import (csv Command)

2-2. Receipt Import (receipt Command)

For a Single Receipt

Bulk Processing of Multiple Receipts

2-3. Invoice Import (invoice Command)

For Image Files: OCR Reading

Step 2.5: Duplicate Check (During CSV Import)

Duplicate Check Before Filing

Step 3: Register Journal Entries

3-1. Register a Single Journal Entry (journal-add)

3-2. Bulk Register Journal Entries (journal-batch-add)

Validation Rules During Registration

Step 4: Search Journal Entries

search Command

Step 5: Modify or Delete Journal Entries

5-1. Modify Journal Entry (journal-update)

5-2. Delete Journal Entry (journal-delete)

Common Journal Entry Patterns

Recording Sales

Paying Expenses (From Business Account)

Paying Business Expenses From Personal Wallet

Using Business Funds for Personal Use

Guidance for Next Steps

Output Handover Documents

Output Step-Specific Files

Update Progress Summary

Post-Output Guidance

`init`
Command

2-1. CSV Import (
`csv`
Command)

2-2. Receipt Import (
`receipt`
Command)

2-3. Invoice Import (
`invoice`
Command)

3-1. Register a Single Journal Entry (
`journal-add`
)

3-2. Bulk Register Journal Entries (
`journal-batch-add`
)

`search`
Command

5-1. Modify Journal Entry (
`journal-update`
)

5-2. Delete Journal Entry (
`journal-delete`
)