Cómo crear una habilidad de agente desde un fallo real

Escriba su propia habilidad de agente a partir de un fallo real

La mejor forma de escribir su propia habilidad de agente es extraerla de un fallo real. Busque una tarea que su agente de programación haya hecho mal dos veces, anote la corrección que escribió en ambas ocasiones y guarde esa corrección como un archivo `SKILL.md` que el agente pueda cargar por sí mismo. Después de eso, todo es mecánico: la estructura de archivos y la única línea que determina si la habilidad llega a activarse.

El orden es importante. Una habilidad escrita a partir de la imaginación documenta un problema que nunca tuvo y sigue consumiendo contexto en cada sesión. Una habilidad extraída de un fallo que observó incluye su propia prueba: vuelva a solicitar lo mismo y compruebe si el agente lo hace bien esta vez. Si el formato es nuevo para usted, lea primero qué son las habilidades de agente y cómo las carga un agente y después vuelva para escribir una.

Empiece por una tarea que el agente haya hecho mal dos veces

Una vez puede ser casualidad. Dos veces forman un patrón, y un patrón merece un archivo.

Este es un fallo que se repite en servidores reales. Pide al agente que añada un bloque de reverse proxy a nginx. Edita /etc/nginx/conf.d/app.conf y después ejecuta sudo systemctl restart nginx. La edición contiene un error tipográfico, por lo que nginx no puede iniciarse y el sitio queda fuera de servicio hasta que lo corrija:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Corríjalo en el chat. Pruebe la configuración con sudo nginx -t antes de tocar el servicio y aplíquelo después con reload en lugar de restart. Una semana más tarde, durante otra tarea, se produce el mismo error. Esa segunda vez es la señal.

Anote dos cosas mientras el fallo siga delante de usted: la solicitud que escribió y la corrección que dio, con las palabras que utilizó. Esas dos líneas se convierten en la skill. La solicitud indica qué debe coincidir con el activador. La corrección constituye todo el contenido.

La propia guía de autoría de Anthropic recomienda empezar por aquí. Ejecute el agente en tareas representativas sin ninguna skill, registre dónde falla y escriba después las instrucciones mínimas que corrijan esos fallos. Los fallos son la especificación. Por eso, si una skill no se puede relacionar con ninguno de ellos, normalmente es una skill que nadie necesitaba.

Como ejemplo práctico de la misma destilación, Ponytail convierte un fallo repetido, cuando un agente reescribe mucho más de lo solicitado, en una skill que puede leer de principio a fin antes de escribir la suya.

La anatomía de una skill

Una skill es un directorio que contiene un archivo obligatorio.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md comienza con un bloque de frontmatter: varios ajustes escritos en YAML, el mismo formato de configuración que usan los archivos de Docker Compose, entre los marcadores ---. Después incluye las instrucciones en markdown. Esta es la skill completa del fallo anterior.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

El archivo tiene menos de veinte líneas y es una skill completa. Sus partes son:

• name: hasta 64 caracteres, sólo letras minúsculas, dígitos y guiones. No puede contener las palabras claude ni anthropic. En una skill personal o de proyecto, sólo es la etiqueta visible. El comando que se escribe procede del nombre del directorio, por lo que esta responde a /nginx-config-changes.
• description: indica qué hace la skill y cuándo se debe usar, con un máximo de 1,024 caracteres. Esta línea realiza el trabajo principal; la siguiente sección trata exclusivamente de este campo.
• El cuerpo: las instrucciones, que sólo se cargan cuando la skill se activa.
• reference/: archivos adicionales que el agente lee cuando los necesita. Enlázalos desde SKILL.md y mantén los enlaces a un solo nivel, porque un archivo referenciado desde otro archivo referenciado suele leerse sólo parcialmente.
• scripts/: archivos que el agente ejecuta en lugar de leer. Sólo su salida consume contexto, por lo que un script de 300 líneas resulta barato.

Una skill se convierte en un diseño completo cuando el comportamiento que corrige es lo bastante persistente como para necesitarlo, y la skill unlazy emplea ese espacio en un árbol de profundidad, un conjunto de archivos de control y un contrato PLAN.md para impedir que un agente anuncie que ha terminado mientras ramas enteras del trabajo siguen sin tocar.

La ubicación del directorio determina quién puede usar la skill.

