Claude Skills ya son estándar: úsalas en Codex y Cursor

TL;DR: Las Claude Skills dejaron de ser una rareza de un solo producto. El formato SKILL.md que estrenó Anthropic es hoy un estándar abierto (agentskills.io) que adoptaron OpenAI Codex, ChatGPT, Cursor, Gemini CLI y GitHub Copilot. Significa que escribes una skill una vez y la reutilizas en casi cualquier agente de código. En esta guía verás qué es el estándar, cómo escribir un SKILL.md portable y dónde colocarlo en cada herramienta.

El problema: cada agente, su propia jaula

Hasta hace poco, automatizar el comportamiento de un agente de IA significaba aprender su dialecto. Reglas de Cursor por un lado, CLAUDE.md por otro, prompts pegados a mano en cada sesión. Si cambiabas de herramienta, tirabas tu trabajo y empezabas de cero. Ese lock-in era el coste oculto de elegir un agente.

Las Claude Skills rompieron ese muro, y lo interesante es lo que vino después: en cuestión de semanas, los demás vendors adoptaron el mismo formato. Ya no inviertes en "skills de Claude", inviertes en una capacidad portable que sobrevive a tu elección de herramienta. Para quien programa con varios agentes a la vez, esto cambia el cálculo por completo.

¿Qué es una Agent Skill?

Una Agent Skill es una carpeta con un archivo SKILL.md que empaqueta instrucciones, scripts y recursos para que un agente ejecute una tarea concreta de forma fiable. El archivo lleva metadatos (nombre y descripción) más las instrucciones; opcionalmente, scripts ejecutables, documentación de referencia y plantillas.

La especificación vive en agentskills.io, fue desarrollada originalmente por Anthropic y liberada como estándar abierto. Esa apertura es la razón de que el ecosistema convergiera tan rápido: nadie quería reinventar el mismo patrón.

La estructura mínima de una skill es esta:

mi-skill/
├── SKILL.md      # Obligatorio: metadatos + instrucciones
├── scripts/      # Opcional: código ejecutable
├── references/   # Opcional: documentación de apoyo
└── assets/       # Opcional: plantillas, recursos

¿Por qué de repente lo adopta todo el mundo?

La clave técnica es un patrón llamado progressive disclosure (revelación progresiva). Es lo que hace que tener muchas skills no infle el contexto ni dispare tu factura de tokens. Si te interesa el control de coste, ya escribí sobre cómo cruzar los 200k tokens vacía tu presupuesto; las skills atacan justo ese problema.

El agente carga la información en tres niveles, solo lo que necesita:

• Nivel 1 (siempre cargado): el frontmatter YAML con name y description. Ocupa pocos tokens y sirve de "índice".
• Nivel 2 (cuando la tarea encaja): el cuerpo completo del SKILL.md con el flujo de trabajo.
• Nivel 3 (bajo demanda): los archivos de references/, scripts/ o assets/, que el agente abre solo si los necesita.

Cada plataforma faceaba dos problemas idénticos: dar conocimiento amplio al agente sin destruir la calidad del contexto, y dejar que el usuario configure el comportamiento sin saber programar. El formato resuelve ambos. Por eso la adopción fue casi inmediata.

Implementación: escribe un SKILL.md portable paso a paso

Vamos a lo accionable. Un buen ejemplo es una skill que estandarice cómo el agente procesa documentos PDF, un caso donde el flujo manual suele ser inconsistente. Si quieres el detalle del pipeline, lo cubrí en procesamiento de PDFs para IA con Python y LangChain.

Paso 1. Crea la carpeta y el archivo. El frontmatter es lo único obligatorio, y la description es el trigger: el agente decide si la skill aplica leyendo esa línea, así que escríbela con las palabras que un usuario usaría.

---
name: extraer-pdf
description: Extrae texto y tablas de PDFs y los normaliza a Markdown. Úsala cuando el usuario mencione PDFs, facturas o extracción de documentos.
---

# Extraer datos de PDF

## Cuándo usar esta skill
Cuando haya que sacar texto o tablas de un PDF de forma consistente.

## Flujo de trabajo
1. Identifica si el PDF es nativo o escaneado.
2. Ejecuta scripts/extract.py sobre el archivo.
3. Devuelve Markdown limpio, una tabla por sección.

Paso 2. Si la tarea necesita lógica, añade un script en scripts/ y referencialo desde el SKILL.md. El agente prefiere ejecutar o parchear un script existente antes que reescribir bloques de código grandes, lo que ahorra tokens.

Paso 3. Coloca la carpeta en la ruta que cada agente espera. El formato es idéntico; lo único que cambia es dónde vive. Esa separación limpia entre "qué hace" y "dónde se carga" es un buen ejemplo del principio de separación de responsabilidades aplicado a la configuración de agentes.

Dónde vive una skill en cada agente

Mismo SKILL.md, distinta ruta. Esta tabla resume las ubicaciones a junio de 2026 (verifica siempre la documentación oficial, porque las rutas evolucionan):

