台帳の隣に SKILL.md ファイルを置くと、bea ask はあなた自身の簿記規則に従います — カテゴリ名、レポートのレイアウト、自宅でのルールなど — 毎回の質問でそれらを繰り返す必要はありません。
スキルは、小さな YAML ヘッダーを持つプレーンな Markdown です。bea ask は起動時にそれを検出し、ホスト型アシスタントに提供します。アシスタントは、質問がそれを必要とするときに全文を読み込みます。
このページは、bea ask がすでに動作していることを前提としています。ask エクストラ（uv tool install 'beancount-io[ask]'）と、bea cloud login または BEA_TOKEN からの Beancount.io 認証情報が必要です。クエリはローカルの台帳に対して実行されますが、質問とスキルコンテキストはホスト型の Beancount.io AI サービスに送信されます。bea ask には JSON 出力はありません。完全なコマンド契約については、CLI リファレンス を参照してください。
スキルの配置場所
bea ask は次の 2 つのディレクトリをこの順序で読み取ります：
| 場所 | スコープ |
|---|---|
<ledger-dir>/.agents/skills/ | プロジェクトレベル — 1 つの台帳に対応し、通常はそのリポジトリにチェックインされます |
~/.config/bea/skills/ | ユーザーレベル — このマシンで開くすべての台帳 |
プロジェクトディレクトリは、--file ではなく、bea ask を実行する作業ディレクトリから解決されます。両方のディレクトリに同じ name を持つスキルがある場合、プロジェクトのコピーが優先され、ユーザーのコピーは無視されます。
BEA_CONFIG_DIR はユーザーレベルのディレクトリを再配置します：これを設定すると、スキルは $BEA_CONFIG_DIR/skills/ から読み取られます。それ以外の場合は $XDG_CONFIG_HOME/bea/skills/ が適用され、~/.config/bea/skills/ にフォールバックします。
スキルファイルを書く
スキルごとに 1 つのディレクトリを作成し、SKILL.md という名前のファイルを 1 つ置きます：
.agents/skills/
└── monthly-report/
└── SKILL.mdファイルは YAML ヘッダーとそれに続く指示で構成されます：
---
name: monthly-report
description: Generates monthly expense summaries grouped by category.
---
When the user asks for a spending summary or monthly report:
1. Group all expenses by the top-level account category.
2. Show totals for each category, sorted highest to lowest.
3. Include a grand total at the end.
4. Always specify the currency next to each amount.必須フィールドは 2 つです。どちらかが欠けているファイルは静かにスキップされるため、スキルが存在しない場合は通常ヘッダーの問題です。
| フィールド | 必須 | 機能 |
|---|---|---|
name | はい | 小文字とハイフン。ディレクトリ名と一致させてください — 2 つの場所間の優先順位はこの値で照合されるため、不一致があるとオーバーライドが予測しにくくなります。 |
description | はい | アシスタントにスキルをいつ適用するかを伝える 1 行。これは、アシスタントが本文を読み込むかどうかを決定する前に見るものです。 |
license | いいえ | 自由テキスト。スキルとともに記録されます。 |
compatibility | いいえ | 自由テキスト。スキルとともに記録されます。 |
metadata | いいえ | キーと値のマップ。スキルとともに記録されます。 |
allowed-tools | いいえ | スペース区切りのリスト。解析され記録されます。 |
本文は同僚への指示として書きます：何を、どの順序で、結果をどのように提示するか。本当にあなた独自の規則に限定してください。アシスタントが台帳から読み取れる事実はスキルに含めるべきではありません。
allowed-tools は権限の境界ではありません。bea 0.1.0 はこのフィールドを解析しますが、それ以外の何も読み取らないため、何も制限しません。意図のドキュメントとして扱ってください。実際に効力を持つ制御はコマンド自体にあります：対話型の書き込みは、ファイルに触れる前にプレビュー、確認、検証が行われ、グローバルな --yes は書き込み権限を付与せず、--print モードは提案された書き込みを適用しません。
読み込まれたことを確認する
使い捨てのスキルに、見逃せない指示を入れてから、何でも質問してください。
スキルを作成します：
mkdir -p .agents/skills/test-skill
cat > .agents/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Test skill to verify skill loading works.
---
IMPORTANT: Whenever the user asks any question, start your response with the exact phrase "SKILL LOADED".
EOFワンアンサーモードで質問します：
bea ask "what accounts do I have?" --printSKILL LOADED で始まる応答は、スキルが検出され、アシスタントに提供されたことを意味します。
次に、そのフレーズがスキルからのものであることを証明するため、ディレクトリをスキルツリーの外に移動して再度質問します：
mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skillそのフレーズは消えているはずです。ディレクトリを .agents/skills/ の外に移動してください。その場で名前を変更するのではなく：検出はヘッダーの name フィールドで照合されるため、test-skill.bak に名前を変更したディレクトリも依然として検出され、読み込まれます。
ユーザーレベルのスキルを確認するには、同じファイルを ~/.config/bea/skills/test-skill/SKILL.md に置いて繰り返します。優先順位を確認するには、同じ name を持つ両方のコピーを保持し、異なるフレーズを指定します：プロジェクトのフレーズが表示されるはずです。
テストスキルは完了したらクリーンアップしてください。そのディレクトリから行うすべての質問に適用されます。
bea ask のスキルはエージェントのスキルではない
これらのスキルは、組み込みの bea ask ヘルパーのみを拡張します。これらは、Claude Code や Codex などの外部コーディングエージェントにインストールする、外部から bea コマンドを駆動する標準的な Beancount.io スキルとは異なるものです。それが目的の場合は、代わりに AI エージェントによる会計 を読んでください — 外部エージェントのレシピを最初から最後までカバーしており、そのいずれも ask エクストラやホスト型アカウントを必要としません。