• .claude/skills/<name>/SKILL.md en el repositorio: sólo este proyecto, y se distribuye a todas las personas que clonen el repositorio.
• ~/.claude/skills/<name>/SKILL.md: todos los proyectos de tu equipo, pero ningún proyecto de otros equipos.
• <plugin>/skills/<name>/SKILL.md: se incluye en un plugin y está disponible donde esté habilitado ese plugin.

Crea una con mkdir -p .claude/skills/nginx-config-changes y escribe el archivo. Claude Code supervisa estos directorios, por lo que editar una skill existente surte efecto en la sesión en ejecución. Si creas un directorio de skills de nivel superior que no existía cuando comenzó la sesión, debes reiniciar, porque al iniciar la sesión no había nada que supervisar.

El campo de descripción es la línea con mayor impacto del archivo

Al iniciarse, el agente carga name y description de cada skill disponible en su contexto. No carga el contenido. Cuando llega su solicitud, esa línea es la única base para decidir si este skill es relevante. Por tanto, un contenido perfecto detrás de una descripción vaga nunca se lee.

Escriba la descripción en tercera persona. «Prueba y recarga nginx de forma segura» funciona. «Puedo ayudarle con nginx» no funciona, porque el texto se inyecta en el prompt del sistema y la primera persona se interpreta como si el modelo hablara de sí mismo.

Incluya dos elementos: qué hace el skill y en qué condición se aplica. Coloque primero el caso de uso importante, porque Claude Code trunca la entrada del listado a 1,536 caracteres. Existe un campo opcional when_to_use para frases de activación adicionales y solicitudes de ejemplo. Este campo se añade a la descripción dentro del mismo límite.

Después, use las palabras que realmente escribirá. description: Helps with nginx no coincide con nada porque nadie escribe «ayuda con». La versión anterior menciona /etc/nginx, server block, reverse proxy y TLS (transport layer security) certificate path, que constituyen aproximadamente el vocabulario de cualquier solicitud que debería activarlo.

Esta es la prueba para una descripción. Entregue esa única línea a alguien que nunca haya visto el contenido, junto con la solicitud que está a punto de escribir, y pregúntele si el skill se aplica. Si no puede determinarlo, el modelo tampoco podrá.

Mantenga el cuerpo breve, porque permanece en el contexto

Cuando se invoca una skill, su contenido renderizado entra en la conversación como un mensaje y permanece allí durante el resto de la sesión. Claude Code no vuelve a leer el archivo en los turnos posteriores. Cada línea que escriba tiene un coste para toda la sesión, no sólo para una respuesta.

Anthropic recomienda mantener SKILL.md por debajo de 500 líneas y trasladar los detalles a archivos independientes. La compactación muestra por qué ese número no es arbitrario. Cuando la conversación se resume para liberar contexto, Claude Code vuelve a adjuntar la invocación más reciente de cada skill, conserva sólo los primeros 5,000 tokens de cada una y completa un presupuesto combinado de 25,000 tokens empezando por la skill invocada más recientemente. Una skill extensa se corta a mitad. Varias skills extensas pueden expulsarse entre sí por completo.

Por tanto, escriba sólo lo que el modelo no sabe ya. Sabe qué es nginx y qué hace un reverse proxy. No sabe la regla interna sobre reload por encima de restart, y esa regla es el único motivo por el que existe este archivo.

Si la skill indica al agente que ejecute un script incluido, especifique la ruta con ${CLAUDE_SKILL_DIR} para que se resuelva independientemente de dónde esté instalada la skill, y autorice previamente el mismo comando para que la ejecución no se detenga ante una solicitud de permisos.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

La autorización cubre el turno que invocó la skill y se elimina cuando envía el siguiente mensaje, por lo que no se convierte silenciosamente en un permiso permanente.

Cómo demostrar que la skill se activa

Observar que se carga una skill confirma que el agente la ha encontrado. No confirma que la respuesta haya cambiado. Compruebe ambas cosas y hágalo en una sesión nueva, porque la sesión en la que escribió la skill ya contiene todo lo que indicó durante su creación. Ese contexto residual oculta las carencias del archivo.

