Coloque um arquivo SKILL.md ao lado do seu ledger e o bea ask segue suas próprias convenções contábeis — seus nomes de categorias, seu layout de relatórios, suas regras internas — sem você repeti-las em cada pergunta.
Uma skill é Markdown simples com um pequeno cabeçalho YAML. O bea ask a descobre na inicialização e a oferece ao assistente hospedado, que carrega o texto completo quando uma pergunta o exige.
Esta página assume que o bea ask já funciona para você. Ela exige o extra ask (uv tool install 'beancount-io[ask]') e credenciais do Beancount.io obtidas via bea cloud login ou BEA_TOKEN. As consultas são executadas contra seu ledger local, mas a pergunta e o contexto da skill vão para o serviço de IA hospedado do Beancount.io. O bea ask não tem saída JSON. Consulte a referência da CLI para o contrato completo do comando.
Onde uma skill mora
O bea ask lê dois diretórios, nesta ordem:
| Localização | Escopo |
|---|---|
<ledger-dir>/.agents/skills/ | Nível do projeto — um ledger, e geralmente versionado no repositório dele |
~/.config/bea/skills/ | Nível do usuário — todos os ledgers que você abre nesta máquina |
O diretório do projeto é resolvido a partir do diretório de trabalho onde você executa o bea ask, não a partir de --file. Quando ambos os diretórios contêm uma skill com o mesmo name, a cópia do projeto vence e a cópia do usuário é ignorada.
O BEA_CONFIG_DIR realoca o diretório de nível do usuário: defina-o e as skills serão lidas de $BEA_CONFIG_DIR/skills/. Caso contrário, $XDG_CONFIG_HOME/bea/skills/ se aplica, com fallback para ~/.config/bea/skills/.
Escreva o arquivo da skill
Um diretório por skill, contendo um único arquivo chamado SKILL.md:
.agents/skills/
└── monthly-report/
└── SKILL.mdO arquivo é um cabeçalho YAML seguido de suas instruções:
---
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.Dois campos são obrigatórios. Um arquivo que falte qualquer um deles é ignorado silenciosamente, então uma skill ausente geralmente é um problema de cabeçalho.
| Campo | Obrigatório | O que faz |
|---|---|---|
name | sim | Letras minúsculas e hífens. Mantenha-o igual ao nome do diretório — a precedência entre os dois locais é correspondida por esse valor, portanto uma incompatibilidade torna as substituições difíceis de prever. |
description | sim | Uma linha dizendo ao assistente quando aplicar a skill. É o que o assistente vê antes de decidir carregar o corpo. |
license | não | Texto livre, registrado com a skill. |
compatibility | não | Texto livre, registrado com a skill. |
metadata | não | Um mapa chave-valor, registrado com a skill. |
allowed-tools | não | Uma lista separada por espaços, analisada e registrada. |
Escreva o corpo como instruções para um colega: o que fazer, em que ordem e como apresentar o resultado. Limite-se às convenções que são genuinamente suas. Fatos que o assistente pode ler diretamente do seu ledger não pertencem a uma skill.
allowed-tools não é uma fronteira de permissão. O bea 0.1.0 analisa o campo e nada mais o lê, portanto ele não restringe nada. Trate-o como documentação de intenção. Os controles que realmente valem são os do próprio comando: gravações interativas são pré-visualizadas, confirmadas e validadas antes de tocarem no arquivo, o --yes global não concede permissão de escrita e o modo --print nunca aplica uma gravação proposta.
Verifique se ela foi carregada
Dê a uma skill descartável uma instrução impossível de ignorar e depois faça qualquer pergunta.
Crie a skill:
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".
EOFFaça uma pergunta no modo de resposta única:
bea ask "what accounts do I have?" --printUma resposta começando com SKILL LOADED significa que a skill foi descoberta e oferecida ao assistente.
Depois comprove que a frase veio da skill, movendo o diretório para fora da árvore de skills e perguntando novamente:
mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skillA frase deve ter sumido. Mova o diretório para fora de .agents/skills/, em vez de renomeá-lo no lugar: a descoberta corresponde ao campo name no cabeçalho, então um diretório renomeado para test-skill.bak ainda é encontrado e ainda é carregado.
Para verificar uma skill de nível do usuário, coloque o mesmo arquivo em ~/.config/bea/skills/test-skill/SKILL.md e repita. Para verificar a precedência, mantenha ambas as cópias com o mesmo name e dê a elas frases diferentes: a frase do projeto é a que você deve ver.
Limpe a skill de teste quando terminar. Ela se aplica a todas as perguntas que você fizer a partir daquele diretório.
Skills para o bea ask não são skills para o seu agente
Estas skills estendem apenas o helper integrado bea ask. Elas são uma coisa diferente das skills canônicas do Beancount.io que você instala em um agente de codificação externo, como Claude Code ou Codex, que acionam comandos bea de fora. Se é isso que você procura, leia Contabilidade com agentes de IA em vez disso — ele cobre as receitas de agente externo de ponta a ponta, e nenhuma delas precisa do extra ask ou de uma conta hospedada.