Поместите файл SKILL.md рядом с вашей книгой, и bea ask будет следовать вашим собственным правилам бухгалтерии — вашим названиям категорий, макету отчётов, вашим внутренним правилам — без необходимости повторять их в каждом вопросе.
Навык — это обычный Markdown с небольшим YAML-заголовком. bea ask обнаруживает его при запуске и предлагает хостируемому ассистенту, который загружает полный текст, когда вопрос этого требует.
Эта страница предполагает, что bea ask уже работает у вас. Для этого требуется дополнительный пакет ask (uv tool install 'beancount-io[ask]') и учётные данные Beancount.io из bea cloud login или BEA_TOKEN. Запросы выполняются к вашей локальной книге, но вопрос и контекст навыка отправляются в хостируемый сервис ИИ Beancount.io. bea ask не имеет JSON-вывода. Полный контракт команды см. в справочнике CLI.
Где находится навык
bea ask читает два каталога в следующем порядке:
| Расположение | Область |
|---|---|
<каталог-книги>/.agents/skills/ | Уровень проекта — одна книга, обычно включённая в его репозиторий |
~/.config/bea/skills/ | Уровень пользователя — каждая книга, которую вы открываете на этой машине |
Каталог проекта определяется из рабочего каталога, в котором вы запускаете bea ask, а не из --file. Когда в обоих каталогах есть навык с одинаковым name, побеждает копия проекта, а копия пользователя игнорируется.
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 и повторите. Чтобы проверить приоритет, сохраните обе копии с одинаковым name и дайте им разные фразы: вы должны увидеть фразу проекта.
Уберите тестовый навык, когда закончите. Он применяется к каждому вопросу, который вы задаёте из этого каталога.
Навыки для bea ask — это не навыки для вашего агента
Эти навыки расширяют только встроенный помощник bea ask. Это не то же самое, что канонические навыки Beancount.io, которые вы устанавливаете во внешний агент кодирования, такой как Claude Code или Codex, и которые управляют командами bea извне. Если вам нужно именно это, прочитайте Бухгалтерия с ИИ-агентами — там подробно рассматриваются рецепты внешнего агента, и ни одному из них не требуется дополнительный пакет ask или хостируемая учётная запись.