1. Inicie una sesión nueva con claude en el proyecto.
2. Escriba la solicitud como lo haría durante una jornada de trabajo normal, con sus propias palabras y sin mencionar la skill.
3. Compruebe si se produce la invocación. Si la skill no se activa, corrija la descripción. El cuerpo todavía no es el problema.
4. Invoque la skill manualmente con /nginx-config-changes como control. Si el comportamiento es correcto al invocarla manualmente e incorrecto al invocarla mediante la solicitud, el problema está en el disparador y no en las instrucciones.
5. Ejecute la misma solicitud con la skill desactivada y compare las dos respuestas. En el menú /skills, seleccione la skill, pulse Space para cambiar su estado a off y, después, pulse Enter para guardar. Esto escribe una entrada skillOverrides en .claude/settings.local.json. Cuando termine, vuelva a pulsar Space para cambiarla a on.
6. Escriba un par de solicitudes que no deberían activar la skill y compruebe que permanece inactiva.

Para automatizar este ciclo, instale el plugin skill-creator desde el marketplace oficial.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Si la salida de la instalación indica Run /reload-plugins to activate., ejecute ese comando. Después, pida a Claude que evalúe la skill por su nombre. El plugin almacena los casos de prueba en evals/evals.json dentro del directorio de la skill y ejecuta cada caso en su propio subagente, por lo que cada ejecución comienza con un contexto limpio. Después escribe una comparación entre la ejecución con la skill y la ejecución sin ella. Esa es la cifra válida: la mejora de la tasa de éxito medida frente a los tokens y el tiempo que consume la skill.

Una skill también puede incluir sus propias pruebas, en lugar de dejar esta tarea a una ejecución de evaluación independiente. Eso es lo que hace la skill Old Coder cuando hace que el agente devuelva un informe de evidencias que usted puede volver a ejecutar.

Modo de fallo: la skill nunca se activa

Escribe la solicitud, el agente vuelve a hacer lo incorrecto y no aparece ninguna línea de la skill. Comprueba estos puntos en orden.

• La descripción indica qué hace la skill, pero nunca cuándo se debe usar. Por eso, nada de tu solicitud coincide con ella.
• La descripción evita las palabras que escribes. Si dices "nginx", la descripción debe incluir nginx.
• disable-model-invocation: true está definido en el frontmatter. Esto mantiene la descripción completamente fuera del contexto del modelo y deja la skill invocable sólo mediante /name.
• Un patrón paths en el frontmatter limita la activación a los archivos que coincidan. El archivo en el que trabajas no coincide.
• La skill está en un directorio .claude/skills/ anidado bajo tu directorio inicial. Esas skills sólo se cargan después de que el agente lea o edite un archivo dentro de ese subdirectorio. Hasta entonces, la skill no está disponible.

Modo de fallo: la habilidad se activa constantemente

El problema opuesto es una descripción tan amplia que la habilidad se activa durante tareas no relacionadas. «Usar al trabajar en el servidor» coincide con casi cualquier solicitud de un repositorio de servidor. El cuerpo se carga durante tareas en las que no puede ayudar y permanece en el contexto durante el resto de la sesión.

Limite la descripción a la condición relevante y especifique los archivos o comandos que cubre. Añada un patrón global paths cuando la habilidad sólo se aplique a determinados archivos. Para cualquier operación con efectos secundarios, como un despliegue o una confirmación, establezca disable-model-invocation: true e invoque la habilidad manualmente con /name, para que el agente nunca decida por su cuenta que es un buen momento para realizar el despliegue.

Modo de fallo: la habilidad debe estar en el archivo de reglas

Un archivo de reglas como CLAUDE.md o AGENTS.md se carga al inicio de cada sesión y se aplica a todas las tareas. El contenido de una habilidad se carga sólo cuando se activa esa habilidad. La frecuencia es el criterio principal. Un hecho que se aplica a todas las tareas del repositorio, como el gestor de paquetes que se utiliza, debe estar en el archivo de reglas. Un procedimiento que se aplica a una parte reducida de las tareas, como la regla de nginx anterior, debe estar en una habilidad, donde no tiene ningún coste los días en que nadie modifica nginx.

El fallo real consiste en colocarlo en ambos sitios. Las dos copias se desincronizan y, cuando el agente hace algo incorrecto, no se puede saber qué copia siguió. Elija una única ubicación para cada instrucción. Si una regla ya está exactamente en una de las dos ubicaciones y aun así se omite, se trata de un problema diferente. Antes de moverla a una habilidad con la esperanza de que el traslado lo solucione, conviene revisar los mecanismos que hacen que una instrucción se ignore. La frontera entre habilidades, servidores MCP y archivos de reglas permite abordar los casos más complejos, incluido cuándo la respuesta correcta es un servidor MCP (model context protocol) que proporciona al agente una herramienta nueva en lugar de una instrucción nueva.

Compártela cuando haya demostrado su valor

