Creación de habilidades para Hermes Agent — Estructura y mejores prácticas de SKILL.md

Hermes Agent trata las habilidades como la forma predeterminada para enseñar flujos de trabajo repetibles. La documentación oficial las describe como documentos de conocimiento bajo demanda alineados con el formato abierto de agentskills.io, cargados mediante divulgación progresiva, de modo que el modelo ve primero un índice pequeño y solo recupera las instrucciones completas cuando una tarea realmente las necesita.

La autoría se trata menos de una redacción ingeniosa que de empaquetar: le estás indicando al runtime 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, las carpetas de soporte, las reglas de visibilidad y la distinción entre configuraciones secretas y no secretas: los detalles que determinan si una habilidad aparece en los comandos /slash, sobrevive a una instalación del hub o desaparece silenciosamente en CI.

Hermes se encuentra 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 una única interfaz de chat. Las rutas de instalación, la conexión de proveedores, el comportamiento de la pasarela y la disposición de ~/.hermes se detallan en la guía Asistente de IA Hermes: Instalación, Configuración, Flujo de Trabajo y Solución de Problemas; la ergonomía diaria de shell —hermes skills, perfiles, pasarela, memoria— es más fácil de consultar en la Hoja de trucos CLI del Agente Hermes — comandos, banderas y accesos directos slash. En implementaciones reales, las habilidades heredan aislamiento de los perfiles (configuración, secretos, memorias y árboles de habilidades separados). Habilidades del Asistente de IA Hermes para Implementaciones Reales de Producción argumenta tratar esos perfiles —no archivos markdown individuales— como la unidad de propiedad; tenlo en cuenta cuando nombres habilidades y decidas qué pertenece a external_dirs compartidos versus un único perfil.

¿Habilidad o herramienta?

La orientación oficial es directa. Usa una habilidad cuando la capacidad consiste principalmente en instrucciones en prosa más comandos shell y herramientas que Hermes ya expone: envolver un CLI, manejar git, llamar a curl o usar web_extract para recuperaciones estructuradas. Usa una herramienta cuando necesitas una integración estrecha para claves de API y flujos de autenticación, manejo determinista de binarios, 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 comenzar con una habilidad y luego promover solo el núcleo frágil a herramienta una vez que los modos de fallo son evidentes (bucles de actualización de autenticación, analizadores binarios, idempotencia estricta). Para la pregunta arquitectónica más amplia de cuándo usar una Habilidad de Agente versus un servidor MCP —especialmente en torno a credenciales, estado en vivo y escrituras transaccionales— consulta nuestro marco de decisión Habilidades de Agente vs Servidores MCP.

Procedimientos versus memoria curada

Las habilidades responden al cómo ejecutar un flujo de trabajo; la memoria central acotada de Hermes responde al 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 detalla en Sistema de Memoria del Agente Hermes: Cómo Funciona Realmente la Memoria Persistente de IA.

Anatomía de un directorio de habilidad

En disco, cada habilidad es una carpeta bajo ~/.hermes/skills/, a menudo anidada bajo una categoría como devops/ o investigación/. Hermes espera SKILL.md en la hoja; todo lo demás es estructura opcional que agregas cuando las instrucciones de otro modo se extenderían. El patrón habitual es referencias/ para tablas largas o documentación del proveedor, plantillas/ para esqueletos de salida, scripts/ para asistentes deterministas y activos/ para archivos estáticos que el agente no debería volver a recuperar.

Esa disposición refleja cómo funciona la divulgación progresiva en la práctica: el agente puede permanecer en el archivo principal hasta que realmente necesite un apéndice profundo. Mantener la prosa del “camino feliz” en SKILL.md y empujar detalles de uso infrecuente a referencias/ es una de las formas más baratas de proteger los presupuestos de tokens.

Hermes también puede fusionar directorios externos de habilidades a través de skills.external_dirs en config.yaml. Esas rutas se escanean para descubrimiento, pero el agente aún escribe 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, tus compañeros que extraigan el mismo repositorio externo no verán tu edición hasta que eliminen o renombrén 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 inicial debe ser YAML válido entre delimitadores ---. Las habilidades reales acumulan ejemplos largos entre cercas, por lo que los pequeños hábitos de Bloques de Código en Markdown: Guía Completa con Sintaxis, Lenguajes y Ejemplos —etiquetas de lenguaje consistentes, extractos legibles, cercas ajustadas— mantienen archivos grandes mantenibles para humanos y ligeramente más fáciles para el modelo de escanear.

Los campos requeridos son name y description. El name se convierte en la ruta slash y clave del índice; permanece en minúsculas con guiones y debe respetar el límite de longitud documentado. La description es la única prosa 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 las copias de seguridad parecen desactualizadas, verifica el último archivo y su checksum”), no como el primer párrafo de una publicación de blog.

Claves opcionales de nivel superior como version, author y license ayudan al empaquetado del hub y 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 no coincidentes, razón por la cual 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.