Agente	Ruta personal	Ruta de proyecto	Invocación
Claude Code	~/.claude/skills/	.claude/skills/	Automática por descripción
OpenAI Codex	~/.codex/skills/	Carpeta del repo	$nombre-skill o /skills
Gemini CLI	~/.gemini/skills/	.gemini/skills/	Automática / explícita
Cursor	Junto a su sistema de Rules	Carpeta del repo	Automática

Existe incluso un instalador universal de la comunidad: npx Ai-Agent-Skills install <skill> --codex trae las skills más populares de Claude a Codex en segundos. La portabilidad ya no es teoría.

Aplicación práctica: una skill, tu equipo entero

En escenarios reales, el valor aparece cuando varias personas usan agentes distintos. Imagina un repositorio con una skill de "estilo de commits" o de "generar el informe semanal". Quien use Claude Code y quien use Codex obtienen el mismo comportamiento sin negociar formatos. La skill viaja en el repo, versionada con Git, y se actualiza como cualquier otro archivo.

Ese es el cambio de mentalidad: una skill no es un truco de prompt, es un artefacto de código. Si ya creaste alguna, como una Claude Skill que genera Word con tu plantilla, ahora ese trabajo rinde en más herramientas sin tocar una línea. Y si dudas entre Cursor y Claude Code para tu día a día, mi comparativa de subagents y skills en 2026 entra al detalle.

En Producción

El tutorial es fácil; producción tiene matices que conviene tener claros antes de repartir skills a un equipo.

• Presupuesto de contexto: Codex limita la lista inicial de skills a un 2% de la ventana de contexto, o 8.000 caracteres si la desconoce. Con muchas skills instaladas, recorta descripciones u omite algunas. Lección: escribe descripciones cortas y precisas, no párrafos.
• Trigger fiable: si la description es vaga, el agente no activará la skill o la activará cuando no toca. Trátala como la parte más importante del archivo, no como un comentario.
• Scripts a prueba de agentes: usa set -euo pipefail en shell, devuelve JSON por stdout y manda diagnósticos a stderr. Así el agente parsea sin adivinar y falla en voz alta en lugar de seguir en silencio.
• Coste: las skills no añaden coste de API por sí mismas; el ahorro viene de no inflar el contexto. En proyectos pequeños la diferencia es de unos pocos euros al mes, pero en sesiones largas se nota.
• Diferencias entre agentes: el formato base es portable, pero cada plataforma añade campos de frontmatter propios. Una skill bien diseñada con lo común funciona en todos; si usas extensiones específicas de Claude Code, prueba antes de asumir que viajan.

Errores comunes y depuración

Error: la skill nunca se activa. Causa: la description no contiene las palabras que el usuario realmente escribe. Solución: reescríbela en términos de la tarea ("cuando el usuario mencione facturas o PDFs"), no del nombre interno.

Error: funciona en Claude Code pero no en Codex. Causa: usaste un campo de frontmatter específico de un vendor, o la carpeta está en la ruta equivocada. Solución: quédate con name y description en el frontmatter portable y revisa la ruta de la tabla anterior.

Error: el agente carga demasiado contexto y la respuesta se ralentiza. Causa: metiste todo el contenido en el SKILL.md en vez de repartirlo en references/. Solución: deja en el cuerpo solo el flujo principal y mueve lo extenso a archivos que el agente abra bajo demanda.

Preguntas frecuentes

¿Una skill escrita para Claude Code funciona igual en Codex?

Sí, si te ciñes al formato base del estándar. El SKILL.md con name y description es universal. Lo único que cambia es la carpeta donde lo colocas y, en algunos casos, campos de frontmatter avanzados específicos de cada plataforma.

¿Cuál es la diferencia entre una skill y un archivo CLAUDE.md o AGENTS.md?

El CLAUDE.md o AGENTS.md es contexto siempre cargado: le dice al agente "así trabajamos aquí". Una skill es conocimiento bajo demanda que se activa solo cuando la tarea encaja. Son complementarios: si una sección de tu CLAUDE.md se ha vuelto un proceso paso a paso, extráela a una skill.

¿Las skills cuestan tokens extra?

No de forma significativa. El nivel 1 (metadatos) ocupa muy poco y solo se carga el resto cuando hace falta. El diseño completo de progressive disclosure existe precisamente para reducir el consumo de contexto, no para aumentarlo.

Conclusión

Hemos visto cómo las Claude Skills pasaron de ser una función de un producto a un estándar abierto que adoptan Codex, Cursor, Gemini CLI y más. La clave está en que ahora el formato SKILL.md es portable: escribes una capacidad una vez, la versionas en Git y viaja con tu repositorio sin importar qué agente use cada miembro del equipo. La inversión deja de ser un riesgo de lock-in y pasa a ser un activo reutilizable.

Si quieres profundizar en cuándo conviene una skill frente a un subagente, el harness que necesita tu Claude Code es la siguiente parada lógica. ¿Has portado ya alguna skill entre agentes? Cuéntame qué tal te fue en los comentarios o en Twitter @sergiomarquezp_. El próximo tema: cómo medir si una skill realmente mejora la fiabilidad del agente o solo lo hace sentir más ordenado.