Creación de habilidades del agente Hermes: estructura de SKILL.md y mejores prácticas

Hermes Agent trata las habilidades (skills) como la forma predeterminada de enseñar flujos de trabajo repetibles. La documentación oficial las describe como documentos de conocimiento bajo demanda alineados con la estructura abierta de agentskills.io, cargados mediante revelación progresiva para que el modelo vea primero un índice pequeño y solo recupere las instrucciones completas cuando una tarea realmente lo necesite.

La autoría se trata menos de un redactado ingenioso que de empaquetado: le estás indicando al entorno de ejecución cuándo cargar un procedimiento, qué orden de pasos cuenta como “completado” y cómo distinguir el éxito de un fallo silencioso. Este artículo se centra en la estructura de SKILL.md, carpetas de soporte, reglas de visibilidad y la distinción entre configuraciones secretas y no secretas: los detalles que deciden si una habilidad aparece en los comandos /slash, sobrevive a una instalación en el hub o desaparece silenciosamente en CI.

Hermes se sitúa dentro del clúster más amplio de Sistemas de IA: Asistentes Autoalojados, RAG e Infraestructura Local, donde los asistentes se tratan como sistemas construidos a partir de inferencia, recuperación, memoria y herramientas, en lugar de como una simple superficie de chat. Las rutas de instalación, conexión de proveedores, comportamiento de la puerta de enlace y el diseño de ~/.hermes se detallan en la guía Asistente de IA Hermes - Instalación, Configuración, Flujo de Trabajo y Solución de Problemas; las ergonomías diarias de la shell—hermes skills, perfiles, puerta de enlace, memoria—son más fáciles de consultar en la Hoja de trucos de la CLI de Hermes Agent — comandos, banderas y atajos de slash. En despliegues reales, las habilidades heredan aislamiento de los perfiles (configuración, secretos, memorias y árboles de habilidades separados). Habilidades del Asistente de IA Hermes para Entornos de Producción Reales argumenta tratar a esos perfiles—no a los archivos markdown individuales—como la unidad de propiedad; ten esto en cuenta cuando nombres habilidades y decidas qué pertenece a external_dirs compartidos versus un solo perfil.

¿Habilidad o herramienta?

La guía oficial es directa. Usa una habilidad cuando la capacidad sea principalmente instrucciones en prosa más comandos de shell y herramientas que Hermes ya expone: envolver una CLI, impulsar git, llamar a curl o usar web_extract para extracciones estructuradas. Usa una herramienta cuando necesites una integración estricta para claves de API y flujos de autenticación, manejo determinista de binarios, transmisión (streaming) o Python que debe ejecutarse de la misma manera cada vez.

Ese límite importa en la práctica porque las habilidades se distribuyen sin cambiar el código del agente, mientras que las herramientas conllevan sobrecarga de revisión y lanzamiento. La mayoría de los equipos se benefician de empezar con una habilidad y luego promover solo el núcleo frágil a una herramienta una vez que los modos de fallo son evidentes (bucles de actualización de autenticación, analizadores binarios, idempotencia estricta).

Procedimientos versus memoria curada

Las habilidades responden cómo ejecutar un flujo de trabajo; la memoria central acotada de Hermes responde qué se ha acordado ya sobre el usuario y el proyecto. Una habilidad se carga cuando la tarea coincide con su descripción; MEMORY.md y USER.md permanecen en el prompt como una capa pequeña y curada de hechos. Los dos mecanismos se apilan en lugar de competir, y el panorama completo de instantáneas, límites y proveedores externos se expone en Sistema de Memoria del Asistente Hermes: Cómo Funciona Realmente la Memoria de IA Persistente.

Anatomía de un directorio de habilidades

En el disco, cada habilidad es una carpeta bajo ~/.hermes/skills/, a menudo anidada bajo una categoría como devops/ o research/. Hermes espera SKILL.md en el nivel inferior; todo lo demás es estructura opcional que agregas cuando las instrucciones de otro modo se extenderían sin control. El patrón habitual es references/ para tablas largas o documentación de proveedores, templates/ para esqueletos de salida, scripts/ para asistentes deterministas y assets/ para archivos estáticos que el agente no debería volver a obtener.

