El desarrollo de Agentes de IA es cada vez más popular, y en la raíz de los proyectos empiezan a aparecer carpetas de configuración como .agents, .claude, .cursor, etc. Entre ellas, tanto .agents como .claude pueden albergar Skills, pero sus propósitos, filosofías de diseño y ámbitos de aplicación son completamente distintos. Elegir la ubicación incorrecta puede hacer que los Skills no funcionen, o peor aún, causar conflictos de configuración en la colaboración en equipo. Este artículo explicará las diferencias fundamentales entre ambos y las mejores prácticas, partiendo desde el diseño subyacente.
Valor Central: Al terminar de leer este artículo, tendrás claro si los Skills deben ir en .agents o en .claude, y cómo gestionar eficientemente la configuración de Agentes en equipos con múltiples herramientas.
Puntos clave de las carpetas .agents y .claude
Primero, respondamos la pregunta más importante: estas dos carpetas no están en competencia, sino que representan sistemas de configuración de diferentes niveles.
| Dimensión de comparación | Carpeta .claude/ |
Carpeta .agents/ |
|---|---|---|
| Propietario | Anthropic (Exclusivo de Claude Code) | Fundación Agentic AI / Fundación Linux |
| Posicionamiento | Directorio de configuración de proyectos de Claude Code | Estándar de configuración de Agentes independiente de herramientas |
| Formato de Skills | SKILL.md (Metadatos YAML + Markdown) |
SKILL.yaml (YAML puro) |
| Madurez | Listo para producción, soporte oficial de Claude Code | Norma en desarrollo (En progreso) |
| Soporte multiherramienta | Solo Claude Code | Diseñado para todas las herramientas de Agentes IA |
Diferencias en la filosofía de diseño entre las carpetas .agents y .claude
La diferencia fundamental entre estas dos carpetas radica en su filosofía de diseño:
.claude/ sigue el enfoque de "integración profunda exclusiva". Está hecho a medida para Claude Code, proporcionando capacidades completas de Skills, Subagents, Hooks, Permissions, etc., profundamente vinculadas a la cadena de herramientas de Claude Code. Su ventaja es que es completo y listo para usar; su inconveniente es que te bloquea en el ecosistema de Claude Code.
.agents/ sigue el enfoque de "estándar universal multiherramienta". Intenta definir una especificación de configuración que todas las herramientas de Agentes IA puedan entender, similar a cómo .editorconfig funciona para los editores. Su ventaja es que una configuración puede ser utilizada por múltiples herramientas; su inconveniente es que la especificación aún está evolucionando y el nivel de soporte varía entre herramientas.
Ambas pueden coexistir en el mismo proyecto: las configuraciones profundas exclusivas de Claude Code van en .claude/, y las configuraciones generales reutilizables entre herramientas van en .agents/.
Estructura de directorios completa de la carpeta .claude
Primero, veamos la carpeta nativa de Claude Code, .claude/, que es la implementación más madura actualmente.
Estructura de directorios de la carpeta .claude explicada
.claude/
├── CLAUDE.md # Instrucciones del proyecto (reemplaza CLAUDE.md de la raíz)
├── settings.json # Configuraciones del proyecto (enviar a git, compartir en equipo)
├── settings.local.json # Configuraciones locales (gitignore, configuración personal)
├── skills/ # Directorio de Skills
│ └── <nombre-skill>/
│ ├── SKILL.md # Archivo de definición de Skill (obligatorio)
│ ├── scripts/ # Scripts auxiliares
│ ├── references/ # Material de referencia
│ └── templates/ # Archivos de plantilla
├── agents/ # Definiciones de subagentes
│ └── <nombre-agente>.md # Archivo de definición de subagente
├── commands/ # Comandos de barra antiguos (fusionados en skills)
│ └── <nombre-comando>.md
└── agent-memory/ # Memoria persistente de subagentes
└── <nombre-agente>/
└── MEMORY.md
También existe el directorio a nivel de usuario ~/.claude/, donde los Skills personales se colocan para que sean efectivos en todos los proyectos:
~/.claude/
├── CLAUDE.md # Instrucciones a nivel de usuario (entre proyectos)
├── settings.json # Configuraciones a nivel de usuario
├── skills/ # Skills personales (disponibles en todos los proyectos)
├── agents/ # Subagentes personales
└── projects/ # Historial y datos de sesiones
Formato SKILL.md para Skills en la carpeta .claude
Los Skills de Claude Code se definen utilizando archivos Markdown con metadatos YAML en el front matter:
---
name: mi-skill
description: Descripción del skill, ayuda a Claude a decidir cuándo activarlo
user-invocable: true # El usuario puede invocarlo mediante /mi-skill
allowed-tools: Read, Grep # Limita las herramientas disponibles
context: fork # Ejecutar en un subagente independiente
model: sonnet # Cobertura del modelo
---
Eres un asistente profesional de revisión de código...
（Instrucciones del skill en formato Markdown）
Explicación de campos clave:
- Los Skills con
user-invocable: truese registran como/slash-command. context: forksignifica que se ejecuta en un contexto independiente y no contamina la conversación principal.allowed-toolspuede limitar el conjunto de herramientas que un Skill puede usar.- Se admiten reemplazos de parámetros como
$ARGUMENTS,$0,$1.
🎯 Recomendación de desarrollo: El sistema de Skills de Claude Code sigue el estándar abierto Agent Skills (agentskills.io), y la sintaxis es universal entre Claude Code, Claude API y VS Code Copilot.
Si desarrollas aplicaciones de IA con Claude Code, se recomienda obtener una clave API a través de APIYI apiyi.com para gestionar de forma unificada las invocaciones de múltiples modelos.
Estructura completa de directorios de la carpeta .agents
La especificación de la carpeta .agents (Especificación AGENTS-1), mantenida por la Agentic AI Foundation y alojada bajo la Linux Foundation, tiene como objetivo definir un estándar de configuración universal que todas las herramientas de codificación de IA puedan entender.
Estructura de directorios de la carpeta .agents explicada
.agents/
├── manifest.yaml # Requerido: Configuración del registro, declara todas las configuraciones disponibles
├── prompts/ # Requerido: Indicaciones de instrucciones
│ ├── base.md # Instrucciones generales del Agente
│ ├── project.md # Instrucciones específicas del proyecto
│ └── snippets/ # Fragmentos de instrucciones modulares
├── modes/ # Requerido: Modos de comportamiento (similar a .claude/agents/)
│ ├── plan.md # Modo de planificación
│ ├── code.md # Modo de codificación
│ └── review.md # Modo de revisión
├── policies/ # Requerido: Políticas de seguridad y restricciones de capacidades
├── skills/ # Requerido: Definiciones de habilidades (siguiendo la Especificación de Habilidades de Agente)
│ └── <name>/
│ └── SKILL.yaml # Definición de habilidad en formato YAML
├── scopes/ # Requerido: Sobrescrituras a nivel de ruta (soporte Monorepo)
├── profiles/ # Requerido: Superposiciones de configuración con nombre (dev/ci/staging)
├── schemas/ # Requerido: Validación de JSON Schema
└── state/ # Estado local (no se envía a git)
├── .gitignore
└── state.yaml
A diferencia de las habilidades de .claude/ que usan SKILL.md (Markdown), las habilidades de .agents/ usan el formato SKILL.yaml (YAML puro).
Diseño único de la carpeta .agents
La especificación .agents tiene varios conceptos que .claude/ no tiene:
- Scopes (Ámbitos): Definen configuraciones diferentes para distintos subdirectorios en un Monorepo, priorizando la coincidencia de rutas más específicas.
- Profiles (Perfiles): Soportan superposiciones de configuración con nombre como
dev,ci,prod, similar a las variables de entorno. - Policies (Políticas): Un directorio independiente de restricciones de seguridad, donde las reglas de denegación siempre tienen prioridad sobre las de permiso.
- Determinism (Determinismo): Entradas idénticas deben producir salidas idénticas, sin depender de estados externos.
Comparación de las reglas de almacenamiento de habilidades de las carpetas .agents y .claude
Esta es la pregunta práctica que más preocupa a los desarrolladores: ¿Dónde pongo mis habilidades?
Comparación de habilidades de las carpetas .agents y .claude
| Dimensión de comparación | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| Archivo de definición | SKILL.md (Markdown + frontmatter YAML) |
SKILL.yaml (YAML puro) |
| Soporte de Claude Code | Soporte nativo, descubrimiento automático | Requiere configuración manual o esperar soporte oficial |
| Comando de barra diagonal | user-invocable: true registra automáticamente /command |
Depende de la implementación específica de la herramienta |
| Ejecución de subagentes | context: fork se ejecuta en un contexto independiente |
Configurado a través de modes/ |
| Sobrescritura de modelo | model: sonnet especifica directamente |
Configurado a través de profiles/ |
| Restricciones de herramientas | allowed-tools: Read, Grep |
A través de policies/ |
| Archivos auxiliares | Subdirectorios scripts/, references/, templates/ |
Depende de la implementación |
| Paso de argumentos | Sustitución de variables $ARGUMENTS, $0, $1 |
La especificación no lo define explícitamente |
Cómo coexisten las carpetas .agents y .claude
En proyectos reales, ambas carpetas pueden coexistir y complementarse. Tomando este proyecto como ejemplo:
.claude/skills/ almacena habilidades exclusivas de Claude Code:
apiyi-article-generator— Generación de artículos, integración profunda con plantillas y especificaciones del proyecto.apiyi-svg-generator— Generación de ilustraciones SVG, dependiente de las plantillas SVG del proyecto.apiyi-content-reviewer— Revisión de contenido, utilizando los estándares de calidad del proyecto.
.agents/skills/ almacena habilidades generales y portátiles:
markdown-proxy— Captura de URL a Markdown, utilizando scripts de Python.nano-banana-pro-image-gen— Generación de imágenes, invocando APIs externas.
El principio de división es claro: las habilidades profundamente integradas con Claude Code van en .claude/, mientras que las reutilizables en otras herramientas de IA van en .agents/.
🎯 Recomendación de selección: Si tu equipo solo usa Claude Code, puedes poner todo en
.claude/skills/para obtener la funcionalidad más completa.
Si los miembros del equipo utilizan diferentes herramientas de IA (Cursor, Windsurf, Codex, etc.), poner las habilidades generales en.agents/skills/facilitará la colaboración.
Para las llamadas a API en el desarrollo de Agentes de IA, se recomienda gestionar unificadamente a través de APIYI apiyi.com, cubriendo múltiples modelos con una sola clave API.
Comparativa de archivos de directivas para .agents y .claude
Además de la carpeta Skills, ambos sistemas tienen sus propios archivos de directivas de proyecto.
Diferencias entre CLAUDE.md y AGENTS.md
| Dimensión de comparación | CLAUDE.md | AGENTS.md |
|---|---|---|
| Herramientas compatibles | Claude Code | Claude Code, OpenAI Codex, Google Jules, Cursor, GitHub Copilot, etc. |
| Nivel de archivo | Nivel de usuario (~/.claude/) → Nivel de proyecto (./) → Nivel de subdirectorio |
Nivel de proyecto (./) → Nivel de subdirectorio |
| Sobrescritura local | CLAUDE.local.md (gitignore) |
Ninguno |
| Estándar formal | Ninguno (documentación de productos de Anthropic) | Sí (Fundación Agentic AI bajo la Linux Foundation) |
| Escala del ecosistema | En crecimiento (adoptado por Next.js, LangChain, Deno, etc.) | A gran escala (n8n 178K estrellas, llama.cpp 97K estrellas, Bun 82K estrellas) |
| Inicialización | Comando /init dentro de Claude Code |
Creación manual |
Recomendación práctica: Ambos archivos pueden coexistir. CLAUDE.md se usa para directivas exclusivas de Claude Code (como configuración de Hooks, reglas de permisos), mientras que AGENTS.md se usa para el contexto del proyecto común a todas las herramientas de IA (como comandos de construcción, convenciones de codificación, descripciones de arquitectura).
Resumen del ecosistema de archivos complementarios para .agents y .claude
| Archivo/Directorio | Sistema al que pertenece | Propósito | ¿Se envía a git? |
|---|---|---|---|
CLAUDE.md |
.claude | Directivas de proyecto de Claude Code | Sí |
CLAUDE.local.md |
.claude | Directivas locales personales | No |
.claude/settings.json |
.claude | Permisos, Hooks, MCP | Sí |
.claude/settings.local.json |
.claude | Configuraciones locales personales | No |
AGENTS.md |
.agents | Directivas de proyecto generales de Agent | Sí |
.agents/manifest.yaml |
.agents | Registro de configuración | Sí |
.agents/state/state.yaml |
.agents | Estado de ejecución local | No |
.cursorrules |
Cursor | Reglas exclusivas de Cursor | Sí |
Nota: Un estudio de ETH Zurich en 2026 indicó que los archivos de contexto generados por IA a veces pueden degradar el rendimiento de los Agentes. Se recomienda escribirlos manualmente y limitar la información no explícita que no se puede inferir del código (cadenas de herramientas personalizadas, patrones poco convencionales, etc.).
Preguntas Frecuentes
P1: ¿Claude Code puede leer los Skills del directorio .agents/skills/?
Actualmente, Claude Code solo descubre y carga Skills de forma nativa desde el directorio .claude/skills/. El contenido de .agents/skills/ no se reconoce automáticamente. La comunidad ya ha presentado una solicitud en GitHub (Issue #31005) pidiendo que Claude Code admita el directorio .agents/. Si tus Skills necesitan funcionar en Claude Code, actualmente deben colocarse en .claude/skills/.
P2: ¿La especificación de la carpeta .agents está madura? ¿Se puede usar en proyectos de producción?
La especificación de la carpeta .agents/ (Especificación AGENTS-1) todavía está en desarrollo (Work In Progress), pero el archivo AGENTS.md ha sido ampliamente adoptado; grandes proyectos de código abierto como n8n (178K estrellas), llama.cpp (97K estrellas) y Bun (82K estrellas) ya lo utilizan. Se recomienda usar AGENTS.md como archivo de instrucciones genérico por ahora y esperar a que la estructura completa del directorio .agents/ y otras especificaciones se estabilicen antes de su uso.
P3: Los miembros del equipo usan diferentes herramientas de IA (Claude Code + Cursor), ¿cómo se gestionan las configuraciones?
Se recomienda una gestión por capas: 1) AGENTS.md para información general del proyecto (comandos de compilación, convenciones de codificación), que todas las herramientas leerán; 2) CLAUDE.md para instrucciones específicas de Claude Code; 3) .cursorrules para reglas específicas de Cursor. Los Skills generales se colocan en .agents/skills/ y los Skills específicos de la herramienta en sus respectivos directorios. Utiliza APIYI apiyi.com para gestionar de forma unificada las invocaciones de API de IA del equipo, una plataforma que cubre todos los modelos.
P4: ¿Cuál es la diferencia de formato entre SKILL.md y SKILL.yaml?
SKILL.md es el formato de Claude Code, que utiliza un archivo Markdown con metadatos frontmatter en YAML. La sección de instrucciones se escribe en Markdown, lo que mejora la legibilidad para los humanos. SKILL.yaml es el formato de la especificación .agents/, que define todo utilizando una estructura YAML, lo que facilita el análisis por parte de las máquinas. La información central (nombre, descripción, condiciones de activación) es la misma en ambos, solo cambia el formato.
Resumen
Diferencias clave entre las carpetas .agents y .claude:
- Propósito diferente:
.claude/es el directorio de configuración exclusivo del proyecto para Claude Code, integrado profundamente con todas sus funcionalidades;.agents/es un estándar universal multiplataforma bajo la Linux Foundation. - Formato de Skills diferente:
.claude/skills/utilizaSKILL.md(Markdown), cargado de forma nativa por Claude Code;.agents/skills/utilizaSKILL.yaml(YAML), diseñado para ser independiente de la herramienta. - Pueden coexistir y complementarse: Las funcionalidades profundas de Claude Code (Hooks, subagentes, permisos) se colocan en
.claude/, las habilidades portátiles y generales en.agents/, y las instrucciones base del proyecto se usan conAGENTS.md.
La elección de qué carpeta usar depende principalmente de la composición de la cadena de herramientas de tu equipo y de las necesidades de portabilidad de las habilidades.
Se recomienda utilizar APIYI apiyi.com para gestionar de forma unificada las invocaciones de modelos en el desarrollo de Agentes de IA. La plataforma ofrece cuotas gratuitas y una interfaz unificada para múltiples modelos, admitiendo la integración de modelos populares como Claude, GPT y Gemini.
📚 Material de Referencia
-
Documentación oficial de Claude Code Skills: Definición completa, formato y métodos de uso de Skills.
- Enlace:
code.claude.com/docs/en/skills - Descripción: Comprender el formato SKILL.md, las reglas de activación y la transferencia de parámetros.
- Enlace:
-
Documentación de Claude Code Sub-agents: Definición y métodos de configuración de Sub-agents.
- Enlace:
code.claude.com/docs/en/sub-agents - Descripción: Comprender el formato de archivo del directorio
.claude/agents/.
- Enlace:
-
Sitio web oficial de AGENTS.md: Estándar de archivo de instrucciones para Agents multiherramienta.
- Enlace:
agents.md - Descripción: Comprender las especificaciones de escritura de AGENTS.md y la lista de herramientas compatibles.
- Enlace:
-
Especificación de la carpeta
.agents/: Definición completa de la estructura de directorios de AGENTS-1 Spec.- Enlace:
github.com/agentsfolder/spec - Descripción: Comprender el diseño de
manifest.yaml,modes,policies,scopes.
- Enlace:
-
Centro de documentación de APIYI: Gestión unificada de llamadas API en el desarrollo de Agentes de IA.
- Enlace:
docs.apiyi.com - Descripción: Soporta interfaces unificadas para múltiples modelos, ideal para escenarios de desarrollo de Agentes.
- Enlace:
Autor: Equipo técnico de APIYI
Intercambio técnico: ¡Bienvenido a discutir en la sección de comentarios! Para más información, visita el centro de documentación de APIYI en docs.apiyi.com.
