Cómo crear una skill para Claude Code y Codex: deja de repetir instrucciones

Le pides a un agente que termine una tarea. Modifica unos archivos, te dice que todo está listo y respiras.

Después abres el proyecto y descubres que no probó el formulario, que una página no carga o que la mitad de los criterios quedaron en el chat como buenos deseos.

El problema no siempre es que el agente no sepa hacer el trabajo. A veces nadie dejó claro cómo se comprueba que está terminado.

Una skill puede ayudar con eso. Es una forma de guardar un procedimiento reutilizable para que el agente sepa cuándo aplicarlo, qué pasos seguir y qué debe entregar.

La idea de este artículo surge del video de Gilberts Ahumada Cabrera sobre cómo crear skills para Claude Code y Codex. Según la descripción del video y la publicación del autor en LinkedIn, en su ejemplo construye una skill llamada prove, que comprueba si una tarea está realmente terminada y entrega un veredicto de aprobado o fallido. Te recomendamos ver el video completo. Aquí tomamos la idea y construimos una plantilla propia de revisión para que la adaptes a tus proyectos.

Qué es una skill, en dos minutos

Una skill es una carpeta con instrucciones para una tarea o un flujo de trabajo. Su archivo principal se llama SKILL.md y puede ir acompañado de referencias, plantillas o scripts cuando hacen falta. El agente ve primero solo el nombre y la descripción, y carga las instrucciones completas cuando tu petición encaja o cuando la invocas tú.

Podrías crear una skill para:

• Revisar artículos antes de publicarlos.
• Preparar una aplicación para una entrega.
• Analizar una hoja de cálculo con el método de tu empresa.
• Comprobar una actualización de software.
• Generar informes con una estructura definida.

Si quieres el panorama completo (el estándar abierto, las carpetas de cada agente, cómo instalar skills de la comunidad y cuántas son demasiadas), lo tienes en nuestra guía Skills para agentes de código. Si trabajas en la app de Claude y no en un editor, mira Skills, conectores y plugins de Claude. Aquí vamos directo a construir una.

La ventaja no es que la IA obtenga un superpoder. Es que el método deja de depender de que alguien recuerde escribirlo completo en cada conversación.

La diferencia entre un prompt y una skill

Un prompt puede ser una instrucción puntual:

Revisa que el formulario de contacto funcione.

Una skill puede definir un procedimiento más amplio:

Cuando se solicite revisar una entrega, identifica los criterios de aceptación, ejecuta las comprobaciones disponibles, registra la evidencia y separa lo aprobado de lo pendiente.

La diferencia práctica está en el alcance y la reutilización. Un prompt también puede ser detallado, y una skill también es texto. Lo que añade la skill es una forma de organizar ese proceso para volver a usarlo, junto con los recursos que necesite:

• Uso habitual. El prompt resuelve una solicitud concreta; la skill aplica un procedimiento que se repite.
• Dónde vive. El prompt, en la conversación o en una plantilla; la skill, en una carpeta con un archivo SKILL.md.
• Qué incluye. El prompt, instrucciones y contexto dentro del mensaje; la skill, instrucciones, referencias, plantillas y, si hacen falta, scripts.
• Cuándo conviene. El prompt, cuando la tarea es puntual o cambia mucho; la skill, cuando el proceso es estable y quieres aplicarlo varias veces.

No necesitas crear una skill para todo. Si una instrucción se usa una vez y se resuelve en dos líneas, probablemente no vale la pena convertirla en un pequeño departamento administrativo.

Cuándo tiene sentido crear una skill

Una buena candidata suele cumplir tres condiciones:

1. La tarea se repite. Revisas entregas, redactas fichas o preparas informes con frecuencia.
2. El método importa. No basta con decir «hazlo bien»; hay pasos o criterios concretos.
3. Puedes describir un buen resultado. Sabes qué debería incluir y cómo revisar si falta algo.

Por ejemplo, «crear una skill para que la IA sea más inteligente» es demasiado amplio. En cambio, «crear una skill para revisar una página antes de publicarla: enlaces, formulario, visualización móvil y texto final» tiene un propósito y un resultado claros.

Qué lleva un archivo SKILL.md

La versión más sencilla tiene dos partes:

1. Una cabecera entre líneas --- con el nombre y la descripción.
2. Las instrucciones que debe seguir el agente.

---
name: revision-de-entrega
description: Revisa una tarea terminada contra sus criterios de aceptación y presenta evidencia. Usar cuando se solicite verificar una entrega.
---

# Revisión de entrega

1. Identifica qué se pidió y cuáles son los criterios de aceptación.
2. Comprueba cada criterio con los medios disponibles.
3. Registra qué revisaste y qué resultado obtuviste.
4. Señala lo que no pudiste comprobar y por qué.
5. Entrega un resumen con resultados y pendientes.

Usa para el nombre minúsculas y guiones, sin espacios: así es fácil invocarla y coincide con el nombre de la carpeta.

