Cómo crear una habilidad personalizada para un agente

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. Identifique una tarea en la que su agente de programación se haya equivocado dos veces, anote la corrección que introdujo en ambas ocasiones y guárdela como un archivo SKILL.md que el agente pueda cargar por sí mismo. Todo lo demás es mecánica: la estructura del archivo y la línea única que determina si la habilidad se ejecuta.

Ese orden es importante. Una habilidad escrita desde 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 usted presenció llega con su propia prueba adjunta: vuelva a preguntar lo mismo y observe si el agente acierta esta vez. Si el formato le resulta nuevo, lea primero qué son las habilidades de agente y cómo las carga un agente, y luego regrese para escribir una.

Comience desde una tarea que el agente haya realizado mal dos veces

Una vez es casualidad. Dos veces es un patrón, y un patrón merece un archivo.

He aquí un fallo que se repite en servidores reales. Usted le pide al agente que añada un bloque de proxy inverso a nginx. Este edita /etc/nginx/conf.d/app.conf y luego ejecuta sudo systemctl restart nginx. La edición contiene un error tipográfico, por lo que nginx se niega a arrancar y el sitio permanece caído hasta que usted lo soluciona:

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.

Usted lo corrige en el chat. Pruebe la configuración con sudo nginx -t antes de tocar el servicio y luego aplíquela con reload en lugar de restart. Una semana después, en una tarea diferente, el mismo error. Esa segunda vez es la señal.

Anote dos cosas mientras el fallo esté aún frente a usted: la solicitud que escribió y la corrección que proporcionó, con las palabras que utilizó. Esas dos líneas se convierten en la habilidad. La solicitud le indica qué debe coincidir con el desencadenante. La corrección es el contenido completo.

La propia guía de creación de Anthropic sitúa esto en primer lugar. Ejecute el agente en tareas representativas sin la habilidad, registre dónde falla y luego redacte las instrucciones mínimas que solucionen esos fallos. Los fallos son la especificación, por lo que una habilidad que no pueda rastrearse hasta uno de ellos suele ser una habilidad que nadie necesitaba.

Para ver un ejemplo práctico de esta misma destilación, Ponytail convierte un fallo repetido, un agente que reescribe mucho más de lo que usted pidió, en una habilidad que puede leer de principio a fin antes de escribir la suya propia.

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 metadatos, una serie de ajustes escritos en YAML (el mismo formato de configuración que utilizan los archivos de Docker Compose) entre marcadores ---, seguido de las instrucciones en formato markdown. A continuación se muestra la skill completa para el 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).

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

• name: hasta 64 caracteres, solo letras minúsculas, dígitos y guiones; no puede contener las palabras claude o anthropic. En una skill personal o de proyecto, esta es solo la etiqueta de visualización. El comando que usted escribe proviene del nombre del directorio, por lo que este responde a /nginx-config-changes.
• description: qué hace la skill y cuándo usarla, hasta 1.024 caracteres. Esta línea realiza el trabajo real, y la siguiente sección trata exclusivamente sobre esto.
• El cuerpo: las instrucciones, que se cargan solo cuando la skill se ejecuta.
• reference/: archivos adicionales que el agente lee bajo demanda. Enlácelos desde SKILL.md y mantenga los enlaces con un solo nivel de profundidad, ya que un archivo referenciado desde otro archivo referenciado a menudo solo se lee parcialmente.
• scripts/: archivos que el agente ejecuta en lugar de leer. Solo su salida consume contexto, por lo que un script de 300 líneas es económico.

La ubicación del directorio determina quién tiene acceso a la skill.

• .claude/skills/<name>/SKILL.md en el repositorio: solo para este proyecto, y se incluye para cualquiera que clone el repositorio.
• ~/.claude/skills/<name>/SKILL.md: para todos los proyectos en su máquina, y para nadie más.
• <plugin>/skills/<name>/SKILL.md: distribuida dentro de un plugin, disponible dondequiera que dicho plugin esté habilitado.

Cree una con mkdir -p .claude/skills/nginx-config-changes y escriba el archivo. Claude Code monitoriza estos directorios, por lo que editar una skill existente surte efecto dentro de la sesión en ejecución. Crear un directorio de skills de nivel superior que no existía cuando comenzó la sesión requiere un reinicio, ya que no había nada que monitorizar al iniciar la sesión.

El campo de descripción es la línea de mayor impacto en el archivo

Al iniciarse, el agente carga el name y el description de cada habilidad disponible en su contexto. No carga los cuerpos. Cuando llega su solicitud, esa única línea es la base completa para decidir si esta habilidad es relevante, por lo que un cuerpo perfecto detrás de una descripción vaga nunca será leído.

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

