Buenas prácticas

El valor de una skill está en lo que ella sabe y un modelo no adivinaría: el endpoint correcto, el campo que viene nulo, la regla de negocio que no está escrita en ningún lugar. Las prácticas de abajo vienen de las skills que Kobana corre en producción.

Al escribir una skill

Verifica antes de afirmar. Ejecuta el comando, llama a la API, lee el archivo. Toda tabla de campos, enum y mensaje de error en el cuerpo de una skill debe haber salido de una ejecución real, y no de memoria. Cuando una verificación contradice lo que ibas a escribir, el hallazgo es la verificación.

Nombra el caso concreto. "El MCP de Kobana responde 401 a un token personal de uso API REST: el KOBANA_MCP_TOKEN debe ser un token de uso MCP" vale más que "verifica el token". El agente sigue mejor un ejemplo que una regla general.

Explica el porqué de cada prohibición. Una tabla de guardrails con el motivo junto a cada regla. Una regla sin motivo se ignora a la primera prisa, por el agente y por quien edite la skill después.

No hagas	Por qué
Preguntar al usuario durante la ejecución	no hay usuario: la ejecución se bloquea hasta el límite de 60 minutos
Llamar a log_http_call en cada solicitud de un scanner	miles de líneas ahogan la pestaña Registros y esconden las llamadas de integración
Leer configuración con ${VAR:-padrão} fuera de required_secrets	el valor predeterminado vale siempre, y nadie puede cambiar el valor desde Kadu

Escribe para los dos modos. Una skill útil en Claude Code corre en local (con una persona respondiendo) y en task (en Kadu, sin nadie). En task, no preguntes: registra un pendiente y sigue. Detecta el modo con GITHUB_ACTIONS (El cuerpo de la tarea).

Termina con una tabla de errores comunes: síntoma → causa → dónde está la solución. Es la parte que más tiempo ahorra a quien diagnostica.

Un parámetro declarado tiene que leerse y usarse. Un parámetro en el parameters_schema que ningún paso consulta es un bug, y no documentación.

Una tarea orquesta; las auxiliares hacen. Separa el acceso a cada sistema externo en skills auxiliares pequeñas (fintera-listar-contas-a-receber, nfeio-buscar-nota-fiscal) y deja que la tarea decida el orden y qué hacer con cada resultado. Las auxiliares se reaprovechan en otras tareas y se prueban solas en Claude Code.

Al cambiar una skill que ya es una tarea

• Cambia el frontmatter, nunca el nombre de la carpeta. Renombrar crea otra tarea.
• Actualiza la documentación del repositorio en el mismo commit: la tabla de tareas del workspace en el README.md y el conteo de tareas. Un README desactualizado es el primer lugar donde se pierde la próxima persona.
• Revisa los avisos de la sincronización después del merge, con el botón Sincronizar. Un elemento inválido (cron, nombre de entorno) descarta la lista completa, y solo el aviso lo cuenta.
• La configuración de la tarea cambia en el repositorio, no en la consola. Las programaciones, el endpoint, el ejecutor y el metadata declarados en el bloque task:, y los entornos en el kadu.yaml, vuelven a lo declarado en cada push.

Al mantener el Playbook

• main es producción. Trabaja en una rama, valida en el sandbox de CI y trata el merge como un deploy (Sincronización).
• Agrega archivos por ruta explícita. git add -A toma el .execution-result.json que una ejecución local deja en la raíz y el .env de prueba. Mantén ambos en el .gitignore.
• Mantén un CLAUDE.md en la raíz con las reglas del repositorio: cómo se escriben las skills, qué no puede ir a git, el orden para provisionar un secret. Es lo que Claude Code lee antes de editar.

Idioma

Escribe las skills, los eventos y el resultado en el idioma de quien los va a leer. Los eventos y el resultado de una ejecución deben seguir $LOCALE, el idioma de quien lanzó.