Покладіть файл SKILL.md поруч з вашим реєстром, і bea ask буде дотримуватися ваших власних бухгалтерських умовностей — ваші назви категорій, ваш макет звіту, ваші внутрішні правила — без необхідності повторювати їх у кожному запитанні.
Навичка — це звичайний Markdown із невеликим YAML-заголовком. bea ask виявляє її під час запуску та пропонує хостингованому помічнику, який завантажує повний текст, коли запитання цього потребує.
Ця сторінка передбачає, що bea ask уже працює у вас. Вона потребує додаткового компонента ask (uv tool install 'beancount-io[ask]') та облікових даних Beancount.io з bea cloud login або BEA_TOKEN. Запити виконуються проти вашого локального реєстру, але запитання та контекст навички надсилаються до хостингового AI-сервісу 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 ззовні. Якщо це те, що вам потрібно, прочитайте Бухгалтерія з AI-агентами натомість — вона охоплює рецепти зовнішніх агентів від початку до кінця, і жоден з них не потребує додаткового компонента ask або хостингового облікового запису.