Explicación de las skills de Claude Code: qué se carga, cuándo se activan y cómo escribirlas

Si eliminamos la marca, una skill es un directorio con un archivo obligatorio. SKILL.md comienza con un frontmatter YAML que contiene un name y una description, y continúa con instrucciones habituales en Markdown. La carpeta también puede contener scripts que las instrucciones invoquen, documentos de referencia y plantillas de activos. Ese es todo el formato, y es deliberadamente sencillo: una skill es un procedimiento documentado y empaquetado para que un agente pueda encontrarlo.

---
name: brand-audit
description: Check UI code against the project design system. Use when reviewing components, screens, or PRs for hardcoded colors, off-scale spacing, or fonts that bypass the tokens in DESIGN.md.
---

# Brand audit

1. Read DESIGN.md at the repo root before judging anything.
2. Flag any literal hex value, arbitrary Tailwind color, or font-family
   that does not come from the token set.
3. Report violations as file:line with the token that should be used.

Este mismo formato ahora funciona más allá de Claude Code: ha evolucionado hacia una convención abierta de skills para agentes que OpenAI Codex y Cursor han adoptado con sus propias rutas de descubrimiento, razón por la cual una skill escrita una vez es cada vez más portátil. Analizamos la parte de Codex en skills de Codex.

Claude Code no lee todas sus skills en cada conversación. Al inicio de la sesión, indexa solo el frontmatter: cada skill aporta su nombre y descripción al contexto (un par de líneas, nada más). El cuerpo completo, los scripts y los archivos de referencia se cargan solo cuando Claude decide que la tarea actual coincide con una descripción, o cuando se invoca la skill explícitamente. Anthropic llama a esto divulgación progresiva, y es la decisión de diseño de la que depende toda la funcionalidad.

De esto se derivan dos consecuencias prácticas. Primero, instalar cincuenta skills no cuesta casi nada en términos de contexto, por lo que acumularlas es económico; cien descripciones pesan menos que el cuerpo de una sola skill cargada. Segundo, y esta es la parte que omiten los artículos de resúmenes, una skill con una descripción débil está *instalada pero es inalcanzable*. Claude no puede asociar una tarea con "Ayuda con cosas de frontend". Las quejas que llenan los hilos de Reddit —"instalé veinte skills y nada cambió"— suelen deberse a esto: los cuerpos estaban bien, pero las descripciones nunca dieron al modelo una razón para abrirlos.

• ~/.claude/skills/<skill-name>/SKILL.md: skills personales, disponibles en cada proyecto que abra.
• .claude/skills/<skill-name>/SKILL.md: skills de proyecto, integradas en el repo para que cada colaborador y cada sesión de agente las tenga.
• Plugins: un plugin puede empaquetar skills junto con comandos y agentes, que es como los equipos distribuyen un conjunto en una sola instalación.

La ubicación en el repo es más importante de lo que parece. Una skill personal optimiza sus sesiones; una integrada optimiza también las sesiones de sus compañeros y las de su agente de CI. Cualquier cosa que codifique un contrato de proyecto —cómo revisamos la UI, cómo escribimos migraciones, cómo aplicamos el sistema de diseño— debe estar en .claude/skills/ junto al código que gobierna.

Claude Code ofrece tres lugares para depositar conocimiento, y cada uno responde a preguntas diferentes. CLAUDE.md siempre está cargado: sirve para restricciones que se aplican a cada solicitud, y cada línea en él se paga en cada prompt, por lo que debe ser breve. Una skill se carga bajo demanda: sirve para procedimientos que solo son relevantes a veces, y puede ser extensa porque no cuesta nada hasta que se activa. Un subagente es un contexto totalmente separado: sirve para trabajos cuyo resultado intermedio contaminaría su sesión.

La línea divisoria para la taxonomía completa de archivos, incluyendo AGENTS.md y DESIGN.md, se encuentra en CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

1. 1

   Parta de una corrección recurrente

   Los mejores candidatos para una skill son aquellas cosas que escribe repetidamente: la lista de verificación de revisión que pega, la secuencia de despliegue que vuelve a explicar. Si nunca ha tenido que corregir al agente sobre ello más de dos veces, aún no necesita una skill.

2. 2

   Escriba primero la descripción como condiciones de activación

   Antes de las instrucciones, escriba la frase que determine cuándo se carga esto: los verbos y situaciones que contendría una solicitud coincidente. Si no puede definir las situaciones, la skill no se activará y lo habrá descubierto pronto.

3. 3

   Convierta el cuerpo en un procedimiento ejecutable

   Pasos numerados, comandos exactos, rutas de archivo exactas. Referencie archivos en la carpeta de la skill para cualquier contenido extenso. Un agente sigue un procedimiento con mucha más fiabilidad que si intenta captar una intuición.

4. 4

   Apunte a artefactos, no a adjetivos

   Una skill que dice "mantenga la UI consistente" no hace nada. Una skill que dice "lea DESIGN.md y use solo sus tokens" funciona, porque el criterio se externaliza en un archivo que el agente puede abrir. Coloque el conocimiento en un artefacto y deje que la skill sea el puntero.

5. 5

   Pruebe preguntando, no invocando

   No pruebe con una invocación explícita; eso no demuestra nada sobre el activador. Formule una solicitud de la manera en que lo haría naturalmente y compruebe si la skill se carga. Si no es así, lo que debe editar es la descripción, no el cuerpo.

El diseño es el caso de uso perfecto para una skill y la ilustración ideal de la regla de los artefactos mencionada anteriormente. Anthropic ofrece una skill de diseño frontend para Claude Code que realmente mejora pantallas individuales; la hemos probado y hemos escrito exactamente qué hace y qué le falta. Lo que le falta es la memoria entre pantallas: la skill aporta criterio estético, no sus valores, por lo que la pantalla veinte se desvía de la primera. El criterio se generaliza; la identidad no.

La solución es el patrón del paso cuatro: la skill sigue siendo un procedimiento ligero y la identidad reside en un artefacto, un DESIGN.md en la raíz del repositorio con tokens reales, elecciones tipográficas, reglas de espaciado y reglas de prohibición. La skill de auditoría de marca al principio de esta página tiene solo doce líneas porque todo lo que impone está definido en ese único archivo. Eso es un sistema de diseño para un agente: no un plugin, sino un contrato legible.

npx --yes identityforge@latest install --client claude-code

El formato de skill ha dejado de ser exclusivo de Claude en un sentido relevante para su inversión de tiempo. El Codex de OpenAI detecta carpetas SKILL.md en .agents/skills/ y ~/.agents/skills/ y las invoca con $; Cursor añadió Agent Skills con la misma carga bajo demanda junto a sus Rules permanentes, y ha estado orientando las reglas procedimentales largas hacia las skills. La convención está convergiendo en la misma estructura en todas partes: un frontmatter que anuncia, un cuerpo que instruye y una carga que espera la relevancia. Las skills que escriba basándose en artefactos de su repositorio, en lugar de en las peculiaridades de una herramienta, sobrevivirán al cambio de herramientas.