La descripción es la parte que más importa, porque es lo que el agente lee para decidir cuándo usar la skill. Si dice solo «ayuda con tareas», no orienta nada. La guía de OpenAI para crear skills recomienda descripciones concisas, con un alcance y unos límites claros, y poner al principio el caso de uso y las palabras con las que se pediría. La documentación de Claude Code va en la misma línea: todos los campos de la cabecera son opcionales, pero recomienda escribir la descripción para que Claude sepa cuándo cargarla.

Ejemplo práctico: una skill para revisar entregas

Vamos a crear una plantilla llamada revision-de-entrega. Su objetivo es responder una sola pregunta:

¿Qué evidencia tenemos de que la tarea realmente cumple lo solicitado?

Este ejemplo está escrito para este artículo. No es una copia de prove ni una reproducción del código que se muestra en el video.

Paso 1. Define la entrada

La skill necesita saber qué debe revisar. Puede partir de:

• La solicitud original.
• Los criterios de aceptación.
• Los archivos o la aplicación modificados.
• Las pruebas disponibles.
• Las restricciones que indicó la persona que pidió el trabajo.

Si no hay criterios claros, la skill puede reconstruirlos a partir de la solicitud y señalar qué partes siguen siendo ambiguas.

Paso 2. Define el resultado esperado

En lugar de una respuesta como «todo listo», pedimos un informe por criterio. Por ejemplo, para un formulario de contacto:

• El formulario abre. Comprobación: abrir la página. Estado: aprobado, fallido o no comprobado. Evidencia: la página o la captura revisada.
• El envío funciona. Comprobación: hacer un envío de prueba autorizado. Estado: aprobado, fallido o no comprobado. Evidencia: el resultado observado.
• Se ve bien en el móvil. Comprobación: revisarlo en una pantalla pequeña. Estado: aprobado, fallido o no comprobado. Evidencia: la pantalla usada y lo que se vio.

El estado «no comprobado» es importante. Si el agente no tiene acceso a un servicio, no debe presentar la ausencia de una prueba como si fuera un éxito. Es el mismo principio de nuestra guía para verificar una respuesta de IA antes de usarla: separar lo que se comprobó de lo que solo se afirma.

Paso 3. Escribe las instrucciones

Crea una carpeta llamada revision-de-entrega y, dentro, un archivo SKILL.md con este contenido:

---
name: revision-de-entrega
description: Verifica una entrega contra los criterios solicitados. Usar cuando se pida comprobar si una tarea, cambio o entregable está terminado.
---

# Revisión de entrega

## Objetivo

Comprobar los criterios de aceptación de una entrega y comunicar
qué está aprobado, qué falla y qué no se pudo verificar.

## Procedimiento

1. Lee la solicitud original y extrae los criterios de aceptación.
2. Revisa los archivos, páginas o resultados relacionados con la tarea.
3. Para cada criterio, elige una comprobación apropiada y disponible.
4. Ejecuta solo acciones autorizadas para esa revisión.
5. Registra el resultado y la evidencia observada.
6. Si una comprobación no se puede realizar, explica el motivo.
7. Presenta los hallazgos por orden de importancia.

## Formato de salida

Incluye una tabla con:

- Criterio.
- Comprobación realizada.
- Estado: aprobado, fallido o no comprobado.
- Evidencia o motivo.

Cierra con los pendientes que impiden considerar terminada la entrega.

## Límites

- No inventes resultados de pruebas.
- No declares que algo funciona si no lo comprobaste.
- No publiques, envíes datos ni modifiques servicios externos
  sin la autorización correspondiente.
- Si faltan criterios esenciales, indícalo.

Esta skill no necesita código para empezar: es un proceso escrito en lenguaje natural. Más adelante podrías añadir scripts para comprobaciones que deben salir siempre igual, como ejecutar las pruebas del proyecto, siempre que realmente aporten algo.

La skill revisa mejor cuando los criterios existen desde el principio. Si todavía no los tienes, empieza por el prompt De idea a especificación que una IA puede construir: primero defines qué se va a construir y cómo se sabe que está bien, y después la skill comprueba si se cumplió.

Dónde guardar la skill

Para usarla dentro de un proyecto, cada herramienta busca en una carpeta distinta.

En Claude Code:

tu-proyecto/
└── .claude/
    └── skills/
        └── revision-de-entrega/
            └── SKILL.md

En Codex:

tu-proyecto/
└── .agents/
    └── skills/
        └── revision-de-entrega/
            └── SKILL.md

Codex busca .agents/skills en cada carpeta, desde la que tienes abierta hasta la raíz del repositorio. Ambas herramientas admiten además skills personales que te acompañan en todos tus proyectos; los detalles están en la documentación de Claude Code y de Codex.

Puedes mantener el mismo contenido básico en las dos ubicaciones. Eso no significa que todas las funciones adicionales de una herramienta existan en la otra: si añades opciones específicas, scripts o integraciones, comprueba la compatibilidad y prueba cada entorno por separado.

Cómo invocar y probar la skill

En Claude Code, escribe una barra seguida del nombre:

/revision-de-entrega