Una habilidad que resiste una semana de trabajo real merece incorporarse al repositorio. Las habilidades del proyecto en .claude/skills/ se revisan como código y llegan con el repositorio, de modo que un compañero que lo clone obtiene tu corrección sin ningún paso de configuración. Mover una habilidad entre repositorios sin copiarla y pegarla es otro problema, que se trata en cómo compartir habilidades de agente entre repositorios.

Hay una consideración de portabilidad. Claude Code acepta una lista extensa de campos de frontmatter, pero el estándar Agent Skills sólo permite seis: name, description, license, compatibility, metadata y allowed-tools. Si subes una habilidad a claude.ai o la empaquetas para la Skills API con cualquier otro elemento en el frontmatter, falla directamente en lugar de ignorar el campo:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Limítate a esos seis campos y el mismo archivo se cargará en Claude Code y en cualquier otra herramienta que lea el estándar. El entorno donde se cargue seguirá determinando lo que puede hacer, porque Cowork se ejecuta en un sandbox de Anthropic, mientras que Claude Code se ejecuta en tu propia máquina o VPS. Por eso merece la pena llevar la habilidad de nginx anterior al checkout de un compañero, pero no sirve en un sandbox que no pueda acceder al servidor. Redactar las instrucciones para que sigan funcionando con otro modelo es una tarea independiente, que se trata en cómo escribir habilidades compatibles con cualquier modelo.

FAQ

¿Qué extensión debe tener un archivo SKILL.md?

Manténgalo por debajo de 500 líneas y tenga en cuenta que la mayoría de las skills útiles son mucho más breves. El cuerpo se incorpora a la conversación cuando se invoca la skill y permanece allí durante el resto de la sesión. Por tanto, cada línea supone un coste recurrente, no un coste puntual. Mueva el material de referencia extenso a archivos independientes dentro del directorio de la skill y enlácelo desde SKILL.md, con un solo nivel de profundidad, para que el agente lo lea sólo cuando lo necesite. Los scripts incluidos se ejecutan en lugar de leerse, por lo que sólo generan el coste de su salida.

¿Por qué mi skill nunca se activa?

La descripción suele ser la causa, porque es la única parte de la skill que está en el contexto cuando el modelo decide. Asegúrese de que indique cuándo debe usarse la skill, no sólo qué hace, y de que contenga las palabras que realmente escribe en sus solicitudes. Si la descripción parece correcta, compruebe el frontmatter en busca de disable-model-invocation: true, que oculta completamente la skill al modelo, y de un glob paths que la limite a archivos que no está modificando. Una skill ubicada en un directorio .claude/skills/ anidado bajo el directorio inicial es otra posible causa: sólo se carga después de que el agente lea o edite un archivo de ese subdirectorio.

¿Debe ser una skill o una línea en mi archivo de reglas?

Pregúntese a cuántas de sus tareas se aplica. Un archivo de reglas se carga en todas las sesiones, por lo que debe contener datos válidos para cualquier tarea, como el gestor de paquetes o la convención de nombres de ramas. Una skill sólo se carga cuando se activa, por lo que es el lugar adecuado para un procedimiento que se aplica a una parte reducida de las tareas. No escriba la misma instrucción en ambos lugares, porque las dos copias acabarán divergiendo y perderá la capacidad de saber cuál siguió el agente.

¿Cómo sé si una skill realmente ayudó?

Compárela con una línea base. Reúna varias solicitudes reales, ejecute cada una en una sesión nueva con la skill disponible y vuelva a ejecutarlas con la skill desactivada desde el menú /skills. Después, lea ambas respuestas una junto a la otra. Una sesión nueva es importante porque la conversación en la que escribió la skill todavía contiene sus explicaciones. Esto puede hacer que un archivo incompleto parezca completo. El plugin skill-creator ejecuta esta comparación por usted e informa de la tasa de aciertos junto al coste en tokens.

¿Puedo usar el mismo SKILL.md con otro agente?

Sí, siempre que se limite a los campos definidos por el estándar Agent Skills: name, description, license, compatibility, metadata y allowed-tools. Claude Code acepta muchos más campos y también admite funciones en el cuerpo, como la inyección de comandos de shell, que otras herramientas no ejecutan. Si carga una skill con un campo ajeno al estándar, se produce un error explícito que enumera las propiedades permitidas. Por tanto, decida pronto si la skill debe permanecer en Claude Code o si debe poder trasladarse.