在你的账本旁边放一个 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 按以下顺序读取两个目录：
| 位置 | 范围 |
|---|---|
<账本目录>/.agents/skills/ | 项目级——对应一个账本，通常纳入其代码仓库 |
~/.config/bea/skills/ | 用户级——你在这台机器上打开的每个账本 |
项目目录是根据你运行 bea ask 时的工作目录解析的，而不是根据 --file。当两个目录都包含同名技能时，项目副本优先，用户副本被忽略。
BEA_CONFIG_DIR 可以重定位用户级目录：设置后，技能将从 $BEA_CONFIG_DIR/skills/ 读取。否则使用 $XDG_CONFIG_HOME/bea/skills/，并回退到 ~/.config/bea/skills/。
编写技能文件
每个技能一个目录，目录中包含一个名为 SKILL.md 的文件：
.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.有两个字段是必需的。缺少任一字段的文件会被静默跳过，所以技能缺失通常是头部的问题。
| 字段 | 必需 | 作用 |
|---|---|---|
name | 是 | 小写字母和连字符。保持与目录名一致——两个位置之间的优先级是按此值匹配的，不一致会让覆盖行为难以预测。 |
description | 是 | 一行文字，告诉助手何时应用该技能。助手在决定是否加载正文之前看到的就是这个。 |
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?" --print如果响应以 SKILL 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 下并重复上述步骤。要检查优先级，保留两份同名副本并给它们不同的短语：你应该看到的是项目级的那句。
完成后清理测试技能。它会应用于你从该目录发出的每个问题。
用于 bea ask 的技能不是用于你的代理的技能
这些技能只扩展内置的 bea ask 助手。它们与你在外部编码代理（如 Claude Code 或 Codex）中安装的规范 Beancount.io 技能不同，后者从外部驱动 bea 命令。如果你需要的是后者，请阅读 使用 AI 代理进行会计——它完整覆盖了外部代理的用法，而且都不需要 ask 附加组件或托管账户。