Ledger Transaction Entry

Convert natural-language spending/income statements into ledger JSONL records and append them into projects/data/YYYY/YYYY-MM.jsonl. Use when the user descri...

Security Scan

The skill's instructions and requirements are internally consistent with its stated purpose (parsing natural-language transactions and appending them to project ledger files); nothing requested is disproportionate or unrelated, but you should verify local scripts and backups before running writes.

Purpose & Capability

The name/description (convert NL transactions to ledger JSONL and append to projects/data/YYYY/YYYY-MM.jsonl) match the instructions: parse fields, consult projects/docs/CATEGORY_CATALOG.md, and run a local Python script to append to month files. No unrelated credentials, services, or external endpoints are requested.

Instruction Scope

Instructions direct the agent to read files under the repository (projects/docs/CATEGORY_CATALOG.md and projects/data/*), determine the correct month file, and run a local script (projects/scripts/add_ledger_entry.py) to append records. They also instruct generating charts into projects/reports and ensuring those outputs are git-ignored. This is consistent with the stated purpose, but the skill assumes the presence and correct behavior of the local python script and that the agent is allowed to modify .gitignore and write files. The SKILL.md also shows concrete shell commands (date and python3) but the required-binaries list is empty (minor inconsistency).

Install Mechanism

This is an instruction-only skill with no install spec and no downloads — lowest risk. It does assume python3 and standard shell utilities are available at runtime, but it does not install anything itself.

Credentials

No environment variables, credentials, or external tokens are requested. The only environment-related behavior is setting TZ='Asia/Taipei' when computing the date, which is appropriate for determining the target month file.

Persistence & Privilege

always is false and the skill does not request persistent platform privileges. It instructs writing to project files and .gitignore within the repository (expected for a write/ledger skill) but does not modify other skills or system-wide settings.

Assessment

This skill appears coherent for appending transactions to a project ledger, but before using it: 1) verify that projects/scripts/add_ledger_entry.py actually exists in your workspace and review its code to confirm it performs only the expected append and timestamp actions; 2) make a backup copy of relevant month files (projects/data/YYYY/YYYY-MM.jsonl) before allowing writes; 3) confirm you want the agent to be allowed to modify .gitignore and write files under projects/reports; 4) ensure python3 is available in the runtime environment (SKILL.md assumes python3 but the skill metadata doesn't declare it). If any of those checks fail or the script is missing, the skill should not be allowed to run writes until resolved.

Use this skill to append new transactions into projects/data.

Required output target

• Data root: projects/data
• File rule: YYYY/YYYY-MM.jsonl
• New record must be appended to the end of the month file.

Parse rules

From user text, extract:

• direction: 支出 or 收入
• amount: number
• currency: default CNY if omitted
• date: default today (Asia/Taipei) if omitted
• description: short clean text
• tag: 单个分类标签（只能选一个）

Optional fields (only if provided clearly):

• id
• major_category
• type

If amount or direction is ambiguous, ask one short clarification question before writing.

Write command

IMPORTANT: Get today's date (YYYY-MM-DD) for determining which month file to write to.

# Get today's date in Asia/Taipei timezone
CURRENT_DATE=$(TZ='Asia/Taipei' date +%Y-%m-%d)

The script will automatically add created_at field with current timestamp (YYYY-MM-DD HH:MM:SS) to each record.

Then run:

python3 projects/scripts/add_ledger_entry.py \
  --data-root projects/data \
  --date "$CURRENT_DATE" \
  --direction <支出|收入> \
  --amount <number> \
  --currency <CNY|USD|JPY|...> \
  --description <text> \
  --tag <tag>

Add optional args only when available:

• --id
• --major-category
• --type
• --source manual
• --batch manual

Category catalog (must check before writing)

Before each write, check:

• projects/docs/CATEGORY_CATALOG.md

Selection policy:

• Prefer existing values from catalog (tag/major_category/type/currency).
• If user gives a new tag not in catalog and meaning is clear, write it; otherwise ask one short confirmation.
• 只能选一个分类，不要给多个。

Existing common tags (只选一个)

当用户没有指定分类时，根据意图选择最合适的一个：

• 吃喝：外卖 / 下馆子 / 饮料零食 / 买菜做饭
• 出行：打车 / 交通卡 / 火车 / 飞机 / 大巴
• 居家：生活好物 / 居家杂物 / 房租住宿
• 订阅与网络：通讯网络 / 服务器 / 域名
• 投资与收入：A股 / 美股 / 港股 / 项目营收 / 二手

When uncertain, leave tags empty instead of guessing aggressively.

Response after write

Confirm with:

• month file path
• appended summary (date, direction, amount, description)

Monthly summary + chart workflow

Use this when user asks things like:

• 统计已知月份的总金额
• 生成图表发我
• 图表都 ignore，发完可以删

Required behavior:

1. Read all month files under projects/data/YYYY/YYYY-MM.jsonl.
2. Aggregate by month:
   • total amount (absolute sum)
   • expense sum (direction=支出)
   • income sum (direction=收入)
   • net (income-expense)
3. Generate chart into projects/reports/ (PNG preferred).
4. Ensure generated charts are git-ignored (keep/report patterns in .gitignore).
5. Send chart to user.
6. If user asks to delete after sending, delete local generated chart files.

Important note in reply:

• If source data includes multiple currencies, state that monthly totals are mixed-currency trend values unless converted to one base currency.