Plaats een SKILL.md-bestand naast uw grootboek en bea ask volgt uw eigen boekhoudconventies — uw categorienamen, uw rapportindeling, uw huisregels — zonder dat u ze bij elke vraag herhaalt.
Een vaardigheid is eenvoudige Markdown met een kleine YAML-kop. bea ask ontdekt deze bij het opstarten en biedt deze aan de gehoste assistent aan, die de volledige tekst laadt wanneer een vraag erom vraagt.
Deze pagina gaat ervan uit dat bea ask al voor u werkt. Het vereist de ask-extra (uv tool install 'beancount-io[ask]') en Beancount.io-referenties van bea cloud login of BEA_TOKEN. Query's worden uitgevoerd op uw lokale grootboek, maar de vraag en de vaardigheidscontext gaan naar de gehoste Beancount.io AI-service. bea ask heeft geen JSON-uitvoer. Zie de CLI-referentie voor het volledige commandocontract.
Waar een vaardigheid woont
bea ask leest twee mappen, in deze volgorde:
| Locatie | Bereik |
|---|---|
<grootboek-map>/.agents/skills/ | Projectniveau — één grootboek, en meestal ingecheckt in de bijbehorende repository |
~/.config/bea/skills/ | Gebruikersniveau — elk grootboek dat u op deze machine opent |
De projectmap wordt bepaald op basis van de werkmap waarin u bea ask uitvoert, niet op basis van --file. Wanneer beide mappen een vaardigheid met dezelfde name bevatten, wint de projectkopie en wordt de gebruikerskopie genegeerd.
BEA_CONFIG_DIR verplaatst de map op gebruikersniveau: stel het in en vaardigheden worden gelezen uit $BEA_CONFIG_DIR/skills/. Anders geldt $XDG_CONFIG_HOME/bea/skills/, met als terugval ~/.config/bea/skills/.
Schrijf het vaardigheidsbestand
Eén map per vaardigheid, met daarin één bestand met de naam SKILL.md:
.agents/skills/
└── monthly-report/
└── SKILL.mdHet bestand is een YAML-kop gevolgd door uw instructies:
---
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.Twee velden zijn verplicht. Een bestand dat een van beide mist, wordt stil overgeslagen, dus een ontbrekende vaardigheid is meestal een probleem met de kop.
| Veld | Verplicht | Wat het doet |
|---|---|---|
name | ja | Kleine letters en koppeltekens. Houd het gelijk aan de mapnaam — voorrang tussen de twee locaties wordt op deze waarde gematcht, dus een mismatch maakt overschrijvingen moeilijk te voorspellen. |
description | ja | Eén regel die de assistent vertelt wanneer de vaardigheid moet worden toegepast. Dit is wat de assistent ziet voordat hij besluit de hoofdtekst te laden. |
license | nee | Vrije tekst, geregistreerd bij de vaardigheid. |
compatibility | nee | Vrije tekst, geregistreerd bij de vaardigheid. |
metadata | nee | Een sleutel-waardekaart, geregistreerd bij de vaardigheid. |
allowed-tools | nee | Een door spaties gescheiden lijst, geparseerd en geregistreerd. |
Schrijf de hoofdtekst als instructies aan een collega: wat te doen, in welke volgorde en hoe het resultaat te presenteren. Beperk het tot de conventies die echt van u zijn. Feiten die de assistent uit uw grootboek kan lezen, horen niet in een vaardigheid thuis.
allowed-tools is geen machtigingsgrens. bea 0.1.0 parseert het veld en niets anders leest het, dus het beperkt niets. Beschouw het als documentatie van de bedoeling. De controles die wel gelden, zitten in het commando zelf: interactieve schrijfbewerkingen worden gecontroleerd, bevestigd en gevalideerd voordat ze het bestand raken, globale --yes verleent geen schrijfrechten en --print-modus past een voorgestelde schrijfbewerking nooit toe.
Controleer dat het is geladen
Geef een wegwerpvaardigheid een instructie die u niet kunt missen en stel dan willekeurig welke vraag.
Maak de vaardigheid:
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".
EOFStel een vraag in de modus met één antwoord:
bea ask "what accounts do I have?" --printEen reactie die begint met SKILL LOADED betekent dat de vaardigheid is ontdekt en aan de assistent is aangeboden.
Bewijs dan dat de zin uit de vaardigheid kwam, door de map uit de vaardigheidsboom te verplaatsen en opnieuw te vragen:
mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skillDe zin zou moeten verdwijnen. Verplaats de map uit .agents/skills/, in plaats van deze ter plekke te hernoemen: ontdekking matcht op het name-veld in de kop, dus een map die is hernoemd naar test-skill.bak wordt nog steeds gevonden en nog steeds geladen.
Om een vaardigheid op gebruikersniveau te controleren, plaatst u hetzelfde bestand onder ~/.config/bea/skills/test-skill/SKILL.md en herhaalt u. Om de voorrang te controleren, houdt u beide kopieën met dezelfde name en geeft u ze verschillende zinnen: de projectzin is degene die u zou moeten zien.
Ruim de testvaardigheid op wanneer u klaar bent. Deze is van toepassing op elke vraag die u vanuit die map stelt.
Vaardigheden voor bea ask zijn geen vaardigheden voor uw agent
Deze vaardigheden breiden alleen de ingebouwde bea ask-helper uit. Ze zijn iets anders dan de canonieke Beancount.io-vaardigheden die u in een externe coderingsagent zoals Claude Code of Codex installeert, die bea-commando's van buitenaf aansturen. Als u dat zoekt, lees dan Boekhouden met AI-agenten — dat behandelt de recepten voor externe agenten van begin tot eind, en geen van alle hebben de ask-extra of een gehost account nodig.