Las perillas específicas 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 llegar a .env y pasar a sandboxes; 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 enormes de opciones a referencias/ 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: Verifica que existan los archivos de copia de seguridad nocturna, que no estén vacíos y que pasen una verificación rápida de checksum en el último archivo.
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 copia de seguridad
        default: "/var/backups"
        prompt: Directorio de archivos de copia de seguridad (ruta absoluta)
---

# Verificación rápida de archivos de copia de seguridad

## Cuándo usar

Usa cuando el usuario pide confirmar que se ejecutaron copias de seguridad, auditar el último archivo en disco o detectar archivos vacíos o desactualizados antes de un ejercicio de restauración.

## Referencia rápida

- El directorio del último archivo está configurado bajo `skills.config.backup_check.archive_dir` (establece mediante `hermes config migrate` si se declara en metadatos).
- La verificación predeterminada usa `ls` por mtime y `test -s` para archivos no vacíos.

## Procedimiento

1. Resuelve el directorio de archivos desde la configuración de la habilidad o pregunta al usuario una vez si no está establecido.
2. Lista el archivo más recientemente modificado que coincida con el patrón esperado (por ejemplo `*.tar.zst`).
3. Confirma que el archivo existe, no está vacío y registra su ruta y tamaño para la respuesta.
4. Si existe un archivo de checksum junto al archivo, verifícalo 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 se rompen cuando el cwd del terminal no es el host de copia de seguridad; usa rutas absolutas en la configuración.

## Verificación

El usuario debería ver la ruta del último archivo, su tamaño en bytes y ya sea una línea de checksum OK o una nota explícita de que no se encontró un acompañante `.sha256`.

Divulgación progresiva en la práctica

La divulgació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— una porción de un archivo de referencia a través de rutas skill_view. Asume que el nivel cero es todo lo que el modelo leerá hasta que se comprometa explícitamente; cada oración en la description y la primera pantalla de texto del cuerpo debería ayudar al enrutamiento, no contar historias.

Un esquema práctico que sobrevive a cargas parciales es Cuándo usar (disparadores en lenguaje sencillo), 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, los volcados de registro de cambios del proveedor y las tablas de opciones de veinte filas pertenecen a referencias/ con encabezados estables para que el agente pueda extraer una sola sección.

Cuando una habilidad se activa, 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 manualmente. Los fragmentos opcionales de shell en línea (!cmd``) pueden inyectar contexto fresco (rama actual, espacio libre 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é toolsets o herramientas existan en la sesión actual. requires_toolsets / requires_tools bloquea una habilidad detrás de capacidades que deben estar presentes; fallback_for_toolsets / fallback_for_tools muestra un camino más barato 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.

Estas predeterminadas moldean directamente el ruido del prompt. Una regla requires_* demasiado estricta oculta una habilidad a nuevos usuarios que aún no han completado 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 punto medio útil es nombrar prerrequisitos reales, probar con hermes chat --toolsets skills y alternar claves o toolsets deliberadamente mientras observas si la lista de habilidades respira como esperas.

Secretos, configuración y archivos de credenciales

Los secretos deberían declararse en required_environment_variables. Hermes puede solicitarlos cuando una habilidad se carga en el CLI local, persistir valores en .env y pasarlos a sandboxes de 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 —redacta 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 a mitad de 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 montarlos por bind-mount en Docker o sincronizarlos en trabajos de Modal; declararlos de antemano evita la brecha clásica “el script funciona localmente, muere en sandbox”.

Scripts y dependencias de soporte

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

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

Publicación, instalaciones del hub y confianza

Las habilidades comunitarias se mueven a través del Skills Hub y las otras rutas de descubrimiento que enumera la guía de usuario —habilidades opcionales oficiales, slugs de GitHub, entradas 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 hasta comunitario, y algunos hallazgos solo se limpian 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 mantienen, incluso cuando el instalador y el cableado de comandos slash difieren.

Los despliegues en toda la organización suelen emparejar un tap privado o repositorio Git compartido con external_dirs para compartir de solo lectura, mientras se mantiene la copia escribible por agente bajo cada perfil cuando skill_manage está permitido mutar habilidades in situ.

Solución de problemas y optimización

Cuando una habilidad se comporta mal, recorre esta lista antes de reescribir prosa.

• Visibilidad — Confirma las predeterminadas 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 namespacia agresivamente.
• Disposición de descubrimiento — Un SKILL.md mal ubicado o una carpeta de categoría incorrecta puede hacer que la habilidad caiga por completo del índice.
• Carga de tokens — Si las sesiones se sienten lentas, acorta las descripciones de nivel cero, mueve la profundidad a referencias/ y deduplica tablas enormes.
• Ediciones del agente — Hermes puede crear, parchear o eliminar habilidades a través de skill_manage. Trata las habilidades valiosas como código: revisa diffs, exporta instantáneas y restablece habilidades integradas deliberadamente cuando las actualizaciones derivan.

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

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