Coloca un archivo SKILL.md junto a tu libro mayor y bea ask seguirá tus propias convenciones contables — tus nombres de categorías, el diseño de tu informe, tus reglas internas — sin que tengas que repetirlas en cada pregunta.
Una habilidad es Markdown simple con una pequeña cabecera YAML. bea ask la descubre al iniciarse y se la ofrece al asistente alojado, que carga el texto completo cuando una pregunta lo requiere.
Esta página asume que bea ask ya funciona para ti. Necesita el extra ask (uv tool install 'beancount-io[ask]') y las credenciales de Beancount.io de bea cloud login o BEA_TOKEN. Las consultas se ejecutan contra tu libro mayor local, pero la pregunta y el contexto de la habilidad se envían al servicio de IA alojado de Beancount.io. bea ask no tiene salida JSON. Consulta la referencia de CLI para el contrato completo del comando.
Dónde vive una habilidad
bea ask lee dos directorios, en este orden:
| Ubicación | Alcance |
|---|---|
<directorio-del-libro>/.agents/skills/ | Nivel de proyecto — un libro mayor, y normalmente incluido en su repositorio |
~/.config/bea/skills/ | Nivel de usuario — cada libro mayor que abras en esta máquina |
El directorio del proyecto se resuelve desde el directorio de trabajo en el que ejecutas bea ask, no desde --file. Cuando ambos directorios contienen una habilidad con el mismo name, gana la copia del proyecto y se ignora la copia del usuario.
BEA_CONFIG_DIR reubica el directorio de nivel de usuario: ajústalo y las habilidades se leen desde $BEA_CONFIG_DIR/skills/. De lo contrario, se aplica $XDG_CONFIG_HOME/bea/skills/, con respaldo en ~/.config/bea/skills/.
Escribe el archivo de habilidad
Un directorio por habilidad, que contenga un único archivo llamado SKILL.md:
.agents/skills/
└── monthly-report/
└── SKILL.mdEl archivo es una cabecera YAML seguida de tus instrucciones:
---
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.Dos campos son obligatorios. Un archivo que carezca de cualquiera de ellos se omite silenciosamente, así que una habilidad ausente suele ser un problema de cabecera.
| Campo | Obligatorio | Qué hace |
|---|---|---|
name | sí | Letras minúsculas y guiones. Mantenlo igual al nombre del directorio — la precedencia entre las dos ubicaciones se compara con este valor, por lo que una discrepancia hace que las anulaciones sean difíciles de predecir. |
description | sí | Una línea que le dice al asistente cuándo aplicar la habilidad. Es lo que el asistente ve antes de decidir si cargar el cuerpo. |
license | no | Texto libre, registrado con la habilidad. |
compatibility | no | Texto libre, registrado con la habilidad. |
metadata | no | Un mapa clave-valor, registrado con la habilidad. |
allowed-tools | no | Una lista separada por espacios, analizada y registrada. |
Escribe el cuerpo como instrucciones para un colega: qué hacer, en qué orden y cómo presentar el resultado. Limítalo a las convenciones que son genuinamente tuyas. Los hechos que el asistente pueda leer de tu libro mayor no pertenecen a una habilidad.
allowed-tools no es un límite de permisos. bea 0.1.0 analiza el campo y nada más lo lee, por lo que no restringe nada. Trátalo como documentación de intención. Los controles que sí se mantienen son los del propio comando: las escrituras interactivas se previsualizan, confirman y validan antes de tocar el archivo, el --yes global no otorga permiso de escritura y el modo --print nunca aplica una escritura propuesta.
Comprueba que se cargó
Dale a una habilidad desechable una instrucción que no puedas pasar por alto, luego pregunta cualquier cosa.
Crea la habilidad:
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".
EOFHaz una pregunta en modo de respuesta única:
bea ask "what accounts do I have?" --printUna respuesta que comience con SKILL LOADED significa que la habilidad fue descubierta y ofrecida al asistente.
Luego demuestra que la frase provino de la habilidad, moviendo el directorio fuera del árbol de habilidades y preguntando de nuevo:
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 debería desaparecer. Mueve el directorio fuera de .agents/skills/, en lugar de renombrarlo en su lugar: el descubrimiento coincide con el campo name de la cabecera, por lo que un directorio renombrado a test-skill.bak aún se encuentra y aún se carga.
Para comprobar una habilidad de nivel de usuario, coloca el mismo archivo en ~/.config/bea/skills/test-skill/SKILL.md y repite. Para comprobar la precedencia, mantén ambas copias con el mismo name y dales frases diferentes: la frase del proyecto es la que deberías ver.
Limpia la habilidad de prueba cuando termines. Se aplica a cada pregunta que hagas desde ese directorio.
Las habilidades para bea ask no son habilidades para tu agente
Estas habilidades extienden únicamente el asistente integrado bea ask. Son una cosa distinta de las habilidades canónicas de Beancount.io que instalas en un agente de codificación externo como Claude Code o Codex, que manejan los comandos bea desde fuera. Si eso es lo que buscas, lee Contabilidad con agentes de IA en su lugar — cubre las recetas de agente externo de principio a fin, y ninguna de ellas necesita el extra ask ni una cuenta alojada.