AI-Entwicklung

Was ist Agent Plugins 1.0.0? plugin.json, MCP, Agent Skills und das JSON-Layout (2026)

Ca. 15 Min.

Agent Plugins 1.0.0 ist ein offener Verzeichnisvertrag, kein weiteres Tool-Calling-Protokoll. Die plugin.json im Wurzelverzeichnis nennt nur Paket und Spezifikationsversion. Skills liegen in skills/. MCP-Server stehen nur in der Wurzel-mcp.json. Das Modell füllt nur JSON. Der Host verbindet sich mit dem Server.

Vor dem Lesen

Datei Was die Spezifikation verlangt Was sie nicht tut
plugin.json Das einzige Manifest, in der Wurzel. $schema und name sind Pflicht. Die Feldliste ist geschlossen MCP darf nicht inline stehen und kein Pfad darf wandern
skills/ Nur SKILL.md in einem unmittelbaren Unterverzeichnis. Das Format gehört zur Agent-Skills-Spezifikation Keine Rekursion. Ein fehlendes Verzeichnis ist kein Fehler
mcp.json Oben nur $schema und mcpServers. Jeder Server braucht type Führt kein Tool aus. 1.0.0 hat keine portablen Zugangsdatenfelder
Erweiterungsverzeichnis Ein Reverse-Domain-Ordner wie com.example.client/. extensions nutzt dieselben Namensräume Andere Clients müssen ihn ignorieren können

Fakten aus der Spezifikation Agent Plugins 1.0.0, der Vercel-Mitteilung und dem Google Developers Blog, alle vom 6. August 2026. Bestellung A-1042 und orders.example.com sind fiktiv.

Es packt Skills und MCP-Server in ein Verzeichnis, das Sie verschieben können

Agent Plugins 1.0.0 wurde am 6. August 2026 öffentlich. Die Core Maintainer kamen damals von Amazon, Cursor, Microsoft, OpenAI und Vercel. Am selben Tag schrieb der Google Developers Blog, Google trete dieser Gruppe bei, vertreten durch Kevin Hou, und beginne, Unterstützung in eigene Produkte zu bauen. Das ist kein privates Format, das Google allein veröffentlicht hat. Die Spezifikation definiert zwei portable Komponententypen: Agent Skills und MCP-Server. Installation, Verteilung, Policy und Oberfläche bleiben beim Client. Ein Client prüft die plugin.json in der Wurzel, bevor er Komponenten sucht. Beim Laden darf er das Schema nicht über das Netz holen.

  • Manifest: $schema muss https://agent-plugins.org/schemas/1.0.0/plugin.schema.json sein. name ist Pflicht.
  • Skills: skills/<Name>/SKILL.md. Nur unmittelbare Kinder. Keine Rekursion.
  • MCP: mcp.json in der Wurzel. Jeder Eintrag nennt stdio, streamable-http oder optionales altes sse.

Wie MCP auf der Leitung läuft: wie ein Coding Agent MCP aufruft. Wie ein MCP-Tool-Schema sich von Function Calling unterscheidet: MCP-Tool-Schema und Function Calling. Dieser Text schreibt die beiden nicht um. Er sagt nur, was die zwei JSON-Dateien im Plugin-Verzeichnis besitzen.

Die Feldliste von plugin.json ist geschlossen

Erlaubt sind nur $schema, name, version, description, author, homepage, repository, license, keywords und extensions. Die ersten beiden sind Pflicht. Ein Name hat 1 bis 64 Zeichen, nur Kleinbuchstaben, Ziffern, Bindestriche und Punkte, muss mit Buchstabe oder Ziffer beginnen und enden und darf weder -- noch .. enthalten. Semantic Versioning ist für version empfohlen, aber ein Nicht-SemVer-String ist allein kein Ablehnungsgrund. author darf nur name, email und url enthalten. Ein fiktives Bestell-Plugin:

{
  "$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"]
}

Ein unbekanntes Top-Level-Feld muss gemeldet und ignoriert werden. Das Laden geht weiter, wenn der Rest gültig ist. Ein fehlendes Pflichtfeld, ein falscher Typ oder ein illegaler Name lehnt das ganze Paket ab. Keine Komponente wird entdeckt oder ausgeführt. Client-Daten gehören nach extensions, Schlüssel ist ein Reverse-Domain-Namensraum, jeder Wert ein Objekt. Keine andere Datei kann die Kernfelder des Wurzelmanifests überschreiben.

Skills und MCP dürfen nicht im Manifest stehen