Incluya dos elementos en ella: qué hace la habilidad y la condición bajo la cual se aplica. Ponga el caso de uso importante primero, ya que Claude Code trunca la entrada del listado en 1,536 caracteres. Existe un campo opcional when_to_use para frases de activación adicionales y ejemplos de solicitudes, y se añade a la descripción bajo ese mismo límite.

Luego, utilice las palabras que realmente escribirá. description: Helps with nginx no coincide con nada, porque nadie escribe "ayuda con". La versión anterior nombra /etc/nginx, server block, reverse proxy y TLS (transport layer security) certificate path, que es aproximadamente el vocabulario de cualquier solicitud que debería activarla.

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

Mantenga el cuerpo pequeño, ya que permanece en el contexto

Cuando se invoca una habilidad, 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 turnos posteriores. Cada línea que escribe es un coste que paga por toda la sesión, no por una sola respuesta.

Anthropic recomienda mantener SKILL.md por debajo de 500 líneas y trasladar los detalles a archivos separados. La compactación explica 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 habilidad, conserva solo los primeros 5,000 tokens de cada una y completa un presupuesto combinado de 25,000 tokens comenzando por la habilidad invocada más recientemente. Una habilidad larga se corta a mitad de camino. Varias habilidades largas se desplazan entre sí por completo.

Por lo tanto, escriba solo lo que el modelo aún no sabe. Sabe qué es Nginx y qué hace un proxy inverso. No conoce su regla interna sobre reload sobre restart, y esa regla es la única razón por la que existe este archivo.

Si la habilidad le indica al agente que ejecute un script incluido, nombre la ruta con ${CLAUDE_SKILL_DIR} para que se resuelva dondequiera que esté instalada la habilidad, y preapruebe 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 concesión cubre el turno que invocó la habilidad y se borra cuando envía su siguiente mensaje, por lo que no se convierte silenciosamente en un permiso permanente.

Cómo verificar que la skill se ejecuta

Observar la carga de una skill indica que el agente la ha detectado. No confirma que la respuesta haya cambiado. Verifique ambos aspectos y hágalo en una sesión nueva, ya que la sesión donde redactó la skill conserva todo lo que escribió durante el proceso. 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 en un día de trabajo normal, con sus propias palabras y sin mencionar la skill.
3. Observe si se produce la invocación. Si la skill no se ejecuta, corrija la descripción. El cuerpo del mensaje aún no es el problema.
4. Invoque la skill manualmente con /nginx-config-changes como control. Un comportamiento correcto al invocarla manualmente frente a un comportamiento incorrecto al solicitarla confirma un problema de activación y no de instrucciones.
5. Ejecute la misma solicitud con la skill desactivada y compare ambas respuestas. En el menú /skills, seleccione la skill, pulse Space para cambiar su estado a off y, a continuación, Enter para guardar. Esto escribe una entrada skillOverrides en .claude/settings.local.json; al pulsar Space de nuevo, el estado vuelve a on cuando haya terminado.
6. Escriba un par de solicitudes que no deberían activar la skill y compruebe que esta 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. Luego, pida a Claude que evalúe su 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. Posteriormente, genera una comparación entre la respuesta con la skill y sin ella, lo cual ofrece la cifra real: la mejora en la tasa de éxito medida frente a los tokens y el tiempo que consume la skill.

Modo de fallo: la skill nunca se activa

Escribe la solicitud, el agente realiza la acción incorrecta de siempre y no aparece ninguna línea de skill. Siga estos pasos en orden.

• La descripción indica qué hace la skill pero no cuándo usarla, por lo que nada en su solicitud coincide con ella.
• La descripción evita las palabras que usted escribe. Si usted dice "nginx", la descripción debe contener la palabra nginx.
• disable-model-invocation: true está configurado en el frontmatter. Esto mantiene la descripción fuera del contexto del modelo por completo y permite que la skill solo sea invocable por usted mediante /name.
• Un glob paths en el frontmatter limita la activación a archivos coincidentes, y el archivo en el que está trabajando no coincide.
• La skill se encuentra en un directorio .claude/skills/ anidado por debajo de su directorio de inicio. Estos solo se cargan después de que el agente lee o edita un archivo dentro de ese subdirectorio, por lo que hasta ese momento la skill no está disponible.

Modo de fallo: la skill se activa constantemente

El problema opuesto es una descripción tan amplia que la skill se dispara ante tareas no relacionadas. "Usar cuando se trabaje en el servidor" coincide con casi cualquier petición en un repositorio de servidor. El cuerpo de la instrucción se carga entonces en tareas con 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 que realmente importa y nombre los archivos o comandos que cubre. Añada un paths glob cuando la skill solo se aplique a determinados archivos. Para cualquier acción con efectos secundarios, como un despliegue o un commit, establezca disable-model-invocation: true e invóquela usted mismo con /name, de modo que el agente nunca decida por su cuenta que es un buen momento para desplegar.

