Développement IA

Qu’est-ce qu’Agent Plugins 1.0.0 ? plugin.json, MCP, Agent Skills et la disposition JSON (2026)

Environ 15 min

Agent Plugins 1.0.0 est un contrat de répertoire ouvert, pas un autre protocole d’appel d’outils. Le plugin.json à la racine ne nomme que le paquet et la version de la spec. Les skills sont dans skills/. Les serveurs MCP ne s’écrivent que dans le mcp.json racine. Le modèle ne remplit que du JSON. C’est l’hôte qui se connecte au serveur.

Avant de lire

Fichier Ce que la spec exige Ce qu’elle ne fait pas
plugin.json Le seul manifeste, à la racine. $schema et name sont requis. La liste de champs est fermée Il ne peut ni inliner MCP ni déplacer un chemin
skills/ Seulement SKILL.md dans un enfant immédiat. Le format appartient à la spec Agent Skills Pas de recherche récursive. Un dossier absent n’est pas une erreur
mcp.json Au premier niveau, seulement $schema et mcpServers. Chaque serveur a un type Il n’exécute pas d’outil. 1.0.0 n’a pas de champ d’identifiants portable
Dossier d’extension Un dossier en domaine inversé, comme com.example.client/. extensions utilise les mêmes espaces Les autres clients doivent pouvoir l’ignorer

Faits de la spec Agent Plugins 1.0.0, de la note Vercel et du Google Developers Blog, tous datés du 6 août 2026. La commande A-1042 et orders.example.com sont fictifs.

Il range skills et serveurs MCP dans un répertoire que l’on peut déplacer

Agent Plugins 1.0.0 est devenu public le 6 août 2026. Les mainteneurs principaux venaient alors d’Amazon, Cursor, Microsoft, OpenAI et Vercel. Le même jour, le Google Developers Blog a écrit que Google rejoignait ce groupe, représenté par Kevin Hou, et commençait à construire le support dans ses produits. Ce n’est pas un format privé publié par Google seul. La spec définit deux types de composants portables : Agent Skills et serveurs MCP. Installation, distribution, politique et interface restent au client. Un client valide le plugin.json racine avant de découvrir les composants. Pendant le chargement, il ne doit pas aller chercher le Schema sur le réseau.

  • Manifeste : $schema doit valoir https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. name est requis.
  • Skills : skills/<nom>/SKILL.md. Enfants immédiats seulement. Pas de récursion.
  • MCP : mcp.json à la racine. Chaque entrée indique stdio, streamable-http, ou l’ancien sse optionnel.

Comment MCP circule sur le fil : comment un agent de code appelle MCP. En quoi un schéma d’outil MCP diffère du function calling : schéma d’outil MCP et function calling. Ce texte ne réécrit pas ces deux articles. Il dit seulement ce que possèdent les deux fichiers JSON d’un répertoire de plugin.

La liste de champs de plugin.json est fermée

Les seuls champs de premier niveau permis sont $schema, name, version, description, author, homepage, repository, license, keywords et extensions. Les deux premiers sont requis. Un nom fait 1 à 64 caractères, lettres minuscules, chiffres, tirets et points, doit commencer et finir par une lettre ou un chiffre, et ne doit contenir ni -- ni ... Le versionnement sémantique est recommandé pour version, mais une chaîne non SemVer n’est pas à elle seule un motif de rejet. author ne peut contenir que name, email et url. Un plugin de commande fictive :

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "orders-plugin",
  "version": "1.0.0",
  "description": "Look up fictional order A-1042. No refunds.",
  "license": "Apache-2.0",
  "keywords": ["orders"]
}

Un champ de premier niveau inconnu doit être signalé et ignoré. Le chargement continue si le reste est valide. Un champ requis manquant, un mauvais type ou un nom illégal rejette tout le paquet. Aucun composant n’est découvert ni exécuté. Les données propres au client vont dans extensions, clé en domaine inversé, chaque valeur un objet. Aucun autre fichier ne peut remplacer les champs centraux du manifeste racine.

Skills et MCP ne s’écrivent pas dans le manifeste

