# Agent Plugins sind npm für Agent-Verhalten — aber ohne Lockfile Canonical URL: https://huecki.com/blog/agent-plugins-npm-fuer-agent-verhalten/ Markdown URL: https://huecki.com/blog/agent-plugins-npm-fuer-agent-verhalten.md Language: German Published: 2026-08-06 Updated: 2026-08-06 Author: Dominic Hückmann Topic: AI Agent Infrastructure - Agent topics: Agent Security, Context Engineering, Agent Evals - Tags: AI Agents, Agent Plugins, Agent Skills, MCP, Codex, Cursor, VS Code, AI Security - Audience: AI Engineers, Agent-Plattform-Teams, Entwickler mit Codex, Cursor oder VS Code, Engineering Leads, Security Engineers - Concepts: agent-plugins, agent-skills, model-context-protocol, plugin-portability, agent-supply-chain, capability-diff, plugin-evals, plugin-sandboxing Thesis: Agent Plugins lösen die Verteilung von Agent-Fähigkeiten, aber nicht deren Vertrauensproblem: Das Paket kann portabel sein, während Berechtigungen, Sandbox, Updates und Blast Radius weiterhin vom jeweiligen Client abhängen. Content status: field-note ## Summary Agent Plugins machen aus Skills und MCP-Konfigurationen ein portables Paket. Der Guide zeigt den kleinsten Aufbau, die Integration in mehrere Clients sowie die fehlenden Produktionskontrollen für Permissions, Updates, Evals und Rollback. ## Description Agent Plugins bündeln Skills und MCP-Verbindungen für mehrere AI Agents. So baust, integrierst, testest und sicherst du ein portables Plugin praktisch ab. ## Body ## Ein Plugin. Drei Agents. Drei verschiedene Risiken. Du baust einen kleinen Deployment-Assistenten. Er soll: 1. die Deployment-Regeln deines Teams kennen, 2. den richtigen Build ausführen, 3. den Status aus eurer Plattform lesen, 4. und erst nach Bestätigung deployen. Heute verteilst du dafür oft mehrere Dateien: ```txt AGENTS.md für Codex .cursor/rules für Cursor ein Skill-Verzeichnis eine MCP-Konfiguration zwei Setup-Nachrichten im Team-Chat ``` Eine Woche später sind drei Versionen im Umlauf. [Agent Plugins 1.0](https://agent-plugins.org/specification) will genau dieses Packaging-Problem lösen. Du bündelst die wiederverwendbaren Teile einmal und kompatible Clients können sie laden. Das klingt wie npm für Agents. Und genau das ist es — mit einem wichtigen Unterschied: > Ein npm-Paket verändert deinen Code. Ein Agent Plugin kann zusätzlich verändern, wie dein Agent denkt, welche Tools er sieht und welche Aktionen er ausführen darf. Darum brauchen Plugins nicht nur einen Package Manager. Sie brauchen eine nachvollziehbare Berechtigungs- und Verhaltenskontrolle. ## Die vier Ebenen in einfacher Sprache Die Begriffe werden schnell durcheinandergeworfen. Dieses Modell reicht für den Einstieg: ```txt Skill = Wie soll der Agent vorgehen? MCP = Welche Tools und Live-Daten bekommt er? Plugin = Wie werden diese Fähigkeiten zusammen verteilt? Client = Unter welchen Regeln darf das alles laufen? ``` Ein Skill kann zum Beispiel sagen: ```txt Prüfe vor jedem Production Deploy: - aktuellen Branch - grünen Build - offene Migrationen - explizite Freigabe des Nutzers ``` Ein MCP-Server kann dazu Tools liefern: ```txt get_build_status list_open_migrations create_deployment ``` Das Plugin packt Skill und MCP-Konfiguration zusammen. Codex, Cursor oder VS Code bleiben aber der **Client**. Der Client entscheidet, ob ein lokaler Prozess starten darf, wann der Nutzer bestätigen muss, welche Dateien sichtbar sind und welche Credentials verfügbar werden. Der Standard macht das Paket portabel. Er macht die Autorität nicht portabel. ## Was Agent Plugins 1.0 wirklich standardisiert Der offene Standard ist absichtlich klein. Ein portables Plugin sieht im Kern so aus: ```txt deploy-helper/ ├── plugin.json ├── skills/ │ └── safe-deploy/ │ ├── SKILL.md │ ├── scripts/ │ └── references/ └── mcp.json ``` Version 1.0 definiert genau zwei portable Komponenten: - **Agent Skills** unter `skills/` - **MCP-Server-Konfigurationen** in `mcp.json` Nicht Teil des portablen Kerns sind aktuell unter anderem: - Hooks - Subagents und Custom Agents - Slash Commands - LSP-Server - UI-Komponenten - Marketplace und Update-Mechanik - Permission Prompts und Sandbox - OAuth und Secret Storage Clients dürfen diese Dinge über eigene Erweiterungen ergänzen. Deshalb kann ein Plugin in mehreren Tools funktionieren, ohne überall exakt dasselbe zu tun. Das ist kein Fehler im Standard. Es ist die Grenze seines Versprechens. ## Baue den kleinsten portablen Plugin-Kern Wir bauen einen `deploy-helper`, der zuerst nur erklärt, wie ein sicherer Deploy vorbereitet wird. ### 1. Das Manifest Lege im Plugin-Root eine `plugin.json` an: ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "deploy-helper", "version": "1.0.0", "description": "Prepare and verify deployments before execution", "author": { "name": "Acme Platform Team" }, "license": "MIT" } ``` Das Manifest gibt dem Paket eine Identität. Es ist **keine Berechtigungsliste**. Aus `plugin.json` kannst du nicht ablesen, ob ein enthaltenes Skript später das Netzwerk nutzt oder ein MCP-Tool Production verändern darf. ### 2. Der Skill Lege `skills/safe-deploy/SKILL.md` an: ```md --- name: safe-deploy description: Prepare a deployment when the user asks to deploy, release, ship, or verify production readiness. --- Before a deployment: 1. Identify environment and target revision. 2. Check build and test evidence for that exact revision. 3. List pending database migrations. 4. Show the planned changes and expected impact. 5. Ask for explicit confirmation before any external mutation. Never treat an old green build as evidence for the current revision. Never deploy when environment or target revision is ambiguous. ``` Die `description` ist wichtiger, als sie aussieht. Viele Clients laden zuerst nur Name und Beschreibung. Erst wenn der aktuelle Task passt, liest der Agent den vollständigen Skill. Eine zu breite Description aktiviert den Skill ständig. Eine zu enge macht ihn unsichtbar. Teste deshalb nicht nur: ```txt Deploy this service. ``` Sondern auch negative Fälle: ```txt Explain how deployments work. # darf nicht deployen Review this Dockerfile. # Skill vermutlich unnötig Deploy something to production. # muss Ziel und Revision klären ``` ### 3. MCP nur hinzufügen, wenn Live-Zugriff nötig ist Der Skill kann ohne MCP funktionieren. Er erklärt dann den Prozess, hat aber keine Live-Daten. Für einen lokalen MCP-Server kann `mcp.json` so aussehen: ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "deployment-status": { "type": "stdio", "command": "./bin/deployment-mcp", "args": ["--data", "${PLUGIN_DATA}/state"], "cwd": "${PLUGIN_ROOT}" } } } ``` Oder für einen entfernten Server: ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "deployment-api": { "type": "streamable-http", "url": "https://deploy.example.com/mcp" } } } ``` Keine API Keys in diese Datei schreiben. Die Spezifikation sagt ausdrücklich, dass Header sichtbare Paketdaten und kein portabler Secret-Mechanismus sind. Authentifizierung und Credential Storage bleiben Aufgabe des Clients. Und noch wichtiger: Ein valider relativer Pfad ist keine Sandbox. Der Standard verhindert bestimmte Pfad-Escapes aus dem Paket. Er verhindert nicht automatisch, dass ein gestarteter Prozess später andere Dateien oder das Netzwerk nutzt. ## Integration: ein Kern, dünne Client-Adapter In einer perfekten Welt lädt jeder Client nur die Root-Dateien des offenen Standards. In der Übergangsphase existieren zusätzlich ältere oder reichere Plugin-Formate. Die aktuelle OpenAI-Dokumentation beschreibt zum Beispiel weiterhin `.codex-plugin/plugin.json`; VS Code und GitHub Copilot erkennen mehrere Manifest-Orte und eigene Komponenten wie Hooks oder Agents. Die wartbare Lösung lautet: ```txt portable core ├── plugin.json ├── skills/ └── mcp.json thin adapters ├── .codex-plugin/ ├── .claude-plugin/ └── vendor namespaces or manifests ``` Halte die eigentliche Arbeitsanweisung im portablen Skill. Client-Dateien sollten nur verbinden oder Fähigkeiten ergänzen, nicht den gesamten Workflow kopieren. Sonst hast du wieder das Problem, das Plugins eigentlich lösen sollen: drei leicht unterschiedliche Wahrheiten. ### Codex und ChatGPT OpenAI unterstützt öffentliche, persönliche und repo-lokale Plugin-Quellen. Für das Scaffolding kann der eingebaute `plugin-creator` genutzt werden. Repo-lokale Marketplaces liegen laut aktueller Dokumentation unter: ```txt $REPO_ROOT/.agents/plugins/marketplace.json ``` Marketplace-Quellen lassen sich in der Codex CLI verwalten: ```bash codex plugin marketplace add owner/repo codex plugin marketplace list codex plugin marketplace upgrade marketplace-name ``` Wichtig: `upgrade` ist eine Supply-Chain-Aktion. In Production sollte ein Team nicht blind einem beweglichen Branch folgen, sondern eine geprüfte Revision pinnen und Änderungen vor der Aktivierung diffen. ### VS Code und GitHub Copilot VS Code bietet eine Agent-Plugins-Ansicht in der Extensions-Seitenleiste und kann Plugins aus konfigurierten Marketplaces oder direkt aus Git-Repositories installieren. GitHub Copilot nutzt ebenfalls Plugin-Manifeste und Marketplaces. Beide unterstützen zusätzliche Komponenten, die über den portablen v1-Kern hinausgehen. Ein Hook kann zum Beispiel Shell-Kommandos an Lifecycle-Punkten ausführen. Das ist mächtig, aber nicht mehr nur „ein bisschen Kontext für den Agenten“. Microsoft warnt deshalb ausdrücklich: Plugin-Inhalte und Publisher vor der Installation prüfen. ### Cursor Cursor bündelt in seinem Plugin-Modell Skills, MCP-Server, Regeln, Subagents und Hooks. Der portable Kern kann geteilt werden, die zusätzlichen Cursor-Funktionen brauchen aber eine eigene Prüfung. Teste nicht nur, ob der Skill in Cursor auftaucht. Teste, ob er bei denselben Prompts aktiviert wird, dieselben Grenzen respektiert und vor derselben externen Aktion eine Bestätigung verlangt. ## Der Integrationstest, der meistens fehlt „Plugin wurde installiert“ ist kein bestandener Test. Baue eine kleine Kompatibilitätsmatrix: ```txt Test Codex Cursor VS Code Skill bei Deploy-Task aktiv ✓ ✓ ✓ Bei Erklär-Task inaktiv ✓ ✓ ✓ Aktuelle Revision geprüft ✓ ✓ ✓ Production braucht Bestätigung ✓ ✓ ✓ MCP Auth separat ✓ ✓ ✓ Offline-Fehler verständlich ✓ ✓ ✓ ``` Für jeden Client brauchst du mindestens vier Testklassen: 1. **Positive Activation:** Der Skill wird beim passenden Task geladen. 2. **Negative Activation:** Der Skill bleibt bei unpassenden Tasks draußen. 3. **Permission Boundary:** Schreibende oder externe Aktionen brauchen die erwartete Freigabe. 4. **Failure Behavior:** Ohne MCP, Auth oder Netzwerk darf der Agent nicht raten oder Erfolg vortäuschen. Führe dieselben Prompts nach jedem Plugin-Update erneut aus. Genau dafür sind Replay Evals gut: nicht um eine magische Gesamtpunktzahl zu erzeugen, sondern um Verhaltensänderungen sichtbar zu machen. ## Das fehlende Feature: ein Capability Diff Bei einer normalen Dependency zeigt dir ein Diff neue Dateien und Versionsnummern. Bei einem Agent Plugin willst du zusätzlich wissen: ```txt + neuer Skill-Trigger: "deploy", "release", "ship" + neues lokales Binary: ./bin/deployment-mcp + neuer Remote Origin: https://deploy.example.com + neues schreibendes Tool: create_deployment ~ Bestätigung verschoben: vor Plan → nach Plan ~ benötigtes Credential: read-only → deploy-staging ``` Das ist ein **Capability Diff**. Es beschreibt nicht nur, welcher Text geändert wurde, sondern welche neue Wirkung möglich wird. Bis Clients das nativ anzeigen, solltest du diesen Diff im Review selbst erzeugen: - Skill-Descriptions und Instruktionen vergleichen - neue Skripte, Binaries und Hooks markieren - MCP-Origins und Tool-Schemas vergleichen - neue Environment-Variablen und Credentials auflisten - Permission- und Sandbox-Annahmen je Client dokumentieren - Eval-Ergebnisse vorher und nachher gegenüberstellen ## Ein Production Contract zum Kopieren Speichere neben jedem freigegebenen Plugin einen kleinen Datensatz: ```yaml plugin: deploy-helper source: https://github.com/acme/agent-plugins revision: 8f41c9d portable_components: - skills/safe-deploy - mcp.json local_execution: - ./bin/deployment-mcp remote_origins: - https://deploy.example.com credentials: - name: deploy-staging scope: staging-only clients_tested: - codex - cursor - vscode eval_suite: deploy-helper-v4 approved_by: platform-security review_after: 2026-09-06 rollback_to: 71a2e10 ``` Der Datensatz ist bewusst langweilig. Langweilige Kontrolle ist hier ein Feature. Er beantwortet die Fragen, die `plugin.json` nicht beantworten soll: - Welche Version wurde wirklich geprüft? - Was darf lokal laufen? - Wohin fließen Daten? - Welches Konto darf handeln? - In welchen Clients wurde das Verhalten getestet? - Wie kommen wir zurück? ## Die Fünf-Minuten-Prüfung vor jeder Installation Bevor du ein Agent Plugin aktivierst: ```txt [ ] Quelle und Publisher geprüft [ ] immutable Commit oder Release gepinnt [ ] alle Skill-Trigger gelesen [ ] Skripte, Binaries und Hooks aufgelistet [ ] alle MCP-Origins und Tools geprüft [ ] Credentials separat und minimal vergeben [ ] positive und negative Activation getestet [ ] externe Mutationen brauchen Bestätigung [ ] Rollback-Version dokumentiert ``` Für ein reines Text-Skill ohne Skripte und MCP ist die Prüfung klein. Für ein Plugin mit lokalen Hooks, Remote-MCP und Production-Credentials ist sie ein Security Review. Beides nur „Plugin installieren“ zu nennen, versteckt den wichtigsten Unterschied. ## Das eigentliche Versprechen Agent Plugins machen Agents nicht automatisch intelligenter. Sie machen Fähigkeiten **verteilbar**. Das ist wertvoll: Ein Team kann denselben geprüften Deployment-Workflow in Codex, Cursor und VS Code anbieten. Verbesserungen landen an einer Stelle. Neue Kolleginnen installieren eine Capability statt fünf Setup-Snippets zu kopieren. Aber Distribution verstärkt gute und schlechte Pakete gleichermaßen. Darum ist der nächste Schritt nach dem offenen Format kein größerer Marketplace. Es ist ein besserer Trust Layer: ```txt Provenance. Capability Diff. Least Privilege. Replay Evals. Rollback. ``` Das Paket darf portabel sein. Das Vertrauen muss sich jede Version neu verdienen. ## FAQ ### Was ist ein Agent Plugin? Ein installierbares Verzeichnis mit Manifest, optionalen Agent Skills und optionalen MCP-Server-Konfigurationen. Der offene Standard definiert die gemeinsame Paketstruktur, während der jeweilige Client Installation, Berechtigungen und Sandbox kontrolliert. ### Was ist der Unterschied zwischen Skill, MCP und Plugin? Ein Skill beschreibt, wie der Agent arbeiten soll. MCP verbindet ihn mit Tools und Live-Daten. Das Plugin bündelt beides als installierbare Einheit. ### Funktioniert ein Agent Plugin unverändert in Codex, Cursor und VS Code? Der portable Kern aus Skills und MCP-Konfiguration kann wiederverwendet werden. Hooks, Subagents, Commands, UI, Installation und Berechtigungen können sich je Client unterscheiden und benötigen teilweise dünne Adapter. ### Ist ein valides Plugin automatisch sicher? Nein. Schema-Validierung prüft Struktur und einige Pfadregeln. Sie beweist nicht, dass Instruktionen korrekt, Skripte ungefährlich, MCP-Server vertrauenswürdig oder angeforderte Credentials angemessen sind. ### Wie sollte ein Team Agent Plugins aktualisieren? Immutable Version oder Commit pinnen, jede Änderung als Capability Diff prüfen, Evals wiederholen, Credentials separat freigeben und eine bekannte funktionierende Version für den Rollback behalten. ## Related - Zeigt, warum installierte Agent-Fähigkeiten vor der Aktivierung geprüft werden müssen.: agent-skills-need-a-supply-chain-gate - Vertieft Provenance, Scanning und Freigabe automatisch erzeugter Skills.: automatisch-generierte-agent-skills-supply-chain - Erklärt, warum MCP-Tools verständliche Berechtigungslabels brauchen.: mcp-tools-permission-labels ## Source References - [Agent Plugins overview](https://agent-plugins.org/) (official standard documentation) - [Agent Plugins Specification 1.0.0](https://agent-plugins.org/specification) (specification) - [Compatible Agent Plugins clients](https://agent-plugins.org/compatible-clients) (official compatibility matrix) - [Build an Agent Plugin](https://agent-plugins.org/plugin-authors) (official guide) - [Implement an Agent Plugins client](https://agent-plugins.org/client-implementers) (official guide) - [Package plugins for ChatGPT and Codex](https://developers.openai.com/plugins/build/plugins) (vendor documentation) - [Agent plugins in VS Code](https://code.visualstudio.com/docs/agent-customization/agent-plugins) (vendor documentation) - [About GitHub Copilot plugins](https://docs.github.com/en/copilot/concepts/agents/about-plugins) (vendor documentation) - [Cursor plugin marketplace](https://cursor.com/blog/marketplace) (vendor announcement) - [AWS Agent Plugins](https://github.com/awslabs/agent-plugins) (official repository) - [Agent Skills overview](https://agentskills.io/home) (open standard documentation) - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-11-25) (specification)