Cómo crear una skill personalizada para Hermes Agent

Una skill es la unidad mínima de comportamiento que puedes enseñarle a Hermes Agent sin tocar su código fuente. Es una carpeta, un archivo markdown y una pequeña cabecera YAML. La documentación oficial de Nous Research describe el formato como "portable porque es simple", y crear una skill personalizada lleva menos de cinco minutos cuando ya conoces la estructura.

Esta guía recorre esa estructura de principio a fin. Verás dónde viven las skills en el disco, qué debe contener el encabezado de SKILL.md, qué secciones lee realmente el agente en ejecución, cómo inyectar secretos mediante required_environment_variables y cómo verificar que la skill se cargó correctamente. El resultado es una skill que puedes copiar a ~/.hermes/skills/ y usar el mismo día.

Dónde viven las skills y cómo las encuentra Hermes

Hermes guarda las skills como carpetas planas dentro de ~/.hermes/skills/. Las skills incluidas se copian ahí durante la instalación, y cualquier skill personalizada que añadas se registra de inmediato en el siguiente reinicio. La disposición es plana:

~/.hermes/skills/
├── backup-check/
│   └── SKILL.md
├── invoice-followup/
│   └── SKILL.md
└── stripe-mrr-digest/
    ├── SKILL.md
    └── helper.py

El nombre de la carpeta es el id de la skill. Hermes descubre cada carpeta automáticamente al arrancar y lee el SKILL.md correspondiente. El campo description del frontmatter YAML es lo que el agente compara con tu mensaje en tiempo de ejecución, así que escríbelo pensando en el agente, no en un lector humano. Si la descripción no describe con claridad la condición de disparo, la skill no se activará cuando tú lo esperas.

Una skill puede incluir archivos extra en su carpeta: un helper en Python, una plantilla SQL, una checklist en texto plano. Hermes no los ejecuta por sí mismo. Están ahí para que el agente los lea o los ejecute cuando el procedimiento se lo indique.

Diagrama de tres carpetas de skills dentro de ~/.hermes/skills/, cada una con un SKILL.md, con flechas que apuntan al proceso de Hermes Agent en ejecución

El formato del archivo SKILL.md

Toda skill es un único archivo markdown. La cabecera YAML al inicio es el bloque de metadatos, y el cuerpo en markdown es el conjunto de instrucciones. Aquí tienes un esqueleto mínimo que puedes copiar:

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 0.1.0
author: [email protected]
required_environment_variables: []
required_credential_files: []
---

Los campos que importan desde el primer día:

name - coincide con el nombre de la carpeta. En kebab-case, sin espacios.
description - una sola frase que Hermes usa para decidir cuándo cargar la skill. Sé concreto sobre la condición de disparo ("cuando el usuario pregunte por X", "antes de ejecutar Y").
version - es libre, pero trátalo como semver para poder subirlo a medida que el contenido evoluciona.
required_environment_variables - un array con los nombres de los secretos que deben estar definidos antes de ejecutar la skill. El agente los pide en la primera activación y los escribe en .env.
required_credential_files - rutas a tokens OAuth o ficheros JSON de cuentas de servicio que tienen que montarse dentro del sandbox.

Campos opcionales que conviene conocer: platforms (array con macos, linux, windows si la skill solo funciona en algunos), requires_toolsets para mostrar la skill solo cuando ciertos toolsets están cargados, y fallback_for_toolsets para lo contrario. La configuración a nivel de skill vive en metadata.hermes.config y acaba bajo skills.config en tu config.yaml para preferencias no secretas como rutas o dominios.

Las cinco secciones que realmente lee el agente

Bajo el frontmatter, el cuerpo en markdown es prosa. Hermes no exige una sección concreta, pero una estructura en cinco partes se ha consolidado a partir de la guía oficial "Working with Skills" y de artículos de autores en dev.to y glukhov.org. El agente la aprovecha porque cada parte responde a una pregunta distinta en ejecución.

Cuándo usarla

Un párrafo corto que distingue esta skill de otras que el agente podría escoger. Si tienes una skill invoice-followup y otra client-update, "cuándo usarla" es lo que evita que el agente dispare la equivocada.

Referencia rápida

Una lista de comandos, rutas o constantes de los que depende el procedimiento. El agente la lee antes del procedimiento para cargar contexto. Pon aquí las rutas de archivos, el nombre del bucket de S3, los nombres de variables de entorno, el id del chat de Telegram de destino.

Procedimiento

Los pasos numerados que el agente debe seguir. Redáctalos en imperativo ("ejecuta X", "si la respuesta contiene Y, haz Z"). El agente trata esta sección como una receta y a menudo cita o parafrasea los pasos a medida que los ejecuta.

Errores comunes

Las trampas que ya conoces. Límites de tasa, fallos silenciosos, bugs de zona horaria, ese cliente cuyos datos tienen una forma rara. El agente lee esto como guardarraíles y avisa o se niega cuando detecta esas condiciones.

Verificación

Cómo confirma el agente que hizo lo correcto. Un grep, un curl, un checksum, un "muéstrame la última línea". La verificación es lo que convierte una skill en algo que puedes dejar funcionando sin supervisión.

Conectar secretos y credenciales

Si tu skill habla con una API, declara el secreto en required_environment_variables:

required_environment_variables:
  - STRIPE_RESTRICTED_KEY
  - SLACK_WEBHOOK_URL

La primera vez que la skill se activa, el agente te pide cada valor y los escribe en el .env del proyecto. Después se pasan automáticamente a los sandboxes (Docker, Modal, runners efímeros). Nunca dejes una clave dentro de la prosa: el agente la pegará durante la ejecución y acabará en algún log.

Para tokens OAuth o ficheros JSON de cuentas de servicio, usa required_credential_files:

required_credential_files:
  - ~/.config/gcloud/application_default_credentials.json

Estos se montan en el sandbox como volúmenes de solo lectura. El agente no los parsea: solo se asegura de que estén presentes antes de ejecutar el procedimiento.

Cómo Hermes extrae skills automáticamente de las conversaciones

También puedes dejar que Hermes escriba skills por ti. Tras una tarea compleja que implique cinco o más llamadas a herramientas, la herramienta skill_manage captura el patrón exitoso y lo escribe como una skill reutilizable en ~/.hermes/skills/. El agente analiza la conversación, identifica el flujo reutilizable y genera un SKILL.md con un procedimiento que refleja lo que realmente hizo.

Este es el mismo mecanismo que hace que Hermes parezca afinarse con el uso. La capa de memoria persistente recuerda de qué hablasteis; las skills auto-extraídas recuerdan cómo resolvió un problema. Las dos capas se explican con más detalle en nuestro artículo sobre memoria y skills de Hermes Agent.

Las primeras skills auto-extraídas suelen ser 80 por ciento lo que querías y 20 por ciento ruido. Abre el SKILL.md, ajusta la descripción, recorta los pasos que el agente ejecutó por accidente y sube la versión. Ya tienes una skill editada a mano que se dispara de forma fiable.

Probar una skill de principio a fin

Una vez que el SKILL.md está en su sitio, reinicia Hermes (o ejecuta hermes skill reload si tu versión lo permite). Luego haz tres comprobaciones:

Pídele a Hermes que liste sus skills. La nueva debe aparecer con su nombre y la descripción que escribiste.
Envía un mensaje que coincida con la condición de disparo. El agente debería anunciar que va a usar la skill antes de hacer nada.
Ejecuta manualmente el paso de verificación. Si la skill escribe un archivo, comprueba el archivo. Si publica en un webhook, revisa el webhook.

Si la skill no carga, el YAML suele ser la causa. Un tabulador suelto o un dos puntos sin comillas rompen silenciosamente el parser del frontmatter. Hermes registra el error en stderr al arrancar; revísalo la primera vez que recargues.

Escena fotorrealista del terminal de un desarrollador mostrando una sesión de Hermes Agent que carga una skill personalizada, con un prompt verde y luz ambiental tenue

Salta toda la fontanería con Hermes gestionado

Una skill personalizada es un archivo markdown, pero ejecutar Hermes en sí no lo es. Necesitas un host, una clave de proveedor de modelo, un bot de Telegram o una web UI, una estrategia de backup para el directorio de skills y una forma de probar cambios sin romper tu agente en producción.

Hermify es hosting gestionado de Hermes Agent que se encarga de todo eso. Tu directorio de skills persiste entre reinicios, las claves de modelo viven en almacenamiento cifrado en reposo y puedes combinar las skills personalizadas que escribas aquí con las integraciones MCP que Hermes ya habla. Empieza con Hermify y tu primera skill personalizada puede estar corriendo en un agente real en menos de cinco minutos.