Auteur : Cet article explique en détail les différences de localisation entre les deux dossiers de configuration .agents et .claude dans le développement d'AI Agent, les normes de stockage des Skills, la comparaison des structures de répertoire, ainsi que les scénarios d'application de AGENTS.md et CLAUDE.md.
Le développement d'AI Agents gagne en popularité, et diverses configurations apparaissent dans le répertoire racine des projets, comme .agents, .claude, .cursor, etc. Parmi ceux-ci, .agents et .claude peuvent tous deux stocker des Skills, mais leurs positions, concepts de conception et champs d'application sont complètement différents. Choisir le mauvais emplacement de stockage peut entraîner, au mieux, l'inefficacité des Skills, et au pire, des conflits de configuration lors de la collaboration d'équipe. Cet article, en partant de la conception sous-jacente, expliquera clairement les différences fondamentales entre les deux et les meilleures pratiques.
Valeur principale : Après avoir lu cet article, vous saurez clairement si les Skills doivent être placés dans .agents ou .claude, et comment gérer efficacement la configuration des Agents dans une équipe multi-outils.
Points clés des dossiers .agents et .claude
Pour répondre d'emblée à la question la plus importante : ces deux dossiers ne sont pas en concurrence, mais représentent des systèmes de configuration à différents niveaux.
| Dimension de comparaison | Dossier .claude/ |
Dossier .agents/ |
|---|---|---|
| Appartenance | Anthropic (Exclusif à Claude Code) | Fondation Agentic AI / Fondation Linux |
| Positionnement | Répertoire de configuration de projet pour Claude Code | Standard de configuration d'agent indépendant des outils |
| Format des Skills | SKILL.md (Métadonnées YAML en préambule + Markdown) |
SKILL.yaml (YAML pur) |
| Maturité | Prêt pour la production, officiellement supporté par Claude Code | Norme en cours de définition (Work In Progress) |
| Support multi-outils | Claude Code uniquement | Conçu pour tous les outils d'agents IA |
Différences de philosophie de conception entre .agents et .claude
La différence fondamentale entre ces deux dossiers réside dans leur philosophie de conception :
Le dossier .claude/ adopte une approche d'"intégration profonde et exclusive". Il est conçu sur mesure pour Claude Code, offrant des fonctionnalités complètes pour les Skills, les Sous-agents, les Hooks, les Permissions, etc., et est étroitement lié à la chaîne d'outils de Claude Code. L'avantage est sa richesse fonctionnelle et sa facilité d'utilisation ; le prix à payer est le verrouillage dans l'écosystème Claude Code.
Le dossier .agents/ adopte une approche de "standard universel inter-outils". Il tente de définir une spécification de configuration que tous les outils d'agents IA peuvent comprendre, un peu comme .editorconfig pour les éditeurs. L'avantage est qu'une seule configuration peut être utilisée pour plusieurs outils ; le prix à payer est que la norme est encore en évolution et que le support varie selon les outils.
Les deux peuvent coexister dans le même projet : les configurations profondes exclusives à Claude Code vont dans .claude/, tandis que les configurations générales réutilisables inter-outils vont dans .agents/.
Structure complète du dossier .claude
Regardons d'abord le dossier natif de Claude Code, .claude/, qui représente actuellement l'implémentation la plus mature.
Structure détaillée du dossier .claude
.claude/
├── CLAUDE.md # Instructions du projet (remplace CLAUDE.md à la racine)
├── settings.json # Paramètres du projet (à commiter dans git, partagés en équipe)
├── settings.local.json # Paramètres locaux (ignorés par git, configuration personnelle)
├── skills/ # Répertoire des compétences (Skills)
│ └── <nom-de-la-skill>/
│ ├── SKILL.md # Fichier de définition de la compétence (obligatoire)
│ ├── scripts/ # Scripts auxiliaires
│ ├── references/ # Ressources de référence
│ └── templates/ # Fichiers de modèles
├── agents/ # Définitions des sous-agents
│ └── <nom-de-l-agent>.md # Fichier de définition du sous-agent
├── commands/ # Commandes slash de l'ancienne version (fusionnées dans skills)
│ └── <nom-de-la-commande>.md
└── agent-memory/ # Mémoire persistante des sous-agents
└── <nom-de-l-agent>/
└── MEMORY.md
Il existe également un dossier .claude/ au niveau utilisateur (~/.claude/), où les Skills personnelles peuvent être placées pour être disponibles dans tous les projets :
~/.claude/
├── CLAUDE.md # Instructions utilisateur (inter-projets)
├── settings.json # Paramètres utilisateur
├── skills/ # Skills personnels (disponibles dans tous les projets)
├── agents/ # Sous-agents personnels
└── projects/ # Enregistrements de session et données
Format SKILL.md pour les Skills du dossier .claude
Les Skills de Claude Code sont définies dans des fichiers Markdown avec des métadonnées YAML en préambule :
---
name: ma-skill
description: Description de la compétence, aide Claude à déterminer quand la déclencher
user-invocable: true # L'utilisateur peut appeler via /ma-skill
allowed-tools: Read, Grep # Limite les outils utilisables
context: fork # Exécuter dans un sous-agent indépendant
model: sonnet # Couverture du modèle
---
Tu es un assistant professionnel d'examen de code...
（Instructions de la compétence au format Markdown）
Explication des champs clés :
- Un Skill avec
user-invocable: truesera enregistré comme une/commande-slash. context: forkindique que la compétence s'exécute dans un contexte indépendant, sans polluer la conversation principale.allowed-toolspeut limiter l'ensemble des outils qu'un Skill peut utiliser.- Les substitutions de paramètres
$ARGUMENTS,$0,$1sont prises en charge.
🎯 Conseil de développement : Le système de Skills de Claude Code suit la norme ouverte Agent Skills (agentskills.io). La syntaxe est universelle entre Claude Code, l'API Claude et VS Code Copilot.
Si vous développez des applications IA avec Claude Code, il est recommandé d'obtenir une clé API via APIYI apiyi.com pour gérer de manière centralisée les invocations de plusieurs modèles.
Structure complète du répertoire .agents
La spécification du répertoire .agents (AGENTS-1 Spec), maintenue par la Fondation Agentic AI et hébergée sous la Linux Foundation, vise à définir un standard de configuration universel que tous les outils de codage IA peuvent comprendre.
Structure détaillée du répertoire .agents
.agents/
├── manifest.yaml # Obligatoire : registre de configuration, déclare toutes les configurations disponibles
├── prompts/ # Obligatoire : instructions (prompts)
│ ├── base.md # Instructions générales pour l'Agent
│ ├── project.md # Instructions spécifiques au projet
│ └── snippets/ # Morceaux d'instructions modulaires
├── modes/ # Obligatoire : modes de comportement (similaire à .claude/agents/)
│ ├── plan.md # Mode planification
│ ├── code.md # Mode codage
│ └── review.md # Mode révision
├── policies/ # Obligatoire : politiques de sécurité et contraintes de capacité
├── skills/ # Obligatoire : définitions de compétences (conformes à la spécification Agent Skills)
│ └── <name>/
│ └── SKILL.yaml # Définition de compétence au format YAML
├── scopes/ # Obligatoire : remplacements au niveau du chemin (support Monorepo)
├── profiles/ # Obligatoire : superpositions de configuration nommées (dev/ci/staging)
├── schemas/ # Obligatoire : validation JSON Schema
└── state/ # État local (non soumis à git)
├── .gitignore
└── state.yaml
Contrairement à .claude/ où les Skills utilisent SKILL.md (Markdown), .agents/ utilise le format SKILL.yaml (YAML pur).
Conception unique du répertoire .agents
La spécification .agents introduit plusieurs concepts absents de .claude/ :
- Scopes (Portées) : Définit des configurations différentes pour divers sous-répertoires dans un Monorepo, la correspondance la plus spécifique au chemin ayant la priorité.
- Profiles (Profils) : Prend en charge des superpositions de configuration nommées comme
dev,ci,prod, similaires aux variables d'environnement. - Policies (Politiques) : Un répertoire indépendant pour les contraintes de sécurité, où les règles de refus (
deny) outrepassent toujours les règles d'autorisation (allow). - Determinism (Déterminisme) : Des entrées identiques doivent produire des sorties identiques, sans dépendance à un état externe.
Comparaison des règles de stockage des Skills pour les répertoires .agents et .claude
C'est la question pratique la plus préoccupante pour les développeurs : où dois-je placer mes Skills ?
Comparaison des répertoires .agents et .claude pour les Skills
| Dimension de comparaison | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| Fichier de définition | SKILL.md (Markdown + YAML frontmatter) |
SKILL.yaml (YAML pur) |
| Support Claude Code | Support natif, découverte automatique | Nécessite une configuration manuelle ou une prise en charge officielle ultérieure |
| Commande slash | user-invocable: true enregistre automatiquement /command |
Dépend de l'implémentation spécifique de l'outil |
| Exécution de sous-agent | context: fork s'exécute dans un contexte indépendant |
Via la configuration modes/ |
| Remplacement de modèle | model: sonnet spécifié directement |
Via la configuration profiles/ |
| Restrictions d'outils | allowed-tools: Read, Grep |
Via la configuration policies/ |
| Fichiers auxiliaires | Sous-répertoires scripts/, references/, templates/ |
Dépend de l'implémentation |
| Passage de paramètres | Substitution de variables $ARGUMENTS, $0, $1 |
Non défini explicitement par la spécification |
Comment les répertoires .agents et .claude peuvent coexister
Dans les projets réels, les deux répertoires peuvent coexister et se compléter. Prenons l'exemple de ce projet :
.claude/skills/ pour les compétences spécifiques à Claude Code :
apiyi-article-generator— Génération d'articles, intégration profonde avec les modèles et les spécifications du projet.apiyi-svg-generator— Génération d'illustrations SVG, dépend des modèles SVG du projet.apiyi-content-reviewer— Revue de contenu, utilise les normes de qualité du projet.
.agents/skills/ pour les compétences génériques et portables :
markdown-proxy— Récupération d'URL vers Markdown, utilise un script Python.nano-banana-pro-image-gen— Génération d'images, appelle une API externe.
Le principe de division est clair : les compétences profondément intégrées à Claude Code vont dans .claude/, tandis que celles réutilisables dans d'autres outils IA vont dans .agents/.
🎯 Conseil de sélection : Si votre équipe utilise uniquement Claude Code, placez tout dans
.claude/skills/pour un maximum de fonctionnalités.
Si les membres de l'équipe utilisent différents outils IA (Cursor, Windsurf, Codex, etc.), placer les compétences génériques dans.agents/skills/facilite la collaboration.
Pour les appels d'API dans le développement d'agents IA, il est recommandé de les gérer de manière unifiée via APIYI apiyi.com, une seule clé pour plusieurs modèles.
Comparaison des fichiers d'instructions pour .agents et .claude
Outre le dossier Skills, les deux systèmes disposent de leurs propres fichiers d'instructions de projet.
Différences entre CLAUDE.md et AGENTS.md
| Dimension de comparaison | CLAUDE.md | AGENTS.md |
|---|---|---|
| Outils pris en charge | Claude Code | Claude Code, OpenAI Codex, Google Jules, Cursor, GitHub Copilot, etc. |
| Niveau de fichier | Niveau utilisateur (~/.claude/) → Niveau projet (./) → Niveau sous-répertoire |
Niveau projet (./) → Niveau sous-répertoire |
| Substitution locale | CLAUDE.local.md (gitignore) |
Aucun |
| Norme officielle | Aucune (documentation produit Anthropic) | Oui (Agentic AI Foundation sous la Linux Foundation) |
| Échelle de l'écosystème | En croissance (adopté par Next.js, LangChain, Deno, etc.) | Grande échelle (n8n 178K étoiles, llama.cpp 97K étoiles, Bun 82K étoiles) |
| Initialisation | Commande /init dans Claude Code |
Création manuelle |
Recommandation pratique : Les deux fichiers peuvent coexister. CLAUDE.md peut contenir des instructions spécifiques à Claude Code (comme la configuration des Hooks, les règles d'autorisation), tandis que AGENTS.md peut contenir le contexte du projet commun à tous les outils d'IA (comme les commandes de build, les normes de codage, les descriptions d'architecture).
Aperçu de l'écosystème des fichiers associés à .agents et .claude
| Fichier/Répertoire | Système associé | Usage | Soumis à git |
|---|---|---|---|
CLAUDE.md |
.claude | Instructions de projet Claude Code | Oui |
CLAUDE.local.md |
.claude | Instructions locales personnelles | Non |
.claude/settings.json |
.claude | Autorisations, Hooks, MCP | Oui |
.claude/settings.local.json |
.claude | Paramètres locaux personnels | Non |
AGENTS.md |
.agents | Instructions de projet Agent génériques | Oui |
.agents/manifest.yaml |
.agents | Registre de configuration | Oui |
.agents/state/state.yaml |
.agents | État d'exécution local | Non |
.cursorrules |
Cursor | Règles spécifiques à Cursor | Oui |
Indice : Une étude de l'ETH Zurich en 2026 a montré que les fichiers de contexte générés par l'IA peuvent parfois réduire les performances des Agents. Il est donc conseillé de les rédiger manuellement et de limiter les informations non explicites que le code ne peut pas déduire (chaînes d'outils personnalisées, modèles non conventionnels, etc.).
Questions Fréquentes
Q1 : Claude Code peut-il lire les Skills du répertoire .agents/skills/ ?
Actuellement, Claude Code ne découvre et ne charge automatiquement les Skills que depuis le répertoire .claude/skills/. Le contenu de .agents/skills/ n'est pas reconnu nativement. La communauté a soumis une demande sur GitHub (issue #31005) pour que Claude Code prenne en charge le répertoire .agents/. Si vos Skills doivent fonctionner dans Claude Code, ils doivent impérativement être placés dans .claude/skills/ pour le moment.
Q2 : La spécification du répertoire .agents est-elle mature ? Peut-elle être utilisée pour des projets en production ?
La spécification du répertoire .agents/ (AGENTS-1 Spec) est encore en cours de développement (Work In Progress). Cependant, le fichier AGENTS.md est déjà largement adopté : de grands projets open-source comme n8n (178K étoiles), llama.cpp (97K étoiles), Bun (82K étoiles) l'utilisent. Il est recommandé d'utiliser AGENTS.md comme fichier d'instructions général pour l'instant, et d'attendre que la spécification complète de la structure du répertoire .agents/ soit stabilisée avant de l'adopter.
Q3 : Comment gérer la configuration lorsque les membres de l’équipe utilisent différents outils IA (Claude Code + Cursor) ?
Nous recommandons une gestion par couches : 1) AGENTS.md pour les informations générales du projet (commandes de build, conventions de codage), lu par tous les outils ; 2) CLAUDE.md pour les instructions spécifiques à Claude Code ; 3) .cursorrules pour les règles spécifiques à Cursor. Les Skills généraux sont placés dans .agents/skills/, et les Skills spécifiques à chaque outil dans leurs répertoires respectifs. Utilisez APIYI apiyi.com pour gérer de manière centralisée les invocations d'API IA de l'équipe, une seule plateforme couvrant tous les modèles.
Q4 : Quelles sont les différences de format entre SKILL.md et SKILL.yaml ?
SKILL.md est le format de Claude Code, utilisant un fichier Markdown avec des métadonnées YAML en frontmatter. La partie instruction est rédigée en Markdown, ce qui la rend plus lisible par l'humain. SKILL.yaml est le format de la spécification .agents/, utilisant entièrement une structure YAML pour la définition, ce qui est plus pratique pour l'analyse par machine. Les informations clés (nom, description, conditions de déclenchement) sont identiques dans les deux formats, seule la présentation diffère.
Résumé
La différence fondamentale entre les répertoires .agents et .claude réside dans :
- Leur positionnement :
.claude/est le répertoire de configuration exclusif pour Claude Code, intégrant profondément toutes ses fonctionnalités..agents/est une norme inter-outils universelle sous la Linux Foundation. - Le format des Skills :
.claude/skills/utiliseSKILL.md(Markdown), chargé nativement par Claude Code..agents/skills/utiliseSKILL.yaml(YAML), conçu pour être indépendant de l'outil. - La coexistence et la complémentarité : Les fonctionnalités avancées de Claude Code (Hooks, sous-agents, permissions) sont placées dans
.claude/. Les compétences générales et portables sont dans.agents/. Les instructions de base du projet utilisentAGENTS.md.
Le choix du répertoire dépendra de la composition de la chaîne d'outils de votre équipe et de vos besoins en matière de portabilité des compétences.
Il est recommandé d'utiliser APIYI apiyi.com pour gérer de manière centralisée les invocations de modèles dans le développement d'agents IA. La plateforme offre des quotas gratuits et une interface unifiée pour plusieurs modèles, prenant en charge l'intégration de modèles populaires comme Claude, GPT, Gemini, etc.
📚 Références
-
Documentation officielle Claude Code Skills : Définition complète, format et utilisation des Skills.
- Lien :
code.claude.com/docs/en/skills - Description : Comprendre le format SKILL.md, les règles de déclenchement et le passage des paramètres.
- Lien :
-
Documentation Claude Code Sub-Agents : Définition et configuration des Sub-Agents.
- Lien :
code.claude.com/docs/en/sub-agents - Description : Comprendre le format des fichiers dans le répertoire
.claude/agents/.
- Lien :
-
Site officiel AGENTS.md : Standard pour les fichiers d'instructions d'Agent inter-outils.
- Lien :
agents.md - Description : Comprendre les spécifications d'écriture d'AGENTS.md et la liste des outils supportés.
- Lien :
-
Spécification du dossier
.agents/: Définition complète de la structure de répertoire pour AGENTS-1 Spec.- Lien :
github.com/agentsfolder/spec - Description : Comprendre la conception de manifest.yaml, modes, policies, scopes.
- Lien :
-
Centre de documentation APIYI : Gestion unifiée des appels d'API dans le développement d'AI Agent.
- Lien :
docs.apiyi.com - Description : Supporte une interface unifiée pour plusieurs modèles, idéale pour les scénarios de développement d'Agent.
- Lien :
Auteur : Équipe technique APIYI
Échange technique : N'hésitez pas à discuter dans la section commentaires, plus de ressources sont disponibles sur le centre de documentation APIYI docs.apiyi.com.