Die Spezifikation fixiert die Orte. Jedes unmittelbare Kind von skills/ mit einer regulären Datei namens genau SKILL.md ist ein Skill. Frontmatter sowie scripts/, references/ und assets/ gehören zur Agent-Skills-Spezifikation. Diese Spezifikation sagt nur, wie ein Skill gefunden wird, nicht wie ein Client ihn einem Modell zeigt. MCP darf nicht in plugin.json stehen und nicht auf einen anderen Pfad wandern. Oben in mcp.json sind nur $schema und mcpServers erlaubt. Ein leeres mcpServers ist gültig. Die beiden $schema-Versionen müssen übereinstimmen. Der MCP-Bezeichner für 1.0.0 ist https://agent-plugins.org/schemas/1.0.0/mcp.schema.json. stdio verlangt type und command. args, env und cwd sind optional. Ein Pfad mit ./ ist relativ zur Plugin-Wurzel. ../ darf diese Wurzel nicht verlassen. Der Client expandiert PLUGIN_ROOT und 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}"
    }
  }
}

Ein entfernter Server nutzt streamable-http und braucht url. sse ist ein veralteter optionaler Transport. Die Spezifikation definiert keinen Fallback, wenn eine Verbindung scheitert. Ein konformer Client unterstützt mindestens eines von stdio und streamable-http und sollte beide unterstützen. Version 1.0.0 hat keine portablen OAuth- oder Zugangsdatenfelder. Authentifizierung bleibt beim Client. Pfadregeln gelten für Dateien im Paket. Sie sandboxen den Subprozess nicht. Tool-Argumente brauchen weiter ein eigenes Schema-Tor: warum KI JSON Schema braucht.

Ein defekter Teil stoppt an der eigenen Grenze

Die Spezifikation trennt Fehler. Lesen Sie eine schlechte JSON-Datei nicht als totes Paket:

Was schiefging Was der Client tun muss
plugin.json fehlt ein Pflichtfeld, oder Typ oder Name ist illegal Paket ablehnen. Nichts entdecken, nichts ausführen.
Ein unbekanntes Top-Level-Feld Melden und ignorieren. Weiterladen, wenn der Rest gültig ist. Keine Bedeutung erfinden.
skills/ fehlt, oder eine SKILL.md verletzt die Agent-Skills-Spezifikation Ein fehlendes Verzeichnis ist kein Fehler. Den schlechten Skill überspringen. Andere Skills und MCP laufen weiter.
Die mcp.json-Version passt nicht, oder ein Servereintrag ist ungültig Eine Versionsabweichung macht nur MCP ungültig, nicht die Skills. Ein schlechter Server deaktiviert nur diesen Eintrag. Eine ungültige Top-Level-mcp.json deaktiviert jeden MCP-Server des Plugins.

Ein Client ignoriert Komponententypen, die er nicht unterstützt. Ein Reverse-Domain-Verzeichnis wie com.example.client/ gehört zu einem Client. Andere müssen es überspringen können. Unbekannte Namensräume in extensions werden genauso ignoriert. Wie eine Sandbox einen schon gesendeten tools/call stoppt, ist eine andere Schicht: OpenShell und Sentry.

Sechs Prüfungen, bevor Sie ein Plugin ausliefern

Beginnen Sie nicht damit, eine MCP-Server-URL in plugin.json zu kleben:

  1. Zuerst die plugin.json in der Wurzel schreiben. Nur Schlüssel aus der geschlossenen Liste. Ein Name wie orders-plugin bleibt klein.
  2. Jeden Skill in ein unmittelbares Kind legen. skills/lookup-order/SKILL.md. Ein tieferes Verzeichnis wird nicht gefunden.
  3. MCP nur in mcp.json schreiben. Jeder Eintrag hat type. Lokal: stdio und ./bin/orders. Kein ../.
  4. Beide $schema-Werte auf 1.0.0 setzen. Bei Abweichung können Skills noch laden. MCP nicht.
  5. Zugangsdaten beim Client lassen. mcp.json in 1.0.0 hat kein portables Geheimnisfeld. Keinen Token in env oder headers committen.
  6. Tool-Argumenten ein eigenes Schema geben. Das Manifest findet nur den Server. Der Host prüft A-1042, bevor er eine Abfrage ausführt.

Ein Plugin ohne skills/ und ohne mcp.json kann gültig sein. Nur plugin.json ist Pflicht.

Beide JSON-Dateien ausbreiten, bevor Sie mergen