En Codex CLI o en la extensión para el editor, puedes elegirla desde /skills o mencionarla con $:

$revision-de-entrega

Las dos herramientas también pueden activarla solas cuando tu petición encaja con la descripción. Por eso la descripción importa tanto.

Después, dale una tarea concreta. Por ejemplo:

Usa la skill de revisión de entrega para comprobar los cambios del formulario. Los criterios son: que la página abra, que los campos obligatorios se validen y que el envío funcione. Si no puedes comprobar el envío, indícalo.

Que la skill aparezca en la lista no basta. Revisa si el resultado cumple lo que esperabas:

• ¿Identificó todos los criterios?
• ¿Hizo las comprobaciones que tenía disponibles?
• ¿Mostró evidencia?
• ¿Marcó como pendiente lo que no pudo comprobar?
• ¿Evitó decir «todo funciona» sin haberlo probado?

Prueba también una petición que no debería activar esa skill. Si se ejecuta en cualquier conversación, su descripción es demasiado amplia.

Qué hacer cuando la skill falla

Una skill es una instrucción, no una garantía. El agente puede interpretar mal un criterio, saltarse una comprobación o encontrarse con una limitación del entorno.

Cuando eso pase, no empieces añadiendo veinte reglas al azar. Mira primero dónde falló:

• Si no se activa: revisa el nombre, la descripción y la ubicación de la carpeta.
• Si se activa para todo: limita la descripción a las tareas que de verdad debe cubrir.
• Si el informe es vago: pide un formato de salida con criterio, resultado y evidencia.
• Si afirma cosas que no comprobó: añade una instrucción explícita para separar lo observado de lo pendiente.
• Si depende de una herramienta que no siempre está disponible: explica qué hacer cuando falte y cómo informar de esa limitación.

Después de cambiarla, repite la prueba con el mismo caso y compara. Así sabes si el cambio mejoró algo.

Una skill no reemplaza tu criterio

Guardar un procedimiento ayuda a que el trabajo sea más consistente. No garantiza que el agente cumpla cada paso ni que una prueba esté bien diseñada.

Por eso conviene revisar las skills de terceros antes de instalarlas, sobre todo si incluyen scripts, piden acceso a archivos o se conectan a servicios externos. Una carpeta puede contener mucho más que instrucciones bonitas.

También conviene una revisión humana cuando el resultado afecta a datos de clientes, publicaciones, pagos o cambios difíciles de revertir. Es la misma idea de fondo que en Vibe coding con criterio: el agente trabaja, tú diriges y decides.

La pregunta útil no es «¿el agente dijo que terminó?». Es esta:

¿Qué se pidió, qué se comprobó y qué evidencia tenemos?

Una skill bien diseñada te ayuda a responderla cada vez, sin escribir el procedimiento desde cero.

Preguntas frecuentes

¿Necesito saber programar para crear una skill?

Para una skill basada solo en instrucciones, basta con un archivo de texto en formato Markdown. Si añades scripts o integraciones, necesitarás saber lo suficiente para revisarlos y probarlos.

¿La misma skill funciona en Claude Code y en Codex?

Una skill sencilla basada en SKILL.md sirve como punto de partida en las dos. Tienes que colocarla en la carpeta que corresponde a cada una y probarla en ambas, porque las funciones específicas de cada producto pueden diferir.

¿Una skill garantiza que el agente no cometa errores?

No. Mejora la claridad y la reutilización de un procedimiento, pero el resultado sigue necesitando comprobación. Pruébala con casos reales y revisa qué ocurre cuando algo falla.

¿Puedo usar una skill para crear contenido?

Sí. Puedes definir una estructura editorial, criterios de calidad y pasos de revisión. Para que el contenido aporte valor, también necesitas fuentes fiables, ejemplos pertinentes y revisar lo que se afirma.

¿Cuándo no necesito una skill?

Cuando la tarea es puntual, cambia constantemente o se resuelve bien con una instrucción corta. Una skill merece su carpeta cuando el procedimiento tiene valor al repetirse.

Sigue leyendo

• Skills para agentes de código: el panorama completo de las skills, las carpetas de cada agente y cómo instalar las de la comunidad con seguridad.
• Skills, conectores y plugins de Claude: cómo crear una skill conversando en la app de Claude y cuándo conviene un plugin.
• Cómo verificar una respuesta de IA antes de usarla: el método para separar lo comprobado de lo que solo se afirma.
• Ingeniería inversa con IA: construye tu propia versión con REA: otro flujo con agentes donde la evidencia manda.
• De idea a especificación que una IA puede construir: el prompt para definir los criterios antes de que el agente empiece.

Fuentes

• Cómo crear skills para Claude Code y Codex (video de Gilberts Ahumada Cabrera)
• Publicación de Gilberts Ahumada Cabrera sobre la skill prove (LinkedIn)
• Skills en Claude Code (documentación oficial)
• Build skills (documentación de OpenAI para Codex y ChatGPT)
• Skills (conceptos de la documentación de plugins de OpenAI)