Agent Plugins 1.0.0 : Le format de packaging partagé pour les compétences et les serveurs MCP

Google, Microsoft, OpenAI, Cursor, Vercel et AWS ont soutenu Agent Plugins 1.0.0, une spécification définissant la manière dont les plugins pour les agents IA sont emballés. Elle définit la structure des dossiers, le format des fichiers de configuration ainsi que les règles de découverte pour deux types de composants : les compétences et les serveurs MCP. L’objectif affiché est simple : écrire un plugin une seule fois et le faire fonctionner dans n’importe quel client compatible.

Jusqu’à présent, il existait deux méthodes courantes pour doter un agent de codage de nouvelles capacités. Une compétence correspond à un ensemble d’instructions Markdown que l’agent lit lorsqu’il en a besoin. Un serveur MCP est un processus distinct qui relie l’agent à des outils externes, des API ou des bases de données. Le contenu des deux types de composants était déjà portable entre les outils, mais chaque outil avait ses propres conventions en matière de structure des dossiers, de noms des fichiers de configuration et d’emplacement des fichiers.

La version 1.0.0 ne concerne que l’enveloppe extérieure. Elle laisse de côté l’intérieur d’une compétence ainsi que le protocole MCP lui-même.

Pourquoi c’est important

Cette approche s’applique à trois groupes :

• Les auteurs de plugins disposent d’une seule structure de répertoires fonctionnelle sur tous les clients compatibles. Il n’est plus nécessaire de conserver des copies séparées pour Cursor, Copilot, Codex et les autres.
• Les fournisseurs d’outils disposent d’emplacements prédéfinis pour skills/ et mcp.json, ce qui leur évite de devoir créer leur propre logique de découverte ou de parsing des configurations. Un fournisseur peut toujours ajouter ses propres éléments dans un répertoire nommé sans perturber les autres implémentations.

L’écosystème plus large bénéficie de trois choix de conception : la découverte via un répertoire, aucune configuration supplémentaire autre que le placement des fichiers, et des échecs restés confinés. La distribution devient plus simple, et les auteurs peuvent se concentrer sur ce qu’ils veulent créer plutôt que sur les outils à choisir.

Les limites sont tout aussi évidentes. La spécification standardise l’emballage du paquet sans rien préciser sur la sécurité de son contenu. Il n’y a ni signatures, ni modèle de permissions, ni gestion des secrets. Pour l’instant, l’avantage réside dans l’efficacité des développeurs, mais cela ne offre aucune garantie de sécurité ni de fiabilité.

Structure du répertoire

Un plugin conforme n’est rien de plus qu’un dossier. Pour un exemple nommé reports-plugin, l’arborescence complète ressemble à ceci :

reports-plugin/
├── plugin.json                  # Required: The only entry point for the plugin
├── skills/                      # Optional: Collection of skills
│   ├── summarize/               # One individual skill
│   │   ├── SKILL.md             #   Required: Skill definition file
│   │   ├── scripts/             #   Optional: Scripts used by the skill
│   │   │   └── analyze.sh
│   │   └── references/          #   Optional: Reference documentation for the skill
│   │       └── checklist.md
│   ├── deploy/                  # A second skill
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── rollback.sh
│   │   └── references/
│   │       └── runbook.md
│   └── code-review/             # A third skill
│       └── SKILL.md
├── mcp.json                     # Optional: MCP server configuration
├── com.cursor.tools/            # Optional: Cursor-specific extensions, other clients skip automatically
│   └── hooks/
│       └── hooks.json
├── LICENSE
└── CHANGELOG.md

Les clients cherchent uniquement en trois endroits. plugin.json indique que le dossier est un plugin valide. Chaque sous-dossier de premier niveau de skills/ contenant un SKILL.md compte comme une compétence. De plus, mcp.json est lu comme la configuration du serveur MCP. Les dossiers nommés selon le style de domaine inversé, tels que com.cursor.tools/, ne sont lus que par le client auquel ils appartiennent, ici Cursor. Les autres clients, comme ChatGPT et Codex, les ignorent simplement.

Le manifest plugin.json

plugin.json est le seul fichier obligatoire, et sa version minimale est très compacte :

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

Le schéma est fermé, avec dix champs de niveau supérieur autorisés : $schema, name, version, description, author, homepage, repository, license, keywords et extensions. Un champ inconnu est signalé mais ignoré, et le plugin se charge néanmoins. Un name incorrect est une autre affaire : s’il manque, a le mauvais type ou contient des caractères illégaux (lettres majuscules, doubles traits d’union, chaîne vide), tout le plugin est rejeté.

Les règles pour name : entre 1 et 64 caractères, composé de lettres minuscules, de chiffres, de traits d’union et de points. Il doit commencer et se terminer par une lettre ou un chiffre, et deux traits d’union ou deux points consécutifs sont interdits.

Comment les composants sont trouvés

La découverte se fait exclusivement sur la base d’un répertoire. Le fichier plugin.json ne peut ni déplacer des composants ailleurs ni intégrer leur configuration directement. Seuls trois types d’emplacements existent :

• skills/ : tout sous-dossier de premier niveau contenant un fichier SKILL.md constitue une compétence. Les dossiers plus profonds ne sont pas scannés.
• mcp.json : la configuration du serveur MCP.
• Dossiers d’extension client : nommés selon le format domaine inverse, comme com.example.client/, et ignorés par tous les autres clients.

