Déposez un fichier SKILL.md à côté de votre grand livre et bea ask suit vos propres conventions comptables — vos noms de catégories, la mise en page de vos rapports, vos règles maison — sans que vous ayez à les répéter à chaque question.
Un skill est du Markdown simple avec un petit en-tête YAML. bea ask le détecte au démarrage et le propose à l'assistant hébergé, qui charge le texte intégral lorsqu'une question l'exige.
Cette page suppose que bea ask fonctionne déjà pour vous. Il nécessite l'extra ask (uv tool install 'beancount-io[ask]') et des identifiants Beancount.io obtenus via bea cloud login ou BEA_TOKEN. Les requêtes sont exécutées sur votre grand livre local, mais la question et le contexte du skill sont envoyés au service d'IA hébergé Beancount.io. bea ask n'a pas de sortie JSON. Consultez la référence CLI pour le contrat de commande complet.
Où vit un skill
bea ask lit deux répertoires, dans cet ordre :
| Emplacement | Portée |
|---|---|
<ledger-dir>/.agents/skills/ | Niveau projet — un grand livre, généralement versionné dans son dépôt |
~/.config/bea/skills/ | Niveau utilisateur — tous les grands livres que vous ouvrez sur cette machine |
Le répertoire projet est résolu à partir du répertoire de travail dans lequel vous exécutez bea ask, et non à partir de --file. Lorsque les deux répertoires contiennent un skill avec le même name, la copie du projet l'emporte et la copie utilisateur est ignorée.
BEA_CONFIG_DIR déplace le répertoire de niveau utilisateur : définissez cette variable et les skills sont lus depuis $BEA_CONFIG_DIR/skills/. Sinon, $XDG_CONFIG_HOME/bea/skills/ s'applique, avec ~/.config/bea/skills/ en dernier recours.
Rédiger le fichier de skill
Un répertoire par skill, contenant un fichier nommé SKILL.md :
.agents/skills/
└── monthly-report/
└── SKILL.mdLe fichier est un en-tête YAML suivi de vos instructions :
---
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.Deux champs sont obligatoires. Un fichier auquel il manque l'un ou l'autre est ignoré en silence, donc un skill absent est généralement un problème d'en-tête.
| Champ | Requis | Rôle |
|---|---|---|
name | oui | Lettres minuscules et traits d'union. Gardez-le identique au nom du répertoire — la priorité entre les deux emplacements est déterminée par cette valeur, donc une discordance rend les remplacements difficiles à prévoir. |
description | oui | Une ligne indiquant à l'assistant quand appliquer le skill. C'est ce que l'assistant voit avant de décider de charger le corps. |
license | non | Texte libre, enregistré avec le skill. |
compatibility | non | Texte libre, enregistré avec le skill. |
metadata | non | Un mapping clé-valeur, enregistré avec le skill. |
allowed-tools | non | Une liste séparée par des espaces, analysée et enregistrée. |
Rédigez le corps comme des instructions destinées à un collègue : quoi faire, dans quel ordre et comment présenter le résultat. Limitez-vous aux conventions qui sont réellement les vôtres. Les faits que l'assistant peut lire dans votre grand livre n'ont pas leur place dans un skill.
allowed-tools n'est pas une frontière de permissions. bea 0.1.0 analyse le champ et rien d'autre ne le lit, donc ce champ ne restreint rien. Traitez-le comme une documentation d'intention. Les contrôles qui s'appliquent réellement sont ceux de la commande elle-même : les écritures interactives sont prévisualisées, confirmées et validées avant de modifier le fichier, l'option globale --yes n'accorde pas la permission d'écrire, et le mode --print n'applique jamais une écriture proposée.
Vérifier qu'il s'est chargé
Donnez à un skill jetable une instruction impossible à manquer, puis posez n'importe quelle question.
Créez le 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".
EOFPosez une question en mode réponse unique :
bea ask "what accounts do I have?" --printUne réponse commençant par SKILL LOADED signifie que le skill a été détecté et proposé à l'assistant.
Prouvez ensuite que la phrase provient du skill en déplaçant le répertoire hors de l'arborescence des skills et en posant à nouveau la question :
mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skillLa phrase devrait avoir disparu. Déplacez le répertoire hors de .agents/skills/ plutôt que de le renommer sur place : la détection se fait sur le champ name de l'en-tête, donc un répertoire renommé en test-skill.bak est toujours trouvé et toujours chargé.
Pour vérifier un skill de niveau utilisateur, placez le même fichier sous ~/.config/bea/skills/test-skill/SKILL.md et répétez l'opération. Pour vérifier la priorité, conservez les deux copies avec le même name et donnez-leur des phrases différentes : c'est la phrase du projet que vous devriez voir.
Nettoyez le skill de test quand vous avez terminé. Il s'applique à chaque question posée depuis ce répertoire.
Les skills pour bea ask ne sont pas les skills de votre agent
Ces skills étendent uniquement l'assistant intégré bea ask. Ce sont des choses différentes des skills canoniques Beancount.io que vous installez dans un agent de codage externe tel que Claude Code ou Codex, qui pilotent les commandes bea depuis l'extérieur. Si c'est ce que vous recherchez, lisez plutôt Comptabilité avec les agents IA — il couvre les recettes d'agents externes de bout en bout, et aucune d'elles ne nécessite l'extra ask ni un compte hébergé.