Ein fehlgeschlagener Ladevorgang ist entweder ein abgelehntes Paket oder ein übersprungener MCP-Server. Das trennen, bevor Sie den Prompt ändern.

  • plugin.json und mcp.json formatieren, dann mit Schema prüfen prüfen, ob ein Top-Level-Schlüssel zu viel ist oder $schema fehlt.
  • JSONPath extrahieren für $.name, $.mcpServers.orders.type und $.mcpServers.orders.command.
  • Das Manifest gegen die vorige Revision JSON Diff. Prüfen, dass ein Pfad die Plugin-Wurzel nicht verlässt.
  • Bestätigen, dass skills/lookup-order/SKILL.md eine reguläre Datei in einem unmittelbaren Kind ist, keine tiefere Datei.
  • Tokens in der Konfiguration zuerst schwärzen. Eine mcp.json mit Geheimnis nicht in einen öffentlichen Formatierer kleben. JSONSort läuft im Browser.

Wenn beide JSON-Dateien gegen die geschlossene Feldliste neu aufgebaut werden und die Verzeichnisse an den festen Orten sitzen, entspricht das Plugin 1.0.0. Ob der Client die Abfrage ausführt, entscheidet das Manifest nicht.

Häufige Fallen

  • Das als Googles privates Plugin-Format schreiben. Die Texte vom 6. August 2026 beschreiben eine herstellerübergreifende Spezifikation. Google trat an dem Tag als Core Maintainer bei.
  • mcpServers in plugin.json setzen. Die Spezifikation verbietet Inline-Konfiguration und das Verschieben des Pfads. Clients lesen nur die mcp.json in der Wurzel.
  • Den Transport aus der Objektform raten. Jeder Server braucht type. Es gibt keine Regel, dass ein URL-förmiger Wert HTTP bedeutet.
  • Einen API-Schlüssel in mcp.json legen. Version 1.0.0 hat kein portables Zugangsdatenfeld. Authentifizierung bleibt beim Client. Das Beispiel nutzt eine fiktive Bestellung.
  • Alle Skills verwerfen, weil ein Server nicht startet. Ein Serverfehler deaktiviert nur diesen Eintrag. Eine schlechte Top-Level-mcp.json deaktiviert MCP. Skills werden weiter geladen.
  • Diesen Text nutzen, um MCP gegen Function Calling neu zu schreiben. Er zeigt nur, wie ein Plugin eine vorhandene MCP-Konfiguration in eine feste Datei legt.

FAQ

Ist ein Verzeichnis nur mit plugin.json ein gültiges Plugin?

Ja. plugin.json ist die einzige Pflichtdatei. Fehlen skills/ oder mcp.json, lädt der Client, was da ist. Das ist kein Fehler. Ein fehlendes Pflichtfeld oder ein illegaler Name lehnt das ganze Paket ab.

Was passiert, wenn die beiden $schema-Werte nicht übereinstimmen?

Die MCP-Konfiguration ist ungültig. Skills und andere Komponententypen bleiben gültig. Bei 1.0.0 nutzen beide Dateien den 1.0.0-Bezeichner aus der Spezifikation, und die Versionen müssen übereinstimmen.

Darf SKILL.md unter skills/orders/extra/ liegen?

Sie wird nicht gefunden. Der Client sieht nur unmittelbare Kinder von skills/ und sucht nicht rekursiv. Die Datei muss eine reguläre Datei wie skills/lookup-order/SKILL.md sein.

Muss ich stdio und streamable-http beide deklarieren?

Nein. Ein Server nutzt einen type. stdio braucht command. streamable-http braucht url. sse ist veraltet, ein Client darf es weglassen. Die Spezifikation wechselt den Transport nicht, wenn eine Verbindung scheitert.

Schlägt dieses JSON die Bestellung von selbst nach?

Nein. plugin.json benennt das Plugin. mcp.json sagt dem Client, wo der Server ist. Der Host führt tools/call aus. Ein Argument wie A-1042 braucht eine eigene Schema-Prüfung. Das Manifest hat kein portables Geheimnisfeld.

Fazit

Agent Plugins 1.0.0 packt Agent Skills und MCP-Server in ein Wurzelverzeichnis, das Sie verschieben können. plugin.json sperrt Spezifikationsversion und Namen. Komponentenorte lassen sich im Manifest nicht ändern.

Prüfen Sie, dass orders-plugin in plugin.json steht, ./bin/orders in mcp.json und SKILL.md in einem unmittelbaren Kind. Wenn diese drei an den festen Orten sitzen, muss der Client nicht raten, wo Sie die Konfiguration versteckt haben.

Weiterlesen

Änderungsprotokoll: Erstveröffentlichung