Ese diseño refleja cómo funciona la revelación progresiva en la práctica: el agente puede quedarse en el archivo principal hasta que realmente necesite un apéndice profundo. Mantener la prosa del “camino feliz” en SKILL.md y empujar los detalles poco usados a references/ es una de las formas más baratas de proteger los presupuestos de tokens.

Hermes también puede fusionar directorios de habilidades externos mediante skills.external_dirs en config.yaml. Esas rutas se escanean para descubrimiento, pero el agente sigue escribiendo a través de skill_manage en el árbol principal de ~/.hermes/skills/. Los nombres locales ocultan los externos, por lo que si “arreglas” una habilidad compartida en tu directorio de inicio, los compañeros que obtengan el mismo repositorio externo no verán tu edición hasta que eliminen o renombren la copia local, una fuente común de confusión del tipo “funciona en mi máquina”.

Frontmatter de SKILL.md que sobrevive a la revisión

El cuerpo de SKILL.md es Markdown; el bloque de apertura debe ser YAML válido entre delimitadores ---. Las habilidades reales acumulan ejemplos con cercas largas, por lo que los pequeños hábitos de Bloques de Código Markdown: Guía Completa con Sintaxis, Idiomas y Ejemplos—etiquetas de idioma consistentes, extractos legibles, cercas ajustadas—mantienen los archivos grandes mantenibles para humanos y ligeramente más fáciles de escanear para el modelo.

Los campos requeridos son name y description. El name se convierte en la ruta slash y la clave del índice; permanece en minúsculas con guiones y debe respetar el límite de longitud documentado. La description es la única prosa por la que muchas sesiones pagan en el nivel cero, por lo que debería leerse como un resultado de búsqueda o cadena de enrutamiento (“cuando los respaldos se ven obsoletos, verificar el archivo de respaldo más reciente y su suma de comprobación”), no como el primer párrafo de un artículo de blog.

Las claves de nivel superior opcionales como version, author y license ayudan al empaquetado del hub y las auditorías. La lista platforms (macos, linux, windows) es más afilada de lo que parece: cuando se establece, Hermes omite la habilidad por completo en hosts que no coinciden, por lo que una habilidad que “funciona en mi Mac” puede desaparecer en CI de Linux sin mensaje de error más allá de una lista de habilidades más corta.

Los controles específicos de Hermes viven bajo metadata.hermes: tags, related_skills y los campos de visibilidad condicional en la siguiente sección. required_environment_variables declara secretos que deberían caer en .env y pasar a los sandbox; required_credential_files cubre archivos de tokens OAuth y otras credenciales en disco que deben montarse en Docker o Modal; metadata.hermes.config declara preferencias no secretas almacenadas bajo skills.config en config.yaml.

La documentación oficial enfatiza la disciplina de tamaño por una razón. Recorta la description a su presupuesto, prioriza el procedimiento y empuja notas históricas o matrices de opciones gigantes a references/ para que una skill_view parcial aún le dé al agente algo accionable.

A continuación se muestra un SKILL.md mínimo que puedes colocar en ~/.hermes/skills/devops/backup-check/SKILL.md (o cualquier carpeta de categoría) e iterar desde allí.

---
name: backup-check
description: Verificar que existen los archivos de respaldo nocturnos, no están vacíos y pasan una rápida comprobación de suma de verificación en el archivo más reciente.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Ruta absoluta al directorio que contiene los archivos de respaldo
        default: "/var/backups"
        prompt: Directorio de archivos de respaldo (ruta absoluta)
---

# Comprobación rápida de archivos de respaldo

## Cuándo usar

Usar cuando el usuario pregunte para confirmar que se ejecutaron los respaldos, para auditar el archivo de respaldo más reciente en el disco, o para detectar archivos de respaldo vacíos u obsoletos antes de una prueba de restauración.

## Referencia rápida

- El directorio de archivos de respaldo más reciente se configura bajo `skills.config.backup_check.archive_dir` (se establece mediante `hermes config migrate` si se declara en metadatos).
- La comprobación predeterminada usa `ls` por mtime y `test -s` para archivos no vacíos.

## Procedimiento

1. Resolver el directorio de archivos de respaldo desde la configuración de la habilidad o preguntar al usuario una vez si no está establecido.
2. Listar el archivo modificado más recientemente que coincida con el patrón esperado (por ejemplo `*.tar.zst`).
3. Confirmar que el archivo existe, no está vacío y registrar su ruta y tamaño para la respuesta.
4. Si existe un archivo de suma de comprobación junto al archivo de respaldo, verificarlo con la herramienta documentada (por ejemplo `sha256sum -c`).

