clams

スキルディレクトリ

このスキル内のすべての scripts/ パスは、この SKILL.md ファイルがあるディレクトリを基準とします。スクリプトを実行する前に、まずこのスキルのディレクトリの絶対パスを特定してください。たとえば、このファイルが ~/.claude/skills/clams/SKILL.md にある場合、スクリプトは ~/.claude/skills/clams/scripts/ にあります。

ルール

1. セッション中に初めて clams コマンドを実行する前に、PATH が設定されていることを確認するため、ユーザーのシェルプロファイルを読み込んでください：source ~/.zshenv 2>/dev/null; source ~/.bashrc 2>/dev/null。セッションごとに一度だけ必要です。
2. コマンドを実行する前に、必ず関連するリファレンスファイルを読んでください。 フラグや構文を推測せず、まずリファレンスを確認してください。
3. 出力を解析したり、スクリプトに渡したりする必要があるコマンドでは、--machine --format json を使用してください。
4. ユーザーがレポート出力をターミナルで見たい場合は、--format plain を使用してください。CLI の出力を直接表示し、再フォーマットしないでください。
5. 処理順序：sync → clams rates sync → clams journals process → レポート
6. レポートのデフォルト形式：表示用レポート（貸借対照表、残高履歴、ポートフォリオ概要）には --format plain を、データレポート（譲渡益、仕訳）には --format csv --output <path> を使用してください。ユーザーが明示的に求めた場合に限り、PDF を生成してください。
7. PDF レポート（依頼された場合のみ）：JSON を <skill-dir>/scripts/render-<report>.sh --pdf <path> にパイプしてください。weasyprint が必要です。
8. CLI 出力の金額を絶対に要約したり、再フォーマットしたりしないでください。レンダリングスクリプト、--format plain、または --format csv を使い、CLI に書式設定させてください。
9. 金融関連の値を使った計算は絶対に行わないでください。CLI 出力から合計、減算、平均、または新しい数値の算出をしないでください。Clams 自身が計算して書式設定した値のみを表示してください。
10. clams reports export コマンドは存在しません。PDF と CSV は上記の方法で生成してください。
11. エラーが発生した場合：原因を診断する前に、エラー JSON の code フィールドと message フィールドを読んでください。原因を推測してはいけません。エラーの内容が明確でない場合は、より詳細な出力を得るために --debug を付けてコマンドを再実行してください。

注意点

• レポートが空ですか？ clams journals process を忘れています。すべての同期／インポート後、レポートを作成する前に実行する必要があります。これが最もよくある間違いです。
• 金額の単位はミリサトシです。 生の JSON の金額を変換、丸め、要約、表示しないでください。必ずレンダリングスクリプトを経由するか、--format csv を使用してください。
• clams reports export は存在しません。 PDF の場合は、JSON を <skill-dir>/scripts/render-*.sh にパイプで渡してください。CSV の場合は、レポートコマンドで --format csv --output <path> を使用してください。
• clams init は対話形式でのみ実行できます。 --machine モードには対応していません。代わりに onboarding.md に記載された個別のコマンドを使用してください。
• clams setup はサーバー管理者向けです。 CLI ワークフローでは使用しないでください。これはクライアントではなく、Clams サーバーを設定します。
• オンチェーンウォレットには、先にオンチェーンソースが必要です。 XPub、Descriptor、Address の接続は、オンチェーンソースがないと同期に失敗します。オンボーディングの手順 7 で作成してください。これらの接続を作成する際は、オンチェーンソースとネットワークを自動解決してください。connections.md の「Resolving Onchain Source and Network」を参照してください。本当に曖昧な場合を除き、ユーザーに尋ねないでください。
• メタデータを変更した後は、再処理してください。 メモ、タグ、除外設定、レートの上書き、アカウントの調整は、clams journals process を再度実行するまで反映されません。
• --excluded を省略すると、除外が解除されます。 --excluded フラグなしで clams metadata records excluded set --event-id <ID> を実行すると、そのイベントの除外が解除されます。これは意図された動作ですが、直感的ではありません。
• 隔離されたイベントがあると、正確なレポートを作成できません。 未解決の隔離イベントはレポートから除外されます。数値がおかしい場合は、必ず clams journals quarantined を確認してください。
• すべての JSON レスポンスは data エンベロープでラップされています。 形式は {"kind": "...", "schema_version": 1, "data": ...} です。実際のペイロードを取得するには、必ず .data にアクセスしてください。リストは .data（配列）または .data.items（ページネーションあり）に含まれる場合があります。
• --machine には --format json が必要です。 --machine を --format csv や --format plain と組み合わせないでください。エラーになります。スクリプトでは --machine --format json を使用するか、--machine を省略して --format plain／--format csv を直接使用してください。
• すべてのレポートが CSV に対応しているわけではありません。 CSV 出力に対応しているのは、キャピタルゲインと仕訳エントリのみです。貸借対照表とポートフォリオ概要は、プレーンテキストと PDF のみ対応しています。reports.md の形式対応表を参照してください。
• CLI を短時間に何度も呼び出すと、レート制限が発生します。 短時間に多数のリクエストを行うと（例：イベントのページネーション）、バックエンドが空のレスポンスを返すことがあります。認証エラーのように見えますが、一時的なものです。ページネーションでは、ページ間に 0.5 秒の遅延を入れ、空のレスポンスが返った場合は再試行してください（最大 3 回、バックオフは 2 秒）。journal-processing.md のページネーションのセクションを参照してください。
• イベント数は多くなることがあります。 Lightning 接続では、数万件のイベントが発生する場合があります。最初のページだけで終わりだと決めつけず、JSON レスポンスの next_cursor を必ず確認してください。件数を尋ねられ、最初のページに 500 件すべてが返された場合は、ほぼ確実に続きのページがあります。

データ階層

workspace → profile → connections → journals → reports
                    → onchain sources (for on-chain wallets)
                    → metadata (notes, tags, exclusions)

レポートの選択

ユーザーの質問内容	レポート
取得原価、純資産、未実現損益、ポートフォリオ価値、平均取得価格	ポートフォリオ概要
実現損益、税務報告、処分、キャピタルゲイン	キャピタルゲイン
アカウント／接続ごとの現在残高、資産と負債	貸借対照表
残高の推移、残高の傾向	残高履歴
生の取引データ、台帳のエクスポート	仕訳エントリ

ワークフローの振り分け

ユーザーの目的	参照先
ログイン、ワークスペース／プロフィールの作成、設定の変更、オンチェーンソースのセットアップ	onboarding.md
ウォレットの追加、接続の一覧表示／更新／削除、同期、CSV／JSON のインポート	connections.md
オンチェーンソース（Esplora、Electrum、Bitcoin RPC）と Tor プロキシの管理	onchain.md
カスタムマッピング（csv_mapping）を使った取引所の CSV インポート、カスタム接続	custom-connections.md
txid またはイベント ID で特定のトランザクションを検索／確認	journal-processing.md
ジャーナルの処理、隔離項目の確認、隔離されたイベントの解決	journal-processing.md
メモ、タグ、除外、レートの上書き、またはアカウント調整の追加	metadata.md
貸借対照表、残高履歴、ポートフォリオの概要、キャピタルゲイン、仕訳の生成	reports.md
CLI の準備状況の確認、ワークフローの前後の状態確認	verification.md
エラーまたは結果が空の場合の診断	troubleshooting.md

フォールバック

clams --help
clams <subcommand> --help