L’absence d’un composant n’est pas une erreur. Si le dossier skills n’existe pas ou que mcp.json n’est pas un fichier ordinaire, ce type de composant est marqué comme invalide, tandis que les autres s’chargent normalement.

Configuration MCP

mcp.json doit contenir deux champs de niveau supérieur, $schema et mcpServers. La version de $schema doit correspondre à celle déclarée dans plugin.json ; sinon, toute la configuration MCP est rejetée.

Trois modes de transmission sont définis :

• stdio exécute un processus enfant local. command représente un token exécutable, soit un nom simple résolu via le PATH système, soit un chemin relatif au plugin commençant par ./. Les champs optionnels sont args, env et cwd ; par défaut, cwd correspond à la racine du plugin.
• streamable-http correspond à la norme HTTP Streamable actuelle pour MCP.
• sse est le mode de transmission HTTP+SSE plus ancien, issu de la spécification MCP du 2024-11-05, conservé pour assurer la compatibilité rétrograde.

Les clients doivent impérativement implémenter au minimum stdio ou streamable-http, et l’utilisation des deux est préférable. sse est optionnel.

Variables d’environnement et données persistantes

Lorsque un client lance un processus stdio, il doit définir deux variables. PLUGIN_ROOT contient le chemin absolu vers le répertoire racine du plugin. PLUGIN_DATA fait référence à un répertoire de données persistantes fourni par le client, qui reste intact après les mises à jour du plugin et est supprimé lors de son désinstallation.

${PLUGIN_ROOT} et ${PLUGIN_DATA} peuvent apparaître dans args, dans les valeurs de env ainsi que dans cwd. La substitution s’effectue en une seule passe sur du texte brut. Aucun autre placeholder ni expansion de variables de type shell n’est pris en charge.

Les échecs restent locaux

La spécification applique une règle selon laquelle « une défaillance partielle ne doit pas entraîner une cascade » à plusieurs niveaux :

• Si un serveur MCP échoue à démarrer, cela n’affecte pas les autres serveurs ni les compétences.
• Une compétence dont le formatage est incorrect est ignorée, tandis que le reste se charge normalement.
• Une entrée MCP utilisant un transport non pris en charge par le client est également ignorée.
• Si mcp.json est complètement invalide, seuls les composants MCP sont désactivés, mais les compétences continuent de se charger.

Ce que la spécification omet

Manquant dans la version 1 : la manière d’installer les plugins, le contrôle des permissions en temps de exécution, l’authentification des auteurs ainsi que le stockage sécurisé des secrets ou des clés API. Le texte indique clairement que les valeurs des en-têtes et les valeurs d’environnement constituent des données de paquet visibles et ne constituent pas un moyen fiable pour préserver la confidentialité des informations. Il n’y a pas non plus de configuration OAuth ni de champ de référence de crédentiel portable, ce qui oblige chaque client à gérer l’autorisation de sa propre manière.

Qui est inclus, et qui ne l’est pas

Le support de lancement couvre six clients : Kiro, VS Code, Cursor, GitHub Copilot, Codex et ChatGPT. Google s’est porté garant ce même jour, et son Agents CLI fait partie des premiers produits à adopter ce format. AWS est également un partenaire de soutien.

Anthropic a créé à la fois le format des compétences et MCP, et Claude Code utilise un emballage de plugins presque identique depuis 2025. Néanmoins, Anthropic n’a pas fait partie du groupe de travail, et Claude Code n’est pas sur la liste initiale de support.

Un exemple complet avec l’Agents CLI de Google

Agents CLI fait partie des premiers à avoir adopté cette technologie. Une fois installé, il fournit à un agent de codage sept compétences couvrant les modèles ADK, la structure de projet, l’évaluation, le déploiement et l’observabilité.

Imaginons la création d’un assistant à la connaissance de type RAG. Un développeur décrit l’objectif en langage simple, et l’agent agit ensuite de manière autonome :

1. Il structure le projet à partir du modèle ADK agentic_rag, en utilisant Vector Search comme stockage de données.
2. Il constate que le modèle ne prend pas en charge les citations, réécrit les instructions de l’agent pour exiger des citations en ligne et modifie le système de récupération afin qu’il retourne des identifiants de source.
3. Il met en place le stockage de données, charge 12 documents de référence en Python comme corpus et effectue un test de fonctionnement de base.

Une évaluation est effectuée avant le déploiement : 20 cas de test répartis en quatre groupes, 6 pour l’exactitude de la récupération, 5 pour le refus en l’absence de contexte, 5 pour le raisonnement à plusieurs étapes et 4 pour l’exactitude des citations.

L’évaluation a révélé un cas limite qui provoquait des hallucinations. Pour les questions hors du corpus, l’agent répondait parfois en s’appuyant sur des connaissances générales au lieu d’admettre qu’il ne savait pas. La cause en était une phrase dans le prompt du système indiquant que les questions simples ayant une réponse connue pouvaient être résolues directement sans outils. La suppression de cette phrase a résolu complètement le problème.

Le déploiement sur Google Cloud prend de deux à trois minutes, avec Cloud Trace activé par défaut. Après s’être enregistré auprès de Gemini Enterprise, tous les membres de l’organisation peuvent trouver et utiliser l’agent.