clams

Skill Directory

All scripts/ paths in this skill are relative to the directory containing this SKILL.md file. Before running any script, resolve the absolute path to this skill's directory first. For example, if this file is at ~/.claude/skills/clams/SKILL.md, then scripts are at ~/.claude/skills/clams/scripts/.

Rules

1. Before running your first clams command in a session, source the user's shell profile to ensure PATH is set: source ~/.zshenv 2>/dev/null; source ~/.bashrc 2>/dev/null. Only needed once per session.
2. Always read the relevant reference file before running a command. Do not guess flags or syntax — check the reference first
3. Use --machine --format json for commands whose output you need to parse or pipe to a script
4. Use --format plain when the user wants to see report output in the terminal — display the CLI output directly, do not reformat it
5. Processing order: sync → clams rates sync → clams journals process → reports
6. Default report formats: use --format plain for display reports (balance sheet, balance history, portfolio summary) and --format csv --output <path> for data reports (capital gains, journal entries). Only generate PDF when the user explicitly asks for it.
7. For PDF reports (only when requested): pipe JSON through <skill-dir>/scripts/render-<report>.sh --pdf <path>. Requires weasyprint.
8. Never summarize or reformat amounts from CLI output — use render scripts, --format plain, or --format csv to let the CLI format them
9. Never perform arithmetic on financial values. Do not sum, subtract, average, or derive new numbers from CLI output — only display values that Clams itself has calculated and formatted
10. There is no clams reports export command — PDF and CSV are produced as described above
11. On errors: read the error JSON (code and message fields) before diagnosing — do not guess the cause. If the error isn't clear, retry the command with --debug for more detailed output

Gotchas