Modo de fallo: la habilidad pertenece a su 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 cada tarea. El cuerpo de una habilidad solo se carga cuando esta se ejecuta. La frecuencia es el factor decisivo. Un hecho que es válido para todas las tareas del repositorio, como el gestor de paquetes que utiliza, pertenece al archivo de reglas. Un procedimiento que se aplica a una pequeña parte de las tareas, como la regla de nginx anterior, pertenece a una habilidad, donde no consume recursos los días en que nadie edita nginx.

El fallo real es colocarlo en ambos lugares. Dos copias terminan siendo diferentes y, cuando el agente realiza una acción incorrecta, no es posible determinar qué copia siguió. Elija una ubicación única para cada instrucción. el límite entre habilidades, servidores MCP y archivos de reglas analiza los casos más complejos, incluyendo cuando la respuesta correcta es un servidor MCP (model context protocol) que proporciona al agente una nueva herramienta en lugar de una nueva instrucción.

Compártala una vez que haya demostrado su utilidad

Una habilidad que sobrevive a una semana de trabajo real merece ser consolidada. Las habilidades de proyecto en .claude/skills/ se revisan como si fueran código y se incluyen en el repositorio, de modo que cualquier compañero que lo clone obtenga su corrección sin pasos de configuración adicionales. Mover una habilidad entre repositorios sin recurrir a copiar y pegar es un problema en sí mismo, tratado en cómo compartir habilidades de agente entre repositorios.

Una nota sobre portabilidad. Claude Code acepta una larga lista de campos de frontmatter, pero el estándar de Agent Skills solo permite seis: name, description, license, compatibility, metadata y allowed-tools. Si sube una habilidad a claude.ai o la empaqueta para la Skills API incluyendo cualquier otro elemento en el frontmatter, el proceso fallará 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

Manténgase dentro de esos seis campos y el mismo archivo se cargará tanto en Claude Code como en cualquier otra herramienta que lea el estándar. Redactar las instrucciones de forma que sobrevivan al traslado a un modelo diferente es una tarea distinta, y escribir habilidades que funcionen con cualquier modelo lo explica.

FAQ

¿Qué longitud debe tener un archivo SKILL.md?

Manténgalo por debajo de las 500 líneas; la mayoría de las habilidades útiles son mucho más cortas. El cuerpo del archivo entra en la conversación cuando se invoca la habilidad y permanece allí durante el resto de la sesión, por lo que cada línea representa un coste recurrente y no único. Mueva el material de referencia extenso a archivos separados dentro del directorio de la habilidad y enlácelos desde SKILL.md, a un nivel de profundidad, para que el agente los lea solo cuando sea necesario. Los scripts incluidos se ejecutan en lugar de leerse, por lo que solo consumen recursos según su salida.

¿Por qué mi habilidad nunca se activa?

La descripción suele ser la causa, ya que es la única parte de la habilidad en contexto cuando el modelo toma la decisión. Asegúrese de que indique cuándo usar la habilidad, no solo qué hace, y que contenga las palabras que usted escribe realmente en sus peticiones. Si la descripción parece correcta, revise el frontmatter en busca de disable-model-invocation: true, que oculta la habilidad al modelo por completo, y de un glob en paths que la limita a archivos que usted no está editando. Una habilidad en un directorio .claude/skills/ anidado por debajo de su directorio inicial es otra causa: solo se carga después de que el agente lee o edita un archivo en ese subdirectorio.

¿Debería ser esto una habilidad 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 cada sesión, por lo que debe contener hechos que sean ciertos para todas las tareas, como el gestor de paquetes o la convención de nombres de ramas. Una habilidad se carga solo cuando se dispara, por lo que es el lugar adecuado para un procedimiento que solo importa en una pequeña parte de las tareas. Nunca escriba la misma instrucción en ambos lugares, ya que las dos copias divergirán y perderá la capacidad de saber cuál siguió el agente.

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

Compárela con una línea base. Recopile algunas peticiones reales, ejecute cada una en una sesión nueva con la habilidad disponible, luego ejecútelas de nuevo con la habilidad desactivada desde el menú /skills y lea ambas respuestas una al lado de la otra. Una sesión nueva es importante porque la conversación donde escribió la habilidad aún contiene sus explicaciones, lo que hace que un archivo incompleto parezca completo. El plugin skill-creator realiza esta comparación por usted e informa de la tasa de éxito junto al coste en tokens.

¿Puedo usar el mismo SKILL.md con un agente diferente?

Sí, siempre que se mantenga dentro de los campos que define el estándar Agent Skills: name, description, license, compatibility, metadata y allowed-tools. Claude Code acepta muchos más campos y también admite características en el cuerpo como la inyección de comandos de shell que otras herramientas no ejecutan. Subir una habilidad con un campo fuera del estándar fallará con un error explícito que enumera las propiedades permitidas, así que decida pronto si una habilidad está destinada a permanecer en Claude Code o a ser portátil.