## Trampas

- Los archivos vacíos aún pueden tener un mtime reciente si un trabajo fallido tocó la ruta; siempre verifica el tamaño.
- Las rutas relativas fallan cuando el cwd de la terminal no es el host de respaldo; usa rutas absolutas en la configuración.

## Verificación

El usuario debería ver la ruta del archivo de respaldo más reciente, el tamaño en bytes y ya sea una línea de suma de comprobación OK o una nota explícita de que no se encontró un acompañante `.sha256`.

Revelación progresiva en la práctica

La revelación progresiva es la diferencia entre una biblioteca de habilidades que se siente ágil y una que quema miles de tokens antes del primer mensaje del usuario. Hermes recorre tres pasos conceptuales: un catálogo compacto (nombres y descripciones cortas), el SKILL.md completo cuando la tarea coincide, y—solo si es necesario—un fragmento de un archivo de referencia mediante rutas skill_view. Asume que el nivel cero es todo lo que el modelo leerá hasta que se comprometa explícitamente; cada frase en la description y la primera pantalla de texto del cuerpo deberían ayudar al enrutamiento, no a la narración.

Un esquema práctico que sobrevive a cargas parciales es Cuándo usar (disparadores en lenguaje claro), Referencia rápida (comandos, variables de entorno, rutas de archivos), Procedimiento (pasos ordenados que el agente no debería improvisar), Trampas (modos de fallo conocidos) y Verificación (cómo se ve “verde”). La historia narrativa, volcados de registros de cambios de proveedores y tablas de opciones de veinte filas pertenecen a references/ con encabezados estables para que el agente pueda extraer una sola sección.

Cuando se activa una habilidad, Hermes puede reescribir ${HERMES_SKILL_DIR} y ${HERMES_SESSION_ID} en el cuerpo para que las líneas de shell apunten a la carpeta instalada sin rutas construidas a mano. Los fragmentos de shell en línea opcionales (!cmd``) pueden inyectar contexto fresco (rama actual, espacio en disco), pero se ejecutan en el host y permanecen deshabilitados a menos que skills.inline_shell esté activado; trata esa bandera como un límite de confianza para toda la fuente de la habilidad, no como un interruptor de conveniencia.

Activación condicional e higiene del prompt

Las habilidades pueden mostrarse u ocultarse según qué conjuntos de herramientas o herramientas existan en la sesión actual. requires_toolsets / requires_tools condicionan una habilidad detrás de capacidades que deben estar presentes; fallback_for_toolsets / fallback_for_tools muestran una ruta más barata o local cuando falta una integración premium—el respaldo de DuckDuckGo cuando no se configura una API de búsqueda web de pago es el ejemplo canónico.

Estos predicados moldean directamente el ruido del prompt. Una regla requires_* excesivamente estricta oculta una habilidad a los nuevos usuarios que aún no han terminado la configuración de hermes tools; una regla fallback_for_* demasiado laxa duplica la mitad de tu biblioteca cada vez que alguien omite una clave de API. El término medio útil es nombrar prerrequisitos reales, probar con hermes chat --toolsets skills y alternar claves o conjuntos de herramientas intencionalmente mientras observas si la lista de habilidades respira como esperas.

Secretos, configuración y archivos de credenciales

Los secretos deben declararse en required_environment_variables. Hermes puede solicitarlos cuando una habilidad se carga en la CLI local, persistir valores en .env y pasarlos a los sandbox terminal y execute_code sin transmitir el secreto crudo de vuelta al transcript del modelo. Las superficies de chat remoto se niegan a recopilar claves en línea y en cambio dirigen a las personas a hermes setup o ediciones manuales de .env; autoriza tu texto de habilidad para que coincida con ese comportamiento (dile a los usuarios que se requiere una clave, no que la peguen en Telegram).

Las preferencias no secretas—rutas predeterminadas, nombres de organización, interruptores de características—pertenecen a metadata.hermes.config. Los valores se resuelven en skills.config dentro de config.yaml, aparecen en hermes config show y llegan al mensaje de la habilidad como hechos resueltos para que el modelo no necesite abrir tu archivo de configuración en medio de la tarea.

