La instrucción que escribes una vez, no en cada sesión

Hay un momento, cada pocos días, en el que escribes la misma corrección otra vez. Usa nuestro componente de botón. No añadas una dependencia para eso. Las fechas de este proyecto van siempre en ISO. Lo dijiste el martes, la sesión terminó y el conocimiento terminó con ella.

Una skill es esa instrucción, escrita una sola vez, en un fichero que el agente recoge por su cuenta cuando pasa a ser relevante.

Ése es el concepto entero, y el resto de esta página son los mecanismos, el criterio sobre qué va dentro de una y la depuración — porque el fallo habitual no es escribir una skill mala, es escribir una skill buena que nunca se carga.

Qué es una skill en el disco

Una carpeta con un fichero markdown dentro:

.claude/skills/
  cc-brand/
    SKILL.md
    references/
      token-reference.md
      motion-and-craft.md
    assets/
      AppShell.vue
      cc-tokens.css

SKILL.md abre con un frontmatter que lleva dos cosas que importan:

---
name: cc-brand
description: Implements UI in the CC design system for Vue. Use this WHENEVER
  building, styling, theming or reviewing any Vue interface, component, page,
  dashboard or form for CommitCycle — and whenever the user mentions CC UI, the
  brand blue (#693DFF), Plus Jakarta Sans, shadcn-vue, or "make this on-brand".
---

# CC Design System Implementor

Everything the agent should know, in ordinary markdown.

No hace falta nada más. Ni build, ni registro, ni fichero de configuración. La carpeta existe, luego la skill existe.

¿Por qué no ponerlo en el prompt?

Porque tienes que acordarte cada vez, y no te vas a acordar. Más exactamente: las veces que se te olvida no son aleatorias. Son las veces en que ibas rápido, que son las veces en que el agente tenía menos contexto, que es justo cuando la convención más importaba.

¿Por qué no ponerlo en AGENTS.md?

Ésta es la pregunta de verdad, y la respuesta es el diseño entero de la función.

AGENTS.md (o CLAUDE.md) se carga siempre. Cada turno, cada sesión, cada task, venga o no a cuento. Eso lo hace perfecto para hechos que son siempre ciertos — el stack, los comandos, la estructura de carpetas, lo que nunca hay que hacer — y significa que cada línea que añades cuesta contexto en trabajos que no tienen nada que ver con ella. Un AGENTS.md de 900 líneas es un impuesto sobre cada petición.

Una skill se carga sólo cuando encaja. Lo que está siempre en contexto es su nombre y su description: un par de líneas. El cuerpo se lee sólo cuando el agente decide que el trabajo lo pide.

Esto se llama progressive disclosure, y funciona en tres niveles:

Por eso una skill puede ser enorme — un sistema de diseño completo, una checklist de cumplimiento, la superficie entera de una API — sin pagarla en una petición que va de otra cosa. Llevas una biblioteca, no una nota.

Qué va dónde

El criterio que hace que todo esto funcione:

El error habitual es meter contenido del tamaño de un sistema de diseño en AGENTS.md, donde se carga en cada petición, incluidas las que van de un script de build. El otro error habitual es meter el stack del proyecto en una skill, donde puede no cargarse en el momento en que hace falta.

La description es el disparador entero

Si te llevas una sola cosa de esta página: la description no es documentación, es la regla de coincidencia. Es la única parte de tu skill que el agente ve antes de decidir si lee el resto.

Así que escríbela con las palabras que una persona teclea de verdad. No:

Directrices de implementación de marca y estándares de componentes.

Eso no coincide con nada. Quien pide “haz que esto se parezca a nuestra app” no ha usado ninguna de esas palabras. Mejor:

Úsalo siempre que construyas, estilices, tematices o revises cualquier interfaz, página, dashboard, formulario o componente de [producto] — y siempre que se mencione [el color de marca], [la tipografía], [la biblioteca de componentes] o “que quede on-brand”. Recurre a ello incluso cuando la petición sea sólo “haz una página de ajustes” o “dale estilo a esta tarjeta”.

Concretamente, una description que salta de forma fiable nombra:

• Los verbos — construir, estilizar, revisar, migrar, redactar
• Los sustantivos — los artefactos a los que se aplica
• Las cadenas literales — nombres de producto, códigos hex, nombres de tipografía, nombres de biblioteca
• Las formulaciones informales — “que quede on-brand”, “como siempre”, “como el resto de páginas”
• Cuándo usarlo aunque no parezca que aplica — esta línea hace un trabajo sorprendente

Pasarse de inclusivo cuesta un poco de contexto cuando salta sin necesidad. Quedarse corto te cuesta la skill entera, en silencio, para siempre. Inclínate por que salte.

Dónde viven las skills

Dos sitios, y la elección importa más de lo que parece.

.claude/skills/ dentro del proyecto. Se commitea con el repositorio, así que está en tu otro ordenador, en cada sesión futura y para cualquiera que lo clone. Todo lo que describe este producto va aquí.

~/.claude/skills/ en tu carpeta personal. Disponible en cada proyecto que toques, invisible para todos los demás. Esto es para tu propia forma de trabajar: cómo te gusta que se escriban los commits, cómo quieres estructurados los documentos.

Por defecto, el proyecto. Una skill que vive sólo en tu portátil está a un ordenador de distancia de no existir, y es la razón por la que un proyecto “sólo funciona bien cuando lo ejecutas tú”.

¿Cómo sé que ha saltado?

Pregunta. ¿Qué skills has usado para eso? es una pregunta razonable y tiene una respuesta directa. ¿Qué skills tienes disponibles? las lista, que es la primera comprobación después de instalar una.

La comprobación fuerte es de comportamiento: abre una sesión nueva, formula una petición como la formularía un usuario real — no como la formula la documentación de la propia skill — y mira si la salida cumple las normas sin que las menciones. Ése es el único test que importa, porque ésa es la condición real de uso.

¿Por qué no salta mi skill?

Fíjate en que cuatro de los cinco son problemas de description o de ubicación. El contenido casi nunca es lo que está mal.

Mantener corto el SKILL.md

Una vez cargado, el cuerpo se lee entero — así que la longitud cuesta algo, y la buena estructura es un fichero de instrucciones corto que apunta al detalle.

SKILL.md              las normas, el orden de decisión, qué gana en un conflicto
references/           el material largo: tablas de tokens, superficies de API, ejemplos
assets/                cosas que copiar: componentes, hojas de estilo, plantillas
scripts/               cosas que ejecutar

La skill cc-brand del ejemplo de arriba tiene exactamente esta forma: el SKILL.md declara la prioridad de capas y la regla de conflicto en unos cientos de palabras, y la referencia de tokens, la guía de movimiento y los componentes de shell ya hechos están en ficheros a los que apunta. El agente abre la referencia de la barra lateral cuando está construyendo una barra lateral, y nunca en otro caso.

Dos cosas van en el SKILL.md y no en un fichero de referencia: el orden de precedencia (cuando dos normas chocan, cuál gana) y qué no hacer. Las dos son cortas y las dos son lo que el agente hace mal cuando faltan.

Skills, MCP, subagents, slash commands

Cuatro cosas que se confunden, en ejes genuinamente distintos:

Skills y MCP son complementos, no alternativas. El servidor MCP le da al agente una conexión con tu base de datos; la skill le cuenta tus convenciones de esquema y qué tablas no se escriben nunca directamente. Tools sin instrucciones es la configuración que tiene casi todo el mundo, y es la razón por la que el agente puede alcanzarlo todo y aun así hacer lo que no toca con ello.

Instalar una que te han pasado

1. Pon la carpeta en .claude/skills/ (proyecto) o ~/.claude/skills/ (personal).
2. Abre una sesión nueva — una ya abierta ha construido ya su lista.
3. Pregunta qué skills tienes disponibles y comprueba que la tuya aparece por su nombre.
4. Dale una petición realista y mira si las normas se aplican sin mencionarlas.

Si falla el paso 3, la carpeta está en el sitio equivocado o el SKILL.md está mal nombrado. Si falla el paso 4, es la description.

La que merece la pena instalar el primer día es una skill de diseño. Si tienes una idea pero todavía ni marca ni opinión visual, startpow.com te deja elegir lo que te gusta, exportar y descargar el resultado como skill. La sueltas dentro y, a partir de ahí, cada pantalla que construya el agente llega con tus colores, tu tipografía y tu espaciado sin que los describas otra vez — que es más o menos la diferencia entre un producto y una demo, por unos diez minutos de trabajo.

¿Cuántas skills son demasiadas?

Hay un presupuesto real, y no es el que preocupa a la gente. Los cuerpos son gratis hasta que se cargan, así que una carpeta con cuarenta skills no ralentiza nada. Lo que no es gratis son las descriptions, que están todas en contexto, todo el rato.

Cuarenta descriptions vagas son peores que cinco afiladas por una segunda razón: cuantas más se solapen, menos fiable es que gane la correcta. Dos skills que cubren “estilos” de forma igual de plausible significan un cara o cruz en cada petición de UI.

La forma práctica es un puñado de skills con fronteras limpias, cada una de las cuales podrías describir en una frase sin usar la palabra “y”. Cuando no puedes, eso son dos skills.

Una skill son instrucciones que aceptas ejecutar

Merece la pena decirlo claro, porque las skills se pasan de mano en mano como si fueran plantillas de estilo, y no lo son.

Una skill es un conjunto de instrucciones que un agente va a seguir, con tus permisos, en tu repositorio. Una skill descargada puede decirle a un agente que instale un paquete, que mande un fichero a alguna parte, que trate una norma como más importante que las que escribiste tú. Es la misma decisión de confianza que ejecutar un script que te ha mandado alguien, y el hecho de que sea markdown y no código la hace parecer más pequeña de lo que es.

Así que: lee el SKILL.md antes de instalarla, mira qué más hay en la carpeta y ten más cuidado con las skills que traen scripts que con las que traen documentación. Un sistema de diseño de una herramienta que elegiste tú es algo muy distinto de una skill pegada en un hilo de un foro.

Lo mismo vale al revés cuando publicas una: quien instale la tuya te está extendiendo esa confianza.

Llevarlas a un equipo

Tres vías, de menor a mayor ceremonia:

• Commitéalas al repositorio. .claude/skills/ está en el repo, así que clonarlo las trae. Esto cubre la mayoría de los casos y no necesita infraestructura ninguna.
• Distribúyelas en un plugin. Un plugin puede llevar skills junto con comandos y servidores MCP, se instala por su nombre y se actualiza de forma centralizada. Lo correcto cuando varios repositorios necesitan las mismas convenciones.
• Manda la carpeta. Vale una vez, es inmanejable a la cuarta persona, porque ya no hay respuesta para “¿qué versión tienes tú?”.

El fallo que hay que evitar es aquél en el que la skill existe sólo en la carpeta personal de alguien. El proyecto se comporta entonces de forma distinta según quién esté al mando, y nadie puede ver por qué.

La forma más rápida de escribir tu primera skill

No empieces con una página en blanco. Las páginas en blanco producen normas genéricas, y las normas genéricas son las que el modelo ya sigue.

En su lugar: trabaja normal, y presta atención a lo que corriges. La tercera vez que digas lo mismo — la tercera vez que señales el formato de fecha, o el componente, o que aquí no usamos esa biblioteca — di:

Convierte lo que acabas de aprender en una skill. Escribe la description para que salte siempre que alguien pida algo de esta área, incluidas las formulaciones informales. Mantén corto el SKILL.md y pon el detalle largo en un fichero de referencia.

Tus correcciones ya son exactamente el contenido que una skill necesita. Son específicas, son reales y son las que de verdad se estaban haciendo mal — que es un punto de partida mucho mejor que cualquier cosa que se te ocurriera escribir de antemano.

Trucos que marcan una diferencia real

• Enseña, no sólo cuentes. Un ejemplo trabajado de tu convención rinde más que tres párrafos describiéndola. Los modelos son extremadamente buenos reconociendo patrones a partir de un ejemplo, y meramente obedientes al seguir una norma.
• Una skill por asunto. Una única skill de “nuestros estándares” que cubra diseño, testing y despliegue salta con todo y no se aplica bien a nada. Divídela.
• Di qué gana. Toda skill que contenga más de una fuente de criterio necesita una frase que diga cuál tiene precedencia en un conflicto. Sin ella elige el modelo, y elige distinto cada vez.
• Escribe las normas en negativo. No introduzcas una segunda biblioteca de componentes. No añadas dependencias para algo que ya hace la biblioteca estándar. Las restricciones negativas se siguen de forma más fiable que las positivas y casi siempre son lo que de verdad te importaba.
• Versiónala con el código que describe. Una skill de diseño en el repositorio cambia en el mismo commit que los tokens que documenta. Una skill de diseño en tu portátil se desvía en quince días y luego enseña con toda confianza los colores del mes pasado.
• Prueba con una sesión fría y una formulación perezosa. “haz la página de ajustes” es como llegará la petición de verdad. Si la skill necesita la versión bien formulada para saltar, no funciona.
• Deja morir a las skills viejas. Una skill que describe una convención que abandonaste es peor que ninguna skill: es una instrucción segura de sí misma, siempre disponible, para hacer lo que no toca.

Si no estás en Claude Code

Las skills como carpetas son una función de Claude Code. Otras herramientas agénticas leen un único fichero de instrucciones siempre cargado, y la convención casi universal es AGENTS.md en la raíz del repositorio.

El contenido se traslada tal cual. Lo que no se traslada es la carga selectiva — todo lo que hay en ese fichero se paga en cada petición — así que la disciplina es otra: limítalo a lo que siempre es cierto, pon el material largo en documentación normal y apunta a ella desde el fichero en lugar de pegarla dentro.

En cualquier caso, el movimiento de fondo es el mismo, y es el hábito de mayor palanca del desarrollo con agentes: la segunda vez que expliques algo, escríbelo donde el agente lo vaya a encontrar. El resto del montaje que rodea a esto — el repositorio, el modelo, el host, el stack, las salvaguardas — son seis decisiones.