La spec fixe les emplacements. Chaque enfant immédiat de skills/ qui contient un fichier régulier nommé exactement SKILL.md est un skill. Le frontmatter et les dossiers scripts/, references/ et assets/ appartiennent à la spec Agent Skills. Cette spec ne dit que comment un skill est découvert, pas comment un client le montre au modèle. MCP ne doit pas être inline dans plugin.json et ne doit pas changer de chemin. Les seuls champs de premier niveau de mcp.json sont $schema et mcpServers. Un objet mcpServers vide est valide. Les deux versions de $schema doivent correspondre. L’identifiant MCP 1.0.0 est https://agent-plugins.org/schemas/1.0.0/mcp.schema.json. stdio exige type et command. args, env et cwd sont optionnels. Un chemin qui commence par ./ est relatif à la racine du plugin. ../ ne doit pas sortir de cette racine. Le client développe PLUGIN_ROOT et PLUGIN_DATA :

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "orders": {
      "type": "stdio",
      "command": "./bin/orders",
      "args": ["--data", "${PLUGIN_DATA}/orders"],
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

Un serveur distant utilise streamable-http et exige url. sse est un transport optionnel déprécié. La spec ne définit pas de repli si une connexion échoue. Un client conforme prend en charge au moins l’un de stdio et streamable-http, et devrait prendre les deux. La version 1.0.0 n’a pas de champs OAuth ou de référence d’identifiants portables. L’authentification reste au client. Les règles de chemin couvrent les fichiers du paquet. Elles ne mettent pas le sous-processus dans un bac à sable. Les arguments d’outil ont encore besoin de leur porte Schema : pourquoi l’IA a besoin de JSON Schema.

Une partie cassée s’arrête à sa propre limite

La spec sépare les échecs. Ne lisez pas un mauvais JSON comme un paquet mort :

Ce qui a mal tourné Ce que le client doit faire
plugin.json manque d’un champ requis, ou le type ou le nom est illégal Rejeter le paquet. Ne rien découvrir, ne rien exécuter.
Un champ de premier niveau inconnu Le signaler et l’ignorer. Continuer si le reste est valide. Ne pas lui inventer un sens.
skills/ est absent, ou un SKILL.md ne suit pas la spec Agent Skills Un dossier absent n’est pas une erreur. Sauter le skill invalide. Les autres skills et MCP continuent.
La version de mcp.json ne correspond pas, ou une entrée serveur est invalide Un écart de version invalide seulement MCP, pas les skills. Un mauvais serveur ne désactive que cette entrée. Un mcp.json de premier niveau invalide désactive tous les serveurs MCP du plugin.

Un client ignore les types de composants qu’il ne prend pas en charge. Un dossier en domaine inversé comme com.example.client/ appartient à un client. Les autres doivent pouvoir le sauter. Les espaces de noms inconnus dans extensions sont ignorés de la même façon. Comment un bac à sable arrête un tools/call déjà envoyé est une autre couche : OpenShell et Sentry.

Six contrôles avant de livrer un plugin

Ne commencez pas en collant une URL de serveur MCP dans plugin.json :

  1. Écrire d’abord le plugin.json racine. Seulement les clés de la liste fermée. Un nom comme orders-plugin reste en minuscules.
  2. Mettre chaque skill dans un enfant immédiat. skills/lookup-order/SKILL.md. Un dossier plus profond ne sera pas découvert.
  3. N’écrire MCP que dans mcp.json. Chaque entrée a type. Un serveur local utilise stdio et ./bin/orders. Pas de ../.
  4. Pointer les deux $schema vers 1.0.0. En cas d’écart, les skills peuvent encore se charger. MCP non.
  5. Laisser les identifiants au client. mcp.json en 1.0.0 n’a pas de champ secret portable. Ne commitez pas un jeton dans env ou headers.
  6. Donner aux arguments d’outil leur propre Schema. Le manifeste ne fait que situer le serveur. L’hôte vérifie encore A-1042 avant d’exécuter une consultation.

Un plugin sans skills/ et sans mcp.json peut rester valide. Seul plugin.json est requis.

Étalez les deux JSON avant de fusionner

Un chargement raté est soit un paquet rejeté, soit un serveur MCP sauté. Séparez cela avant de modifier le prompt.

  • formater plugin.json et mcp.json, puis validation Schema pour voir si une clé de premier niveau est en trop ou si $schema manque.
  • Utilisez extraction JSONPath pour $.name, $.mcpServers.orders.type et $.mcpServers.orders.command.
  • JSON Diff le manifeste avec la révision précédente. Vérifiez qu’un chemin ne sort pas de la racine du plugin.
  • Confirmez que skills/lookup-order/SKILL.md est un fichier régulier dans un enfant immédiat, pas un fichier plus profond.
  • masquer d’abord les jetons de la config. Ne collez pas un mcp.json qui contient un secret dans un formateur public. JSONSort tourne dans le navigateur.

Si les deux JSON se reconstruisent contre la liste fermée et que les dossiers sont aux places fixes, le plugin correspond à 1.0.0. Le manifeste ne décide pas si le client exécute la consultation.

Pièges fréquents

  • Écrire cela comme le format privé de Google. Les textes du 6 août 2026 décrivent une spec entre éditeurs. Google a rejoint ce jour-là comme mainteneur principal.
  • Mettre mcpServers dans plugin.json. La spec interdit la config inline et le déplacement du chemin. Les clients ne lisent que le mcp.json racine.
  • Deviner le transport d’après la forme de l’objet. Chaque serveur a besoin de type. Il n’y a pas de règle qu’une valeur en forme d’URL signifie HTTP.
  • Mettre une clé d’API dans mcp.json. La version 1.0.0 n’a pas de champ d’identifiants portable. L’authentification reste au client. L’exemple utilise une commande fictive.
  • Jeter tous les skills parce qu’un serveur n’a pas démarré. Un échec de serveur ne désactive que cette entrée. Un mcp.json de premier niveau invalide désactive MCP. Les skills continuent de se charger.
  • Utiliser ce texte pour réécrire MCP contre le function calling. Il montre seulement comment un plugin place une config MCP existante dans un fichier fixe.

FAQ

Un répertoire avec seulement plugin.json est-il un plugin valide ?

Oui. plugin.json est le seul fichier requis. Si skills/ ou mcp.json est absent, le client charge ce qui est là. Ce n’est pas une erreur. Un champ requis manquant ou un nom illégal rejette tout le paquet.

Que se passe-t-il si les deux valeurs $schema divergent ?

La configuration MCP est invalide. Les skills et les autres types de composants restent valides. En 1.0.0, les deux fichiers utilisent l’identifiant 1.0.0 de la spec, et les versions doivent correspondre.

SKILL.md peut-il vivre sous skills/orders/extra/ ?

Il ne sera pas découvert. Le client ne regarde que les enfants immédiats de skills/ et ne descend pas plus profond. Le fichier doit être un fichier régulier tel que skills/lookup-order/SKILL.md.

Faut-il déclarer à la fois stdio et streamable-http ?

Non. Un serveur utilise un type. stdio a besoin de command. streamable-http a besoin de url. sse est déprécié, et un client peut l’omettre. La spec ne change pas de transport quand une connexion échoue.

Ce JSON consulte-t-il la commande tout seul ?

Non. plugin.json nomme le plugin. mcp.json dit au client où est le serveur. L’hôte exécute tools/call. Un argument comme A-1042 a besoin de sa propre vérification Schema. Le manifeste n’a pas de champ secret portable.

Conclusion

Agent Plugins 1.0.0 range Agent Skills et serveurs MCP dans un répertoire racine que l’on peut déplacer. plugin.json verrouille la version de la spec et le nom. Les emplacements des composants ne se changent pas dans le manifeste.

Vérifiez que orders-plugin est dans plugin.json, que ./bin/orders est dans mcp.json, et que SKILL.md est dans un enfant immédiat. Quand ces trois-là sont aux places fixes, le client n’a pas à deviner où vous avez caché la config.

Pour aller plus loin

Historique : Première publication