Cursor ahora tiene dos formas de enseñarle algo a su agente: reglas y skills. Las reglas se llevaron toda la atención inicial, así que la mayoría de las guías que encuentras son sobre archivos .mdc. Pero desde que Cursor lanzó las Agent Skills, el lugar correcto para buena parte de ese contenido cambió, y se ha escrito sorprendentemente poco sobre cómo construir una bien. Esta es esa guía: la mecánica real de archivos según las docs de Cursor, más lo que aprendimos generando y analizando miles de archivos de contexto para agentes.
Qué es una Cursor Skill (y cuándo una regla es la herramienta equivocada)
Una regla de Cursor es contexto pasivo. Vive en .cursor/rules/*.mdc y, según su frontmatter, se inyecta en cada petición (alwaysApply: true) o se adjunta cuando un archivo que coincide con sus globs entra a la conversación. El agente nunca elige usar una regla. La regla simplemente está ahí, gastando tokens sea o no relevante para la tarea actual.
Una skill es una capacidad bajo demanda. Vive en su propia carpeta (.cursor/skills/<name>/SKILL.md) y, por defecto, el agente solo ve su name y su description. Cuando el agente decide que la skill es relevante para lo que pediste, carga el SKILL.md completo, y solo entonces. También puedes invocarla explícitamente escribiendo /skill-name en el chat del Agent. Además, la carpeta de una skill puede llevar scripts/ que el agente puede ejecutar, docs en references/ que carga solo cuando las necesita y assets/ como plantillas. Las reglas no pueden hacer nada de eso.
Esa diferencia dicta la elección:
- Regla: una restricción permanente que debe moldear todo lo que el agente hace en alguna parte del código. "Usamos named exports." "Nunca edites archivos generados, regenéralos."
- Skill: un procedimiento que el agente ejecuta cuando se lo piden. "Crea una migración de base de datos." "Escribe una entrada de changelog." "Publica una release."
Si estás describiendo cómo debe verse siempre el código, quieres una regla (también tenemos un generador gratuito para eso). Si estás describiendo cómo hacer una tarea, quieres una skill.
Anatomía de una skill
La skill mínima viable es una carpeta con un archivo. Las skills de proyecto van en .cursor/skills/ (o .agents/skills/), se commitean a git y llegan a todo tu equipo. Las personales van en ~/.cursor/skills/ y te siguen en todos los proyectos. Cursor descubre archivos SKILL.md de forma recursiva y también lee rutas legadas como .claude/skills/, así que las skills escritas para otros agentes suelen funcionar tal cual.
Aquí va una skill completa y realista para un proyecto que gestiona su base de datos con migraciones SQL numeradas:
---
name: db-migration
description: Create a new numbered SQL migration for the Supabase database.
Use when the user asks to add a migration, change the schema, create a
table, add a column, or write RLS policies.
paths:
- "supabase/migrations/**"
---
# db-migration
Create exactly one migration file per schema change in supabase/migrations/.
## Workflow
1. Find the next number: run `scripts/next-number.sh` from the skill root.
2. Name the file `NNN_short_description.sql` (three digits, snake_case).
3. Write the forward migration only. This project does not use down
migrations; reverting means writing a new forward migration.
4. Enable RLS on every new table and add an owner-only policy, because
every user-data table in this repo is RLS-guarded.
5. Run `supabase db push` against the local instance and paste the output.
## Restrictions
- Never edit an already-committed migration, because it may have run in
production. Create a new migration instead.
Los campos del frontmatter, según las docs de Cursor:
name(obligatorio): letras minúsculas, números y guiones, y debe coincidir con el nombre de la carpeta. Es también lo que escribes después de/para invocarla manualmente.description(obligatorio): qué hace la skill y cuándo usarla. Es la única parte del cuerpo que el agente ve antes de decidir cargar la skill, lo que la convierte en la línea de mayor impacto de todo el archivo.paths(opcional): patrones glob que acotan la skill a los archivos que coinciden. La clave legadaglobssigue funcionando, peropathses la forma actual.disable-model-invocation(opcional): ponlo entruey la skill solo corre cuando un humano escribe/skill-name, como un slash command tradicional. Úsalo para procedimientos destructivos o costosos (deploys, backfills de datos) que nunca quieres que se disparen por una corazonada.
Todo lo que va debajo del frontmatter son instrucciones en markdown plano, escritas para el agente, no para humanos.
Escribir la descripción para que el agente sí la active
Aquí es donde muere la mayoría de las skills. El descubrimiento funciona como una tabla de ruteo: el agente compara tu petición contra la descripción de cada skill y carga el cuerpo solo de la que juzga relevante. Una descripción vaga significa una skill que nunca se dispara, y concluirás que las skills "no funcionan" cuando en realidad tu resumen de una línea perdió la decisión de ruteo.
Tres reglas que lo arreglan:
- Di qué hace y cuándo usarla, en tercera persona. No "Ayuda con migraciones" sino "Crea una migración SQL numerada. Úsala cuando el usuario pida cambiar el esquema, agregar una tabla o agregar una columna."
- Incluye las palabras que la gente realmente escribe. Si tu equipo dice "agregar una columna" y "escribir una política RLS", esas frases van en la descripción tal cual. El ruteo coincide con tu vocabulario, no con tu intención.
- Di cuándo no usarla si hay una vecina cercana. Dos skills con descripciones solapadas (digamos,
db-migrationydb-seed) se robarán las invocaciones entre sí a menos que cada una nombre su frontera.
Si la skill sigue sin dispararse, pruébala directo con /skill-name. Si funciona invocada a mano pero nunca automáticamente, el cuerpo está bien y el problema es la descripción. Reescribe la descripción, no las instrucciones.
Alcance: qué va en la skill vs en una regla
Una prueba útil para cada línea que estás por escribir: "¿esto aplica siempre, o solo durante esta tarea?"
- "Todo el SQL va en minúsculas con comas al inicio" aplica siempre. Regla.
- "Corre
scripts/next-number.shpara elegir el número de migración" aplica solo durante la tarea. Skill. - Los hechos del repo ("desplegamos en Cloudflare Workers") no van en ninguna de las dos. Van en tu archivo de contexto siempre activo, y tanto reglas como skills pueden asumirlos.
Mantener limpia esta frontera paga doble: las reglas se mantienen pequeñas (se pagan en cada petición) y las skills quedan autocontenidas, en vez de comportarse distinto según qué reglas estén cargadas.
Errores comunes
Analizamos muchos archivos de configuración de agentes, y en las skills aparecen las mismas fallas:
Descripciones de activación vagas. "Ayuda con cosas de base de datos." El ruteo no tiene nada con qué coincidir, y nuestro linter marcaría el cuerpo equivalente como vague/low-signal: sin contenido verificable, nada sobre lo que el agente pueda actuar.
Skills que deberían ser reglas. Una "skill" cuyo cuerpo es una lista de convenciones de formato no tiene procedimiento que ejecutar. Se disparará rara y aleatoriamente, y las convenciones no aplicarán el otro 95% del tiempo. Conviértela en una regla auto-adjunta con globs y funcionará cada vez que los archivos relevantes estén abiertos.
Hinchazón. Las skills se cargan bajo demanda, lo que tienta a la gente a volcar guías de estilo enteras y referencias de API en el SKILL.md. Pero una vez activada, el archivo completo aterriza en el contexto. Deja el SKILL.md en el procedimiento y empuja el detalle a references/, que el agente carga progresivamente, solo cuando un paso lo necesita de verdad. Esto refleja los presupuestos de tamaño que existen para cada formato de archivo de contexto.
Gritos y prohibiciones sin fundamento. Las instrucciones escritas para modelos de la era 2024, "CRITICAL: you MUST ALWAYS...", degradan a los actuales, que se sobre-activan con la agresividad (antipattern/emphasis-inflation). Y un "NEVER do X" sin razón generaliza peor que uno con su justificación adjunta (antipattern/bare-prohibition). Fíjate cómo el ejemplo de arriba dice por qué no se pueden editar las migraciones ya commiteadas.
Puedes pasar el cuerpo de una skill por el linter gratis para atrapar esto antes de que te cueste una mala corrida del agente.
Validar e iterar
- Prueba de humo manual. Invócala con
/skill-namey mira cómo ejecuta el procedimiento de punta a punta. Esto aísla el cuerpo de instrucciones del problema de ruteo. - Prueba de descubrimiento. Abre un chat de Agent nuevo y formula la petición como lo haría un compañero de equipo, sin nombrar la skill. Si no se carga, itera solo sobre la descripción.
- Pásala por el linter. Corre el cuerpo por el linter gratuito para atrapar directivas vagas, inflación de énfasis y prohibiciones sin explicar.
- Observa el uso real. Cuando el agente use mal la skill, el arreglo suele ser uno de estos: una frase de "cuándo usarla" que falta en la descripción, un paso que asumía conocimiento que el agente no tenía, o un exceso de alcance que pertenece a una regla.
Sáltate la página en blanco
Puedes escribir tu primer SKILL.md a mano con la plantilla de arriba, o usar nuestro generador gratuito de Cursor skills: describe la tarea, las condiciones de activación, los globs y los permisos de herramientas, y produce un SKILL.md completo y limpio para el linter, con el frontmatter y la estructura que cubrimos aquí. Es gratis, corre en el navegador y no requiere registro. Genera una, ponla en .cursor/skills/ y pruébala con /skill-name.