Las credenciales con forma de archivo (JSON de token OAuth, claves de cuenta de servicio) mapean a required_credential_files. Cuando esos archivos existen, Hermes puede montar-los de forma vinculada en Docker o sincronizarlos en trabajos de Modal; declararlos por adelantado evita el clásico abismo de “el script funciona localmente, muere en el sandbox”.

Scripts de soporte y dependencias

La guía de upstream impulsa a los autores hacia dependencias aburridas: Python stdlib, curl y las propias herramientas de Hermes (web_extract, read_file, terminal). Esto es menos sobre pureza que sobre reproducibilidad—cada pip install extra es otro fallo silencioso cuando el agente se ejecuta en un contenedor limpio.

Cuando el análisis JSON o XML es complicado, un script corto bajo scripts/ más una ruta ${HERMES_SKILL_DIR} supera pedirle al modelo que rederive analizadores en cada ejecución. Si realmente necesitas un paquete, establece el comando de instalación en Procedimiento, repite el síntoma de fallo en Trampas y da un comando de Verificación que falle ruidosamente cuando falte la dependencia.

Publicación, instalaciones en el hub y confianza

Las habilidades comunitarias pasan por el Hub de Habilidades y las otras rutas de descubrimiento que enumera la guía del usuario—habilidades oficiales opcionales, slugs de GitHub, entradas de skills.sh, índices .well-known y URLs crudas de SKILL.md. Las instalaciones se escanean en busca de exfiltración obvia, inyección y patrones destructivos; los niveles de confianza van desde integrado (builtin) hasta comunidad, y algunos hallazgos solo se aclaran con --force mientras que los peores casos permanecen bloqueados por completo.

La forma del archivo SKILL.md no es específica de Hermes; los asistentes centrados en IDE usan la misma idea de carga progresiva con descubrimiento y disparadores diferentes. Habilidades de Claude y SKILL.md para Desarrolladores: VS Code, JetBrains, Cursor es una lectura de contraste útil—la disciplina del frontmatter y “cargar solo cuando sea relevante” se trasladan, incluso cuando el instalador y el cableado de comandos slash difieren.

Los despliegues a nivel de organización suelen emparejar un tap privado o repositorio Git compartido con external_dirs para compartir en solo lectura, mientras mantienen la copia escribible por el agente bajo cada perfil cuando skill_manage está permitido para mutar habilidades en su lugar.

Solución de problemas y optimización

Cuando una habilidad se comporta mal, sigue esta lista de verificación antes de reescribir la prosa.

• Visibilidad — Confirma los predicados platforms, requires_* y fallback_for_*. Una habilidad que “funciona en mi Mac” pero no en CI de Linux a menudo es un guardián de plataforma.
• Colisiones de nombre — Los nombres duplicados entre directorios locales y externos siguen la precedencia local. Renombra o usa espacios de nombres agresivamente.
• Diseño de descubrimiento — Un SKILL.md mal colocado o una carpeta de categoría incorrecta pueden eliminar la habilidad del índice por completo.
• Carga de tokens — Si las sesiones se sienten lentas, acorta las descripciones de nivel cero, mueve la profundidad a references/ y desduplica tablas gigantes.
• Ediciones del agente — Hermes puede crear, parchear o eliminar habilidades mediante skill_manage. Trata las habilidades valiosas como código: revisa diferencias, exporta instantáneas y restablece las habilidades empaquetadas deliberadamente cuando las actualizaciones se desvían.

Un ciclo de regresión ajustado supera a volver a leer todo el archivo: hermes chat --toolsets skills -q "Usa el flujo de trabajo <skill> para <tarea concreta>" debería mostrar al agente extrayendo el nivel de revelación correcto antes de improvisar. Si nunca invoca skill_view, tu texto Cuándo usar o description probablemente no coincide con cómo las personas formulan las solicitudes.

Las referencias oficiales permanecen autoritarias para cambios de comportamiento: la guía de usuario del Sistema de Habilidades para semánticas de tiempo de ejecución, Creando Habilidades para reglas orientadas al autor, el Catálogo de Habilidades Empaquetadas para ejemplos de copiar y pegar, y la especificación de agentskills.io para el formato de archivo compartido con el que Hermes se alinea.