Inserisci un file SKILL.md accanto al tuo registro e bea ask seguirà le tue convenzioni contabili — i tuoi nomi di categoria, il tuo layout di report, le tue regole interne — senza che tu le ripeta in ogni domanda.
Una skill è semplice Markdown con una piccola intestazione YAML. bea ask la rileva all'avvio e la offre all'assistente ospitato, che carica il testo completo quando una domanda lo richiede.
Questa pagina presuppone che bea ask funzioni già per te. Richiede l'extra ask (uv tool install 'beancount-io[ask]') e le credenziali Beancount.io da bea cloud login o BEA_TOKEN. Le query vengono eseguite sul tuo registro locale, ma la domanda e il contesto della skill vanno al servizio AI ospitato di Beancount.io. bea ask non ha output JSON. Consulta il riferimento CLI per il contratto completo del comando.
Dove vive una skill
bea ask legge due directory, in questo ordine:
| Posizione | Ambito |
|---|---|
<dir-registro>/.agents/skills/ | Livello di progetto — un registro, di solito versionato nel suo repository |
~/.config/bea/skills/ | Livello utente — ogni registro che apri su questa macchina |
La directory di progetto viene risolta dalla directory di lavoro in cui esegui bea ask, non da --file. Quando entrambe le directory contengono una skill con lo stesso name, vince la copia di progetto e quella utente viene ignorata.
BEA_CONFIG_DIR sposta la directory a livello utente: impostala e le skill verranno lette da $BEA_CONFIG_DIR/skills/. Altrimenti si applica $XDG_CONFIG_HOME/bea/skills/, con fallback a ~/.config/bea/skills/.
Scrivi il file della skill
Una directory per skill, contenente un unico file chiamato SKILL.md:
.agents/skills/
└── monthly-report/
└── SKILL.mdIl file è un'intestazione YAML seguita dalle tue istruzioni:
---
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.Due campi sono obbligatori. Un file a cui manca uno dei due viene saltato in silenzio, quindi una skill assente di solito è un problema di intestazione.
| Campo | Obbligatorio | Cosa fa |
|---|---|---|
name | sì | Lettere minuscole e trattini. Mantienilo uguale al nome della directory — la precedenza tra le due posizioni viene abbinata su questo valore, quindi una discrepanza rende gli override difficili da prevedere. |
description | sì | Una riga che dice all'assistente quando applicare la skill. È ciò che l'assistente vede prima di decidere di caricare il corpo. |
license | no | Testo libero, registrato con la skill. |
compatibility | no | Testo libero, registrato con la skill. |
metadata | no | Una mappa chiave-valore, registrata con la skill. |
allowed-tools | no | Un elenco separato da spazi, analizzato e registrato. |
Scrivi il corpo come istruzioni a un collega: cosa fare, in che ordine e come presentare il risultato. Limitati alle convenzioni che sono davvero tue. I fatti che l'assistente può leggere dal tuo registro non appartengono a una skill.
allowed-tools non è un confine di autorizzazione. bea 0.1.0 analizza il campo e nient'altro lo legge, quindi non limita nulla. Trattalo come documentazione delle intenzioni. I controlli che valgono davvero sono quelli nel comando stesso: le scritture interattive vengono anteprime, confermate e validate prima di toccare il file, --yes globale non concede il permesso di scrittura e la modalità --print non applica mai una scrittura proposta.
Verifica che sia stata caricata
Dai a una skill usa e getta un'istruzione che non puoi non notare, poi fai una domanda qualsiasi.
Crea la 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".
EOFFai una domanda in modalità a risposta singola:
bea ask "what accounts do I have?" --printUna risposta che inizia con SKILL LOADED significa che la skill è stata rilevata e offerta all'assistente.
Poi dimostra che la frase proviene dalla skill, spostando la directory fuori dall'albero delle skill e chiedendo di nuovo:
mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skillLa frase dovrebbe essere sparita. Sposta la directory fuori da .agents/skills/, anziché rinominarla sul posto: il rilevamento si basa sul campo name nell'intestazione, quindi una directory rinominata in test-skill.bak viene ancora trovata e caricata.
Per verificare una skill a livello utente, metti lo stesso file in ~/.config/bea/skills/test-skill/SKILL.md e ripeti. Per verificare la precedenza, tieni entrambe le copie con lo stesso name e dai loro frasi diverse: la frase di progetto è quella che dovresti vedere.
Rimuovi la skill di test quando hai finito. Si applica a ogni domanda che fai da quella directory.
Le skill per bea ask non sono skill per il tuo agente
Queste skill estendono solo l'helper integrato bea ask. Sono una cosa diversa dalle skill canoniche Beancount.io che installi in un agente di codifica esterno come Claude Code o Codex, che guidano i comandi bea dall'esterno. Se è quello che cerchi, leggi invece Contabilità con agenti AI — copre le ricette per agenti esterni dall'inizio alla fine, e nessuna di esse richiede l'extra ask o un account ospitato.