AGENTS.md, CLAUDE.md, rules y skills
Cuatro formatos para instruir a un agente de código. No compiten entre sí: se diferencian en cuándo se cargan, y eso decide cuánto contexto te cuestan. Aquí está qué lee cada editor, qué dicen las docs oficiales y cuál elegir en cada caso.
Los cuatro formatos de un vistazo
Cada uno nació para un editor distinto y hoy conviven. El único que sí está de salida es .cursorrules, que la documentación de Cursor da por legacy.
Cursor Rules
Reglas estructuradas en .cursor/rules/ con frontmatter, descripciones y patrones. El sistema más completo y composable de Cursor.
- Archivos .mdc en .cursor/rules/
- Activación por description, file globs o manual
- Comparte prompts, scripts y workflows entre el equipo
AGENTS.md
Un solo archivo markdown en la raíz del proyecto. Cursor lo lee como instrucciones globales del agente. Pensado para casos simples.
- Un único AGENTS.md en la raíz
- Markdown plano, sin frontmatter requerido
- Convención open-source compartida con otros agentes
CLAUDE.md
El formato de Claude Code. Markdown plano, se concatena desde varias ubicaciones y entra completo en cada sesión. Cursor también lo lee.
- Claude Code lee CLAUDE.md, no AGENTS.md
- Se concatenan los cuatro niveles: gestionado, usuario, proyecto y local
- Importa otros archivos con @ruta, hasta cuatro saltos
- La documentación recomienda menos de 200 líneas
Agent Skills
Carpetas con SKILL.md autoinvocables. El agente decide cuándo usarlas según el description, o las invocas con /skill-name. Ya no son exclusivas de Claude.
- Directorio por skill con SKILL.md
- Activación por description semántica o /skill-name
- Soporta scripts, ejecución en subagente y contexto dinámico
- Distribuibles vía skills.sh (registry open-source)
Aspecto por aspecto
Las diferencias clave entre los cuatro formatos, según lo que dice la documentación oficial de cada plataforma.
| Aspecto | Cursor Rules | AGENTS.md | CLAUDE.md | Agent Skills |
|---|---|---|---|---|
| Estructura | Cursor Rules.cursor/rules/*.mdc | AGENTS.mdAGENTS.md (un archivo) | CLAUDE.mdCLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md | Agent Skills.cursor/skills/, .agents/skills/ o .claude/skills/ + SKILL.md |
| Activación | Cursor RulesDescription, globs o manual | AGENTS.mdSiempre activo (global) | CLAUDE.mdSiempre activo, en cada sesión | Agent SkillsDescription semántica o /skill-name |
| Composición | Cursor RulesMúltiples rules combinables | AGENTS.mdArchivo único, sin composición | CLAUDE.mdSe concatenan todos los niveles; imports con @ruta | Agent SkillsSkills referencian archivos auxiliares en su carpeta |
| Alcance | Cursor RulesProyecto o User Rules (global) | AGENTS.mdProyecto | CLAUDE.mdGestionado, usuario, proyecto y local | Agent SkillsProyecto y global (~/.cursor/, ~/.agents/, ~/.claude/) |
| Editor | Cursor RulesCursor | AGENTS.mdCursor (también lo respetan otros agentes) | CLAUDE.mdClaude Code y Cursor | Agent SkillsCursor, Claude Code, Codex y compatibles |
| Estándar abierto | Cursor RulesNo | AGENTS.mdAGENTS.md convention | CLAUDE.mdNo, pero Cursor lo lee igual | Agent Skillsagentskills.io |
| Soporte de scripts | Cursor RulesSí (workflows con scripts) | AGENTS.mdNo (solo instrucciones) | CLAUDE.mdNo (solo instrucciones) | Agent SkillsSí (scripts ejecutables, contexto dinámico con !`cmd`) |
La misma idea en cada formato
Una regla equivalente expresada en cada sistema. Vas a notar que el modelo mental cambia más que la cantidad de código.
Cursor Rules
.cursor/rules/next.mdc---
description: Next.js component conventions
globs:
- "app/**/*.tsx"
alwaysApply: false
---
When working with Next.js components:
- Use Server Components by default
- Add 'use client' only when needed
- Co-locate types with componentsAGENTS.md
./AGENTS.md# Project Agent Instructions
## Next.js conventions
- Use Server Components by default
- Add 'use client' only when needed
- Co-locate types with components
## Database
- Migrations live in /db/migrations
- Use Drizzle ORM for queriesAgent Skills
.cursor/skills/next-best/SKILL.md---
description: Next.js component conventions. Use when building React components in App Router.
---
## When to use
Building Next.js components, optimizing rendering strategy.
## Conventions
- Server Components by default
- 'use client' only when needed
- Co-locate types with componentsCLAUDE.md
./CLAUDE.md@AGENTS.md
## Next.js conventions
- Use Server Components by default
- Add 'use client' only when needed
- Co-locate types with components
<!-- Nota para humanos: los comentarios HTML de
bloque se eliminan antes de entrar en contexto,
así que no gastan tokens. -->Interoperabilidad entre editores
La pregunta que más se repite y la que peor documentada está. Dos de estas filas van al revés de lo que casi todo el mundo asume.
- AGENTS.mdClaude CodeNoCursorSí
Formato abierto bajo la Agentic AI Foundation. Lo leen Codex, Jules, Zed, Warp, Gemini CLI, Windsurf y muchos más, pero Claude Code no.
- CLAUDE.mdClaude CodeSíCursorSí
Cursor lo recoge automáticamente desde la raíz y lo aplica a todas las conversaciones, sin importar el alwaysApply del frontmatter.
- .cursor/rules/*.mdcClaude CodeNoCursorSí
Solo Cursor. Un .md plano dentro de .cursor/rules se ignora: sin frontmatter no hay description, globs ni alwaysApply.
- SKILL.mdClaude CodeSíCursorSí
El único formato que carga bajo demanda: al arrancar solo entra la descripción, el cuerpo entra cuando se usa.
- .cursorrulesClaude CodeNoCursorSí
Legacy. La documentación de Cursor dice que va a ser deprecado: migra el contenido a una regla con Always Apply y borra el archivo.
Cómo tener AGENTS.md y CLAUDE.md sin duplicar nada
La solución oficial no es mantener dos archivos con el mismo contenido, sino que uno importe al otro. Claude carga el importado al arrancar la sesión y añade el resto debajo:
@AGENTS.md
## Claude Code
Usa el modo plan para cambios bajo `src/billing/`.Si no necesitas añadir nada específico de Claude, ln -s AGENTS.md CLAUDE.md también sirve. En Windows el enlace simbólico pide privilegios de administrador o modo desarrollador, así que ahí conviene el import.
Guía de decisión
Cuatro situaciones concretas para ubicarte. No hay respuesta absoluta: el editor que uses define el espacio.
Usas Cursor y quieres algo simple
Un archivo markdown en la raíz. Sin overhead: lo leen todos los agentes que respetan la convención. Ideal para reglas globales del proyecto.
Usas Cursor con reglas que dependen del tipo de archivo o flujo
Si necesitas activación condicional, scripts, o múltiples reglas combinables, Rules te da más control. La documentación de Cursor recomienda Rules para workflows complejos del equipo.
Trabajas con Claude Code y con otro agente a la vez
Claude Code lee CLAUDE.md, no AGENTS.md, así que un AGENTS.md solo lo deja fuera. Mantén el contenido en AGENTS.md para el resto de agentes y crea un CLAUDE.md de una línea que lo importe con @AGENTS.md. Un solo archivo que mantener y los dos agentes leen lo mismo.
Quieres un procedimiento que funcione en varios agentes
Cursor las lee desde .cursor/skills/ y .agents/skills/, Claude Code desde .claude/skills/, y Cursor además acepta el directorio de Claude por compatibilidad. Una misma carpeta te sirve en los dos, con descripciones semánticas y soporte para scripts.
skills.sh: el registry abierto
Skills sigue el estándar agentskills.io. Vercel Labs mantiene skills.sh como directorio público y npx skills como CLI para instalar skills en 76 agentes.
Una instalación, múltiples agentes
La CLI npx skills conoce las rutas de instalación de cada agente compatible y coloca los archivos donde corresponde. Para agentes que soportan nativamente la spec (Claude Code es el caso más claro), los skills se cargan automáticamente. Para otros agentes la integración puede variar.
# Instalar un skill desde GitHub
npx skills add anthropics/skills --skill skill-creator
# Listar skills instalados
npx skills list
# Buscar en el registry
npx skills find react
# Actualizar skills instalados
npx skills updateLa lista completa vive en el repositorio vercel-labs/skills. Cada agente declara su ruta de instalación (proyecto y global) en la configuración de la CLI.
Lo que se dice por ahí y lo que dicen las docs
Reviso afirmaciones que circulan por ahí contra lo que dice la documentación oficial.
Cursor Rules está deprecado
Falso. La doc oficial de Cursor lo presenta como el sistema principal en 2026 y describe AGENTS.md como una alternativa más simple, no como reemplazo. Ninguno está deprecado.
Las Skills son solo de Claude
Ya no. Cursor soporta Agent Skills de forma nativa: las descubre en .cursor/skills/ y .agents/skills/, tanto en el proyecto como en tu directorio de usuario, y además lee .claude/skills/ y .codex/skills/ por compatibilidad. Una misma carpeta de skills te sirve en Cursor y en Claude Code sin duplicarla. Lo que sigue siendo cierto es que no reemplazan a Cursor Rules: conviven.
Skills siguen un estándar abierto
Verdadero y con tracción real. Skills implementa el spec de agentskills.io. Vercel Labs publica la CLI npx skills, que soporta 76 agentes (Claude Code, Cursor, Codex, Cline, Continue, GitHub Copilot, Windsurf y más). El leaderboard de skills.sh acumula más de un millón de instalaciones.
MCP permite contexto dinámico
Verdadero. Model Context Protocol es un estándar abierto (modelcontextprotocol.io) que permite cargar contexto desde servidores externos. Ortogonal a rules y skills: cualquiera de estos formatos puede combinarse con MCP.
Fuentes primarias
Documentación oficial de las plataformas. Para todo lo que aparece en este artículo, esta es la fuente de verdad.
Cursor Rules (docs oficiales)
Especificación oficial del sistema de Rules de Cursor.
AGENTS.md (Cursor)
Convención simplificada para instrucciones globales. Cursor la documenta como una sección dentro de la misma página de Rules.
Claude Code Skills (docs oficiales)
Documentación oficial de Anthropic sobre Skills.
Agent Skills en Cursor (docs oficiales)
Los directorios que Cursor descubre y el frontmatter que acepta.
Agent Skills (open standard)
Especificación abierta que siguen Cursor, Claude Code y Codex.
skills.sh (Vercel Labs registry)
Directorio público de Agent Skills y ranking de adopción. Open source.
vercel-labs/skills (CLI)
La CLI `npx skills`, que instala skills en 76 agentes con symlinks o copia.
Model Context Protocol (MCP)
Especificación del protocolo para contexto dinámico desde servidores externos.
Mis skills para agentes de código
Las cuatro Agent Skills que publico, con el formato SKILL.md en uso real y las reglas que sigo al escribirlas.
Mi artículo anterior sobre Cursor Rules
Contexto histórico de cómo escribí mis primeras reglas.
¿Tienes un setup que te haga ruido?
Si quieres ayuda para diseñar el setup de editores con IA de tu equipo o auditar el que ya tienes, escríbeme y vemos cómo.