Plug-Ins für Copilot Cowork erstellen

  • Gilt für:: Microsoft Copilot

Microsoft Copilot Cowork unterstützt die Erweiterbarkeit durch M365-App-Pakete – derselbe Verteilungsmechanismus, der von Teams-Apps, Copilot-Agents und Office-Add-Ins verwendet wird. Sie können Cowork erweitern mit:

  • Fähigkeiten: Prompt-basierte Workflows, die Cowork neue Fachkenntnisse vermitteln, z. B. Finanzanalyse, Rechtsrecherche oder HR-Workflows.
  • Konnektoren: Remoteserver, die Cowork Zugriff auf externe Datenquellen und APIs gewähren.

Beide sind in einem Microsoft 365-Standard-App-Paket verpackt und werden über den Microsoft 365 App Store vertrieben.

Important

Microsoft Purview-Informationsbarrieren (IB) werden derzeit nicht für die Verwaltung und Freigabe von Plug-Ins oder Skills unterstützt. In Mandanten, in denen IB aktiviert ist, werden Uploads eingebetteter Wissensdateien auf Mandantenebene blockiert. Dadurch wird verhindert, dass betroffene Plugins und Skills hochgeladen oder veröffentlicht werden.

Microsoft erstellt oder pflegt weder einen persistenten Index, einen Wissensgraphen (einschließlich des Microsoft Graph) noch eine Datenbank, die ISV-Inhalte enthalten, sei es durch Crawlen, Scraping, Harvesting, Massenexport, Datenaufnahme oder jede andere Methode (über APIs, MCP-Server oder anderweitig). Microsoft kann ISV-Inhalte ggf. vorübergehend verarbeiten, um auf die Echtzeitabfrage eines Benutzers zu reagieren, aber ISV-Inhalte nicht über die Dauer dieser Sitzung hinaus aufbewahren. Auf schriftliche Aufforderung des ISV hin löscht Microsoft alle ISV-Inhalte, die sich in seinem Besitz oder unter seiner Kontrolle befinden, innerhalb von 10 Werktagen und bescheinigt diese Löschung schriftlich. Weitere Informationen finden Sie unter Unternehmensdatenschutz in Microsoft Copilot und Microsoft Copilot Chat.

Was Sie erstellen werden

Ein Cowork-Plugin ist ein .zip Paket, das Folgendes enthält:

my-extension.zip
├── manifest.json          # M365 Unified App Manifest (v1.28)
├── color.png              # 192×192 full-color app icon
├── outline.png            # 32×32 outline icon
└── skills/                # Agent Skills (SKILL.md files)
    ├── skill-one/
    │   ├── SKILL.md
    │   └── references/    # Optional deep-dive docs
    └── skill-two/
        └── SKILL.md

Skills verwenden den offenen Standard "Agent Skills" – dasselbe Format, das von Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie und mehr als 30 anderen KI-Tools unterstützt wird.

Auswählen des Startpunkts

Erstellen Sie Ihr Plug-In mit der wiqd-CLI. Die CLI legt die Paketstruktur an und hält manifest.json und Ihre Skill-Ordner synchron. Außerdem wendet sie die plattformeigenen Validierungsregeln an, bevor Sie das Paket hochladen, und stellt das Ergebnis anschließend bereit und gibt es frei. Die CLI befindet sich in der Vorschauversion, sodass sich die Befehle und die generierte Ausgabe vor der allgemeinen Verfügbarkeit ändern können. Alles, was es generiert, ist ein einfaches Microsoft 365-App-Paket, sodass Sie die Dateien weiterhin direkt öffnen, bearbeiten und versionieren können.

Stellen Sie das Paket nur manuell zusammen, wenn Sie keine Tools installieren können oder wenn Sie Ihre eigene Paketpipeline erstellen. In diesem Fall ist der Paketformatverweis in diesem Artikel genau das, was Sie brauchen. Er beschreibt genau, was wiqd erzeugt.

Startpunkt Mach das Zeit bis zum ersten Paket
Ich fange bei Null an Ein Plugin mit wiqd erstellen ca. 10 Minuten
Ich habe ein vorhandenes Claude Code-Plugin Plug-In konvertieren ca. 5 Minuten
Ich kann die Tools nicht installieren, oder ich schreibe meine eigenen Pakete Ein Paket von Hand zusammenstellen ca. 30 Minuten

Ein Plugin mit wiqd erstellen

Die wiqd-CLI durchläuft denselben Lebenszyklus, den Sie andernfalls manuell durchlaufen würden – erstellen, Fähigkeiten hinzufügen, validieren, bereitstellen, verpacken und teilen. Das erzeugte Paket erfüllt bereits die Validierungsregeln in diesem Artikel.

Schritt 1: wiqd installieren und anmelden

Installieren Sie die wiqd-CLI, indem Sie der wiqd-Installationsanleitung folgen, die Windows, macOS und Linux abdeckt. Melden Sie sich dann bei dem Microsoft 365-Mandanten an, für den Sie entwickeln, da sowohl die Bereitstellung als auch die Freigabe Ihren Mandanten berühren:

wiqd auth login --interactive

Das Installationsprogramm registriert auch ein GitHub Copilot CLI-Plugin, sodass Sie denselben Ablauf im Dialog steuern können. Sie könnten zum Beispiel sagen: Erstelle ein eigenständiges Plug-In namens Triage Helper oder Validiere mein Plug-In. Der Unterhaltungspfad führt die gleichen Befehle wie in diesem Abschnitt aus. Verwenden Sie die Befehle direkt, wenn Sie Skripts für eine Pipeline erstellen oder reproduzierbare, nicht interaktive Automatisierung wünschen.

Schritt 2: Gerüst für das Plug-In erstellen und Funktionen hinzufügen

Erstellen Sie den Plug-In-Container und fügen Sie dann die benötigten Funktionen in einer beliebigen Kombination hinzu:

wiqd plugin create --name my-plugin
wiqd plugin add skill --name "Contract Analysis"
wiqd plugin add connector --name "Contoso Legal" --description "Case law and statutes over MCP" --url https://api.contoso.com/legal/mcp

add skill erstellt das Gerüst appPackage/skills/contract-analysis/SKILL.md und registriert es in agentSkills[]. add connector schreibt den agentConnectors[] Eintrag. Beide Befehle erzwingen die Namensgebungs- und Größenbeschränkungen der Plattform vor dem Schreiben in die Manifestdatei, sodass eine Nichtübereinstimmung des Ordnernamens oder eine Überlänge von id niemals das Manifest erreicht.

Schreiben Sie Ihre Skilllogik in die generierte SKILL.md. Die Frontmatter-Felder, das Modell für progressives Laden und die Begleitdatei-Limits sind die gleichen, die unter Schritt 1: Erste Fertigkeit erstellen und Schritt 2: Referenzmaterialien hinzufügen (optional) beschrieben werden.

Important

wiqd plugin create heftet das Paket an manifestVersion: "1.29" an, während die manuell erstellten Beispiele in diesem Artikel 1.28 verwenden. Bei Connectors sind Unterschiede von Bedeutung. Bei 1.28 ist mcpToolDescription erforderlich, und die Datei, auf die es verweist, muss sich in der ZIP-Datei befinden. Bei 1.29 agentConnectors[] sind Einträge reine URLs und mcpToolDescription ist optional, sodass ein von wiqd generiertes Paket niemals auf diesen Uploadfehler stößt. wiqd unterstützt das Scaffolden der Connector-Authentifizierung noch nicht – konfigurieren Sie sie direkt wie unter Unterstützte Authentifizierungstypen beschrieben.

Schritt 3: Beim Erstellen validieren

Überprüfen Sie kontinuierlich, anstatt ein Paket zusammenzustellen und zu hoffen, dass der Upload erfolgreich ist:

wiqd plugin validate
wiqd plugin validate --mode deep

validate ist die statische Offlineüberprüfung der Oberfläche des deklarativen Agents. Ein Plug-In, das nur Fertigkeiten oder Connectors enthält, besteht die Prüfung, ohne dass etwas überprüft werden muss. Dies entspricht den Erwartungen – es ist eine Überprüfung für Ihre Buildschleife und nicht für vollständige Abdeckung vorgesehen. validate --mode deep paketiert zuerst das Plug-In und validiert dann die erstellte .zip anhand derselben App-Validierungsbibliothek, die der Upload verwendet. Hier kommen die ASKILL-Codes und Konnektorregeln zum Vorschein.

Schritt 4: Bereitstellen, verpacken und freigeben

Führen Sie diese drei Befehle in der angegebenen Reihenfolge aus:

wiqd plugin provision
wiqd plugin package
wiqd plugin share --scope users --email you@contoso.com

Führen Sie zuerst provision aus, da die Umgebungsdatei geschrieben wird, von der sowohl package als auch share abhängen. --scope users wird zur Freigabe für die Personen verwendet, die Sie auflisten, oder --scope tenant zum Freigeben für alle Personen in Ihrer Organisation. In beiden Fällen wird das Plug-In unter Für mich freigegeben under Cowork>Quellen und Fertigkeiten>Plug-Ins angezeigt. Um es stattdessen im Abschnitt "Entdecken " aufzulisten, lädt ein Administrator das Paket hoch. Weitere Informationen finden Sie in Schritt 8: Veröffentlichen in Ihrem Mandanten. Um das zu entfernen, was provision erstellt hat, führen Sie wiqd plugin delete --env local --yes aus.

Die Übermittlung an den öffentlichen Store ist im Partner Center immer noch ein manueller Prozess. Weitere Informationen finden Sie in Schritt 9: Veröffentlichen für die Öffentlichkeit.

Ein Plug-In auf einen anderen Host übertragen

Um Ihre Skills in Claude Code, Cursor oder einem anderen Agenten-Skills-Host zu nutzen, exportieren Sie das Projekt, anstatt Ordner manuell zu kopieren:

wiqd plugin export --format claude-plugin

export ist standardmäßig auf --format open-plugin gesetzt und akzeptiert auch cursor-plugin. Es schreibt ein unkomprimiertes Verzeichnis unter <path>/export/<format>.

Vorhandenes Plug-In importieren

Wenn Sie bereits ein Claude Code Plugin mit Skills und MCP-Servern haben, haben Sie zwei Konvertierungswege. Die Route, die Sie wählen, hängt davon ab, ob Sie das Plug-In weiterentwickeln oder nur das bereitstellen möchten, was Sie haben.

Ziel Verwenden
Das Plug-In weiterhin von Microsoft 365 aus entwickeln, überprüfen und bereitstellen wiqd plugin import
Sofort eine veröffentlichungsfähige .zip aus einem vorhandenen Claude-Plug-In erstellen Das Konvertierungsskript

Importieren mit wiqd

wiqd plugin importerkennt eine Open-Plugin-, Claude-Plugin- oder Cursor-Plugin-Quelle und erzeugt daraus ein wiqd-Plugin-Projekt. Das importierte Plug-In gehört zum selben Lebenszyklus wie eines, das Sie mit wiqd plugin create erstellt haben:

wiqd plugin import --path ./my-claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

--privacy-url und --terms-url sind nur beim ersten Import eines Plug-Ins erforderlich. Wenn die Quelle aus einem früheren wiqd plugin exportstammt, sind sie bereits in den Roundtrip-Metadaten enthalten.

Important

Ein importiertes Projekt unterstützt nur den schreibgeschützten Teil des Lebenszyklus – wiqd plugin validate, show und list. Es kann noch nicht verpackt, bereitgestellt oder freigegeben werden, da der Import die für diese Schritte erforderlichen lokalen Bereitstellungsdateien nicht generiert. Dies ist eine nachverfolgte Lücke. Informationen zum aktuellen Status finden Sie in der WIQD-CLI-Referenz. Wenn Sie heute ein veröffentlichungsfähiges Paket benötigen, verwenden Sie das Konvertierungsskript.

Konvertieren mit dem Konvertierungsskript

Das Konvertierungsskript übersetzt ein Claude-Plugin direkt in ein veröffentlichungsfähiges M365-Paket:

  1. Installieren Sie die CLI (erfordert Version 1.1.12 oder höher):

    npm install -g @microsoft/m365agentstoolkit-cli

  2. Überprüfen Sie die Version:

    atk --version

  3. Importiere dein Plugin:

    atk import openplugin --path ./my-claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

Der Befehl liest die Verzeichnisse .claude-plugin/plugin.json (oder .cursor-plugin/plugin.json), .mcp.json und skills/ des Plug-Ins und erstellt dann ein Gerüst für ein Agents-Toolkit-Projekt, das appPackage/manifest.json, Ihre Fertigkeiten und generierte Symbole enthält.

Sie müssen --privacy-url und --terms-url einschließen, da Plug-In-Manifeste keine entsprechenden Felder haben und das Microsoft 365-Manifest beides erfordert.

Hinweis

atk import openplugin sucht ein Plug-In-Manifest in einem Verzeichnis mit vorangestelltem Punkt – .claude-plugin/plugin.json.cursor-plugin/plugin.json oder .plugin/plugin.json – neben einer .mcp.json. Die Spezifikation Agent Plugins 1.0.0 platziert das Manifest auf einer obersten Ebene unter plugin.json und die MCP-Konfiguration unter mcp.json. Um ein Plug-In zu importieren, das dem Layout 1.0.0 folgt, verschieben Sie sein Manifest nach .plugin/plugin.json, und benennen mcp.json Sie es in .mcp.jsonum.

Verpacken Sie das Ergebnis in ein zum Hochladen geeignetes .zip:

cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
  --output-package-file ./appPackage/build/appPackage.zip \
  --output-folder ./appPackage/build

Hinweis

atk import openplugin generiert ein devPreview Manifest. Die Manifestbeispiele an anderer Stelle in diesem Artikel beziehen sich auf das Schema v1.28. Wenn Sie über einen Kanal veröffentlichen, der Version 1.28 erfordert, aktualisieren Sie manifestVersion und $schema in der generierten appPackage/manifest.json.

Was wird importiert?

Plugin-Artefakt M365-Äquivalent Hinweise
.claude-plugin/plugin.json manifest.json Namens-, Beschreibungs- und Entwicklerfelder zugeordnet; GUID automatisch generiert (deterministische UUID v5)
skills/*/SKILL.md agentSkills[] Einträge + skills/ Ordner Wörtlich kopiert – identisches Format
.mcp.json Server agentConnectors[] Einträge URL und Authentifizierungstyp automatisch erkannt
color.png / outline.png Symbole im Paket Wird verwendet, falls vorhanden; Platzhalter werden generiert, falls sie fehlen

Important

Für jeden aus .mcp.json importierten Connector ist der generierte authorization.referenceId ein Platzhalter, der vom Plug-In und dem Servernamen abgeleitet wird. Ersetzen Sie diese ID durch Ihre tatsächliche OAuth-Clientregistrierungs-ID, bevor Sie veröffentlichen. Weitere Informationen finden Sie unter Unterstützte Authentifizierungstypen.

Nicht konvertiert wird

Die folgenden Features des Claude-Plug-Ins werden im Microsoft 365-Manifest noch nicht unterstützt:

Claude Plugin-Funktion Status
commands/ (Schrägstrichbefehle) Noch nicht unterstützt
agents/ (Unteragenten) Noch nicht unterstützt
hooks/ (Ereignishandler) Noch nicht unterstützt
settings.json Nicht anwendbar
bin/ (ausführbare Dateien) Nicht anwendbar

Importoptionen

Option Description
--path, -p Required. Plug-In-Verzeichnis, das .claude-plugin/plugin.json, .cursor-plugin/plugin.json oder .plugin/plugin.json enthält
--output, -o Zielprojektordner (Standard: ./<plugin-name>)
--privacy-url developer.privacyUrl für das generierte Manifest
--terms-url developer.termsOfUseUrl für das generierte Manifest
--website-url developer.websiteUrl. Fällt zurück auf homepage, dann author.url
--app-id Überschreiben Sie die für das Manifest id generierte deterministische UUID v5
--default-auth-type Auto (Standard), None, OAuthPluginVaultoder ApiKeyPluginVault

Automatische Erkennung des Authentifizierungstyps:

Source Standard-Authentifizierungstyp Grund
Externe HTTPS-URLs OAuthPluginVault Die meisten Remote-APIs benötigen eine Authentifizierung
localhost und Nicht-HTTPS-URLs None Lokale Entwicklungsserver

Wenn die automatische Erkennung nicht zu Ihrem Setup passt, verwenden Sie --default-auth-type, um dies außer Kraft zu setzen.

Zurück in ein Plug-in-Verzeichnis exportieren

Um ein Agents Toolkit-Projekt zurück in ein Plug-In-Verzeichnis zu verschieben, z. B. um ein Claude Code-Plug-In und ein Cowork-Paket synchron zu halten, verwenden Sieatk export openplugin:

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin
Option Description
--path, -p Required. Der Agents Toolkit-Projektordner enthält appPackage/manifest.json
--output, -o Plugin-Zielverzeichnis (Standard: ./<plugin-name>-openplugin)
--manifest-kind open-plugin (Standard, schreibt .plugin/plugin.json), claude-plugin oder cursor-plugin

Export schreibt einen x-microsoft-365-agents-toolkit Block in die generierte plugin.json. Dieser Block enthält das Manifest id, Entwickler-URLs und Connectoreinstellungen, sodass ein späteres atk import openplugin Roundtrips durchführt, ohne dass --privacy-url oder --terms-url erforderlich sind.

Hinweis

Der x-microsoft-365-agents-toolkit Block ist spezifisch für das Agents Toolkit, und der Standardtyp open-plugin schreibt das Manifest in .plugin/plugin.json. Agent Plugins 1.0.0 verwendet eine oberste Ebene plugin.json und überträgt clientspezifische Daten unter einem extensions Schlüssel mit einem Reverse-Domain-Namespace, sodass andere Clients diesen Block ignorieren, anstatt darauf zu reagieren. Wenn Ihr Ziel Claude Code oder Cursor ist, verwenden Sie --manifest-kind claude-plugin or cursor-plugin.

Legacy: PowerShell-Konvertierungsskript

Bevor atk den Plug-In-Import unterstützte, wurde für die Konvertierung ein reines Windows-PowerShell-Skript verwendet, das als Konvertierungsskript verfügbar bleibt:

.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output

Verwenden Sie stattdessen atk import openplugin. Es ist plattformübergreifend, unterstützt sowohl Cursor- als auch Claude-Code-Quellen und kann zurück in ein Plugin-Verzeichnis exportiert werden.

Ein Paket von Hand zusammenstellen

Dieser Abschnitt ist die Referenz zum Paketformat: sie beschreibt genau, was Build a plugin with wiqd generiert, Feld für Feld. Folgen Sie ihm von Anfang bis Ende, wenn Sie keine Tools installieren können oder Ihre eigene Verpackungspipeline erstellen. Verwenden Sie es als Referenz, wenn Sie ein generiertes Paket verstehen oder debuggen müssen.

Schritt 1: Erste Fertigkeit erstellen

Ein Skill ist ein Ordner, der eine SKILL.md Datei enthält. Erstelle die folgende Ordnerstruktur:

my-extension/
└── skills/
    └── contract-analysis/
        └── SKILL.md

Schreiben Sie SKILL.md mit YAML-Frontmatter und einem Markdown-Text:

---
name: contract-analysis
description: |
  Analyzes contracts for key terms, risks, and obligations.
  Use when user asks to "review this contract", "find the liability clause",
  "summarize the key terms", or "compare these two agreements".
license: MIT
metadata:
  author: Contoso Legal Tech
  version: "1.0"
---

# Contract Analysis

## What This Skill Does

Guides Cowork through systematic contract review, identifying:
- Key commercial terms (pricing, payment, renewal)
- Risk clauses (indemnification, limitation of liability, IP)
- Obligations and deadlines
- Non-standard or unusual provisions

## Workflow

1. Read the uploaded contract document
2. Extract and categorize all clauses
3. Flag risk areas with severity ratings
4. Generate a structured summary with recommendations

## Output Format

Present findings in a structured table:

| Clause | Category | Risk Level | Summary |
|--------|----------|------------|---------|
| Section 4.2-Indemnification | Risk | High | Unlimited indemnification for IP claims |
| Section 7.1-Term | Commercial | Low | 12-month auto-renewal with 30-day notice |

SKILL.md Frontmatter-Felder

Erforderliche Felder:

Feld Constraints Description
name 1–64 Zeichen, Kebab-Case Skill-ID – muss exakt mit dem Ordnernamen übereinstimmen
description 1–1024 Zeichen Wann sollte dieser Skill verwendet werden? Triggerphrasen einschließen

Important

  • Der Ordnername muss mit dem name Feld in der Frontmatter übereinstimmen. Diese Diskrepanz ist die häufigste Ursache für das Versagen von Skills.
  • Die Felder der Plug-In-Auflistung description sollten keine Call-to-Actions enthalten, die Benutzer zum Kauf von Abonnements auf externe Marketplaces verweisen.
Ordnerpfad name-Feld Gültig? Warum?
skills/contract-analysis/SKILL.md contract-analysis Yes Ordner und Name stimmen überein
skills/contract-analysis/SKILL.md ContractAnalysis No Name verwendet PascalCase anstelle eines entsprechenden Ordners
skills/my-skill/SKILL.md contract-analysis No Ordner ist my-skill, aber Name ist contract-analysis

Benennungsregeln (Kebab-Case): Verwenden Sie nur alphanumerische Kleinbuchstaben und Bindestriche. Verwenden Sie keine aufeinanderfolgenden Bindestriche und keine führenden oder nachfolgenden Bindestriche.

Example Gültig? Issue
bond-relative-value Yes Kleinbuchstaben mit Bindestrichen
fx-carry-trade Yes Kleinbuchstaben mit Bindestrichen
email Yes Einzelnes Wort, ohne Bindestriche
Bond_Relative_Value No Unterstriche und Großbuchstaben
--my-skill-- No Bindestriche am Anfang und am Ende
my--skill No Aufeinanderfolgende Bindestriche

Schritt 2: Referenzmaterialien hinzufügen (optional)

Bei komplexen Fertigkeiten sollten Sie die primäre SKILL.md schlank halten und detaillierte Inhalte in Unterverzeichnisse verschieben. Diese zusätzlichen Dateien sind Begleitdateien. Die Fertigkeit lädt sie bei Bedarf.

skills/
└── contract-analysis/
    ├── SKILL.md               # Core workflow (~1,500-2,000 words ideal)
    ├── references/            # Deep-dive docs loaded on demand
    │   ├── clause-taxonomy.md
    │   └── risk-scoring.md
    └── scripts/               # Executable utilities
        └── extract-clauses.py

Beschränkungen für Begleitdateien

Jeder Skill kann bis zu 20 Begleitdateien (jede andere Datei als SKILL.md) enthalten. Folgende Grenzwerte gelten pro Fertigkeit:

Begrenzung Wert
Maximale Anzahl von Begleitdateien 20
Maximale Größe pro Begleitdatei 5 Megabyte
Maximale Gesamtgröße von Begleitdateien 10 MB
Downloadtimeout (alle Begleitdateien) 15 Sekunden

Regeln für Begleitdateien

Pfade von Begleitdateien müssen den folgenden Regeln entsprechen:

  • Verwenden Sie nur relative Pfade (keine absoluten Pfade).
  • Kein Pfaddurchlauf (.. Segmente).
  • Keine umgekehrten Schrägstriche oder Nullbytes in Dateinamen.
  • Keine versteckten Dateien (Namen beginnend mit .).
  • Keine reservierten Windows-Namen (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
  • Die Datei SKILL.md selbst zählt nicht als Begleitdatei.
  • Dateinamen müssen sichere Zeichen verwenden: alphanumerische Zeichen, Bindestriche, Unterstriche, Punkte, Leerzeichen und !.

Um das Kontextfenster effizient zu halten, lädt das System Skills in drei Ebenen:

Ebene Beim Laden Zielgröße
Frontmatter (name + description) Immer – beim Start ~100 Token
SKILL.md-Textkörper Wenn Fertigkeit ausgelöst wird Weniger als 5.000 Token (1.500-2.000 Wörter)
Verweise (references/) Auf Anfrage durch den Agent Unbegrenzt
Skripte (scripts/) Ausgeführt, nicht in den Kontext geladen N/A

Verweisen Sie in SKILL.md explizit auf die Unterverzeichnisse, damit der Agent weiß, dass sie existieren:

## Additional Resources

- **`references/clause-taxonomy.md`**-Full taxonomy of contract clause types
- **`references/risk-scoring.md`**-Risk scoring methodology and thresholds
- **`scripts/extract-clauses.py`**-Automated clause extraction utility

Schritt 3: Connector hinzufügen (optional)

Wenn Ihre Erweiterung Zugriff auf externe Daten benötigt, fügen Sie einen Remote-MCP-Server hinzu. Dieser Schritt ist optional. Reine Fertigkeitspakete eignen sich gut für promptbasierte Workflows.

Tip

Wenn Ihr Server die Sichtbarkeit von Tools nach Client filtert oder den eingehenden Datenverkehr nach Attributen sortiert, gehen Sie zu Cowork-Datenverkehr zu Ihrem Server identifizieren, um die Client-Identität zu sehen, die Cowork übermittelt.

Hinweis

Benutzerdefinierte Plug-Ins werden in Cowork auf Mobilgeräten nicht unterstützt.

Steckverbindungsanforderungen

Requirement Details
Transport HTTP-Streaming (HTTPS erforderlich, TLS 1.2+)
Protocol JSON-RPC 2.0-Nachrichtenformat
Werkzeugentdeckung Unterstützung von tools/list für dynamische Ermittlung (empfohlen)
Werkzeugausführung Unterstützung von tools/call für Aufrufe
Availability Empfohlene SLA mit 99,9 % Verfügbarkeit für im Store veröffentlichte Apps
Antwortzeit Weniger als 30 Sekunden pro Toolaufruf

Tooldesignrichtlinien

  • Ein Tool pro Aktion für kleine APIs (weniger als 15 Vorgänge): search_case_law, get_ruling, cite_precedent
  • Suchen und ausführen für große APIs (50+ Operationen): search_actions + execute_action
  • Beschreibende Namen: get_bond_price nicht getData
  • Umfangreiche Eingabeschemata: Fügen Sie für jeden Parameter eine Beschreibung hinzu – das liest der Agent
  • Strukturierte Ausgabe: Geben Sie JSON zurück, das der Agent für den Nutzer formatieren kann
  • Datei-Eingaben: Um eine Datei aus dem Arbeitsbereich des Benutzers anzunehmen, deklarieren Sie den Parameter mit contentEncoding: base64. Weitere Informationen finden Sie unter Dateien aus dem Cowork-Arbeitsbereich akzeptieren.

Tools Ihres Connectors beschreiben (mcpToolDescription)

Ein remoteMcpServer Verbinder kann optional ein mcpToolDescription Objekt enthalten. Wenn angegeben, verweist die verschachtelte file Eigenschaft auf eine JSON-Datei mit der Tool-Beschreibung, die Sie in Ihr .zip aufnehmen und von der Paketwurzel aus über einen relativen Pfad referenzieren. Cowork ermittelt die Tools dynamisch auf Ihrem MCP-Server und verwendet diese Datei auch dann nicht, wenn sie vorhanden ist.

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp",
  "mcpToolDescription": {
    "file": "./tools/contoso-legal-tools.json"
  },
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
  }
}

Wenn Sie mcpToolDescription einschließen, beschreibt die referenzierte Datei (z. B. tools/contoso-legal-tools.json) die Tools, die der Connector verfügbar macht, und muss im ZIP-Paket vorhanden sein. Fügen Sie es zusammen mit Ihrem manifest.json- und skills/-Ordner ein, wenn Sie das Plug-In packen.

Tip

Diese Anforderung gilt für die Manifestversion 1.28. Pakete, die wiqd plugin create erzeugt, zielen auf 1.29 ab, wobei agentConnectors[]-Einträge nur aus URLs bestehen, mcpToolDescription optional ist und es keine Toolbeschreibungsdatei zum Vergessen gibt.

Unterstützte Auth-Typen

Authentifizierungstyp Wann verwenden? Benutzerfreundlichkeit
None Öffentliche oder anonyme APIs, interne Dienste Transparent – keine Authentifizierungsaufforderung
OAuthPluginVault OAuth 2.0-APIs (empfohlen für die Produktion) Benutzer schließt OAuth-Zustimmung einmal ab
ApiKeyPluginVault Dienste auf API-Schlüsselbasis Benutzer gibt den Schlüssel einmal ein

Hinweis

  • Unterstützung für die API-Schlüsselauthentifizierung ist in Cowork noch nicht verfügbar.
  • Wenn Ihr MCP-Server einen API-Schlüssel erfordert, verwenden Sie stattdessen OAuthPluginVault oder Dynamic Client Registration, oder machen Sie einen Endpunkt verfügbar, der None akzeptiert.

Für OAuthPluginVault und ApiKeyPluginVault verweist referenceId auf Anmeldeinformationen, die im Microsoft Enterprise Token Store gespeichert sind – Geheimnisse werden nie in den Manifest- oder Skill-Dateien angezeigt. Der referenceId-Wert ist die OAuth-Clientregistrierungs-ID, die Sie erstellen, wenn Sie einen OAuth-Client bei Agents-Toolkit registrieren.

Important

Legen Sie beim Registrieren Ihres OAuth-Clients die Nutzung nach Organisation auf Beliebige Microsoft 365-Organisation fest, um sicherzustellen, dass Ihr Plug-In mandantenübergreifend funktioniert.

MCP-Authentifizierung

Informationen zur Verwendung von OAuth oder ApiKey für die Authentifizierung finden Sie unter Authentifizierung für MCP- und API-Plug-Ins in Agents in Microsoft 365 Copilot konfigurieren (Setup- und Konfigurationsdetails).

Dynamische Clientregistrierung

Wenn Ihr MCP-Server die dynamische Client-Registrierung (DCR) unterstützt, können Sie in Ihrer Connectordefinition auf eine authentication-Konfiguration verzichten, und Cowork erstellt automatisch einen OAuth-Client für Ihr Plug-In.

Hinweis

Das Weglassen der authentication Konfiguration wird nur in Cowork unterstützt. Es wird in Copilot Chat nicht unterstützt. Wenn Ihr Plug-In auch in Copilot Chat funktionieren muss, konfigurieren Sie die OAuthPluginVault Authentifizierung wie unter Unterstützte Authentifizierungstypen beschrieben.

Sie können das authorization Objekt vollständig weglassen. Konfigurieren Sie Ihre MCP-Server-URL, und Cowork kümmert sich um den OAuth-Client:

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp"
}

Schritt 4: Erstellen des Manifests

Erstelle manifest.json in deinem Paketstamm. Im Beispiel wird die Manifestversion 1.28 verwendet. wiqd plugin create heftet stattdessen 1.29 an, wobei Connector-Einträge nur URLs sind.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
  "manifestVersion": "1.28",
  "version": "1.0.0",
  "id": "YOUR-GUID-HERE",
  "developer": {
    "name": "Contoso Legal Tech",
    "websiteUrl": "https://contoso.com",
    "privacyUrl": "https://contoso.com/privacy",
    "termsOfUseUrl": "https://contoso.com/terms"
  },
  "name": {
    "short": "Contoso Legal Tools",
    "full": "Contoso Legal Tools for Copilot Cowork"
  },
  "description": {
    "short": "Contract analysis, clause extraction, and legal research",
    "full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#2B579A",
  "agentSkills": [
    { "folder": "./skills/contract-analysis" }
  ]
}

Um einen Connector hinzuzufügen, schließen Sie agentConnectors ein:

{
  "agentConnectors": [
    {
      "id": "contoso-legal-api",
      "displayName": "Contoso Legal Database",
      "description": "Access to case law, statutes, and regulatory databases",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://api.contoso.com/legal/mcp",
          "mcpToolDescription": {
            "file": "./tools/contoso-legal-tools.json"
          },
          "authorization": {
            "type": "OAuthPluginVault",
            "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
          }
        }
      }
    }
  ]
}

In der Connectorkonfiguration referenceId sollte dies die OAuth-Registrierungs-ID sein. Wenn Sie mcpToolDescription einschließen, muss dessen file auf eine JSON-Datei mit der Toolbeschreibung verweisen, die im ZIP-Paket enthalten ist.

Important

Das Schema der Manifestversion v1.28 ist streng: Es legt additionalProperties: false im Stammverzeichnis fest, sodass jedes Feld, das nicht im Schema definiert ist, abgelehnt wird. Felder, die in Teams-App-Standardmanifesten gültig sind, wie z. B. packageName, führen dazu, dass der Upload mit einem Fehler wie Property 'packageName' has not been defined and the schema does not allow additional properties. fehlschlägt. Schließen Sie nur die hier gezeigten Felder ein.

Schritt 5: Symbole hinzufügen

Erstelle zwei PNG-Symbole:

Icon Größe Purpose
color.png 192×192 px Vollfarbiges App-Symbol wird im Store und in der App-Liste angezeigt
outline.png 32×32 px Einfarbiges Kontursymbol für kompakte Ansichten

Wenn Sie noch keine Symbole haben, generiert atk import openplugin einfarbige Platzhalter. Ersetzen Sie sie vor der Store-Einreichung.

Schritt 6: Verpacken

Erstellen Sie eine ZIP-Datei mit dem gesamten Inhalt im Stammverzeichnis. (wiqd plugin package erzeugt die gleiche Struktur nach wiqd plugin provision.)

contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│   └── contoso-legal-tools.json   # Referenced by mcpToolDescription (optional, connectors only)
└── skills/
    └── contract-analysis/
        ├── SKILL.md
        └── references/
            └── clause-taxonomy.md

Wenn ein Connector mcpToolDescription enthält, schließen Sie die JSON-Datei mit der Toolbeschreibung ein, auf die er verweist. Pakete, die mcpToolDescription nicht verwenden, einschließlich Pakete, die nur Skills enthalten, benötigen keinen tools/-Ordner.

Windows (PowerShell):

Compress-Archive -Path manifest.json, color.png, outline.png, tools, skills -DestinationPath contoso-legal-tools.zip

macOS/Linux:

zip -r contoso-legal-tools.zip manifest.json color.png outline.png tools/ skills/

Verwenden des Microsoft 365 Agents Toolkit

 atk package --manifest-file ./appPackage/manifest.json \
       --output-package-file ./appPackage/build/appPackage.zip \
       --output-folder ./appPackage/build

Schritt 7: Testen

Um Ihre App zu testen, laden Sie Ihr App-Paket in Teams hoch, wie unter Hochladen Ihrer App in Teams beschrieben.

Wenn Sie das Plug-In mit wiqd erstellt haben, führen Sie es stattdessen wiqd plugin provision aus. Es registriert das Plug-In für Sie bei Ihrem Mandanten. Für persönliche Tests eines manuell zusammengestellten Pakets laden Sie die App quer, indem Sie die CLI des Microsoft 365 Agents Toolkit verwenden:

  1. Installieren Sie @microsoft/m365agentstoolkit-cli von npm:

    npm install -g @microsoft/m365agentstoolkit-cli

  2. Überprüfen Sie die Installation durch Ausführen:

    atk --version

  3. Authentifizieren Sie sich mit Ihrem Microsoft 365-Geschäftskonto:

    atk auth login

  4. Melden Sie sich bei Ihrem Arbeitskonto an und installieren Sie das Agentpaket. Ersetzen Sie den Dateipfad durch den Speicherort Ihres ZIP-Pakets:

    atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal

    Eine erfolgreiche Installation gibt eine Ausgabe zurück, die ein TitleId und AppId für Ihr Konto enthält.

  5. Speichern Sie diese IDs zur späteren Verwendung beim Aktualisieren oder Deinstallieren.

Weitere Informationen finden Sie in Microsoft 365 Agents Toolkit-Befehlszeilenschnittstelle.

Schritt 8: In Ihrem Mandanten veröffentlichen

Laden Sie das Paket im Admin Center hoch, um Ihr Plug-In im Abschnitt Entdecken aufzulisten, wo alle in Ihrer Organisation es finden können:

  1. M365 Admin Center öffnen>Verwalten von Apps>Benutzerdefinierte App hochladen.
  2. Wählen Sie die Schaltfläche mit den Auslassungspunkten (...) >und dann Agent hinzufügen.
  3. Laden Sie Ihr .zip-Paket hoch.
  4. Öffnen Sie Cowork>Quellen und Fertigkeiten>Plug-Ins. Ihr Plug-In wird im Abschnitt Discover angezeigt.

wiqd plugin share platziert das Plug-In in Für mich freigegeben statt Ermitteln. Verwenden Sie es zum Testen und für einen gezielten Rollout an bestimmte Personen. Der Upload im Admin Center listet ein Plug-In zur Ermittlung auf.

Schritt 9: Für die Öffentlichkeit veröffentlichen

Für Plug-Ins, die für die öffentliche Bereitstellung vorgesehen sind, reichen Sie Ihr Plug-In über das Partner Center des Microsoft 365 App Store ein. Weitere Informationen finden Sie unter Veröffentlichen von Agents für Microsoft 365 Copilot.

Connector mit einem lokalen MCP-Server testen

Connectors erfordern eine HTTPS-mcpServerUrl. Um einen Server zu testen, der auf Ihrem Computer ausgeführt wird, müssen Sie ihn über eine öffentliche HTTPS-URL verfügbar machen. Dev-Tunnel stellen ein Relay bereit, das die TLS-Verbindung für Sie beendet.

devtunnel port create <tunnel> -p <port> --protocol http

Important

Verwenden Sie --protocol http, nicht https. Das --protocol-Flag beschreibt den lokalen Dienst, zu dem der Tunnel weiterleitet, nicht die öffentliche Tunnel-URL. Die meisten lokalen MCP-Server sprechen einfaches HTTP. Wenn Sie also --protocol https festlegen, während Ihr Server HTTP bereitstellt, gibt jede Anfrage über den Tunnel einen 502-Fehler zurück. Das Relay beendet TLS und stellt die öffentliche URL unabhängig von diesem Flag über HTTPS bereit.

Troubleshooting

Symptom Ursache Beheben
Jede getunnelte Anfrage gibt 502 zurück und der lokale Server spricht HTTP devtunnel port create wurde mit --protocol https ausgeführt Erstellen Sie den Port neu mit --protocol http
Weitergeleitete Anfragen geben unter macOS 502 zurück, obwohl der lokale Server ausgeführt wird Der Server ist an 0.0.0.0 gebunden (nur IPv4), aber der Tunnel wählt sich bei localhost ein, der zuerst zu ::1 (IPv6) aufgelöst wird Binden Sie den Server an ::, sodass er sowohl IPv4- als auch IPv6-Verbindungen akzeptiert
Upload schlägt mit Property '<field>' has not been defined and the schema does not allow additional properties fehl Das Manifest enthält ein Feld, das das v1.28-Schema nicht zulässt (z. B. packageName) Entfernen Sie das Feld; Das v1.28-Schema verwendet additionalProperties: false

Verpackungsmuster

Wählen Sie das Muster aus, das zu Ihrer Erweiterung passt:

Nur Fertigkeiten (kein Connector)

Am besten geeignet für promptbasierte Workflows, Dokumentenanalyse und Schreibunterstützung.

my-skills-pack.zip
├── manifest.json          # agentSkills only, no agentConnectors
├── color.png
├── outline.png
└── skills/
    ├── skill-one/SKILL.md
    └── skill-two/SKILL.md

Skills + Remote-Connector

Am besten geeignet für Datenanalysen, API-Integrationen und Unternehmenssysteme.

my-data-skills.zip
├── manifest.json          # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

Nur Connector (keine benutzerdefinierten Skills)

Verwenden Sie diese Option für Datenquellen, die von den integrierten Fähigkeiten von Cowork bereits verwendet werden können.

my-connector.zip
├── manifest.json          # agentConnectors only, no agentSkills
├── color.png
├── outline.png
└── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
    └── my-connector.json

Importierter Claude-Code oder Cursor-Plug-In

Verwenden Sie diese Option für vorhandene Claude-Ökosystem-Plug-Ins, die auf Cowork ausgerichtet sind. Um das Plug-In in Microsoft 365 weiterzuentwickeln, importieren Sie es:

wiqd plugin import --path ./claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

Um eine veröffentlichungsfähige .zip aus dem Plug-In in ihrer heutigen Form zu erstellen, verwenden Sie das Konvertierungsskript:

atk import openplugin --path ./claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

Bewährte Methoden für die Fertigkeitserstellung

Befolgen Sie diese Richtlinien, um Fertigkeiten zu erstellen, die zuverlässig aktiviert werden und konsistente Ergebnisse liefern.

Effektive Beschreibungen verfassen

Das description Feld bestimmt, wann der Agent Ihren Skill aktiviert. Spezifisch:

# Good-specific trigger phrases, concrete scenarios
description: |
  Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
  Use when user asks to "analyze bond spreads", "compare bonds",
  "rich-cheap analysis", "relative value", or "Z-spread calculation".

# Bad-vague, no trigger phrases
description: Provides bond analytics capabilities.

Effektive Workflows schreiben

  • Seien Sie in der Beschreibung präzise. Schließen Sie Triggerphrasen ein: „Bitte verwenden, wenn der Benutzer darum bittet ...“ Anhand dieser Beschreibung entscheidet der Agent, welche Fertigkeit aktiviert werden soll.
  • Als Workflow strukturieren. Versehen Sie die Schritte mit Nummern. Jeder Schritt sollte einer konkreten Aktion zugeordnet werden (Datei lesen, Tool aufrufen, Ausgabe generieren).
  • Ausgabeformat definieren. Zeigen Sie genau die Tabellen-, Listen- oder Dokumentstruktur an, die Benutzer erwarten sollten. Diese Definition verbessert die Konsistenz erheblich.
  • Referenzieren Sie Tools nach Name. Wenn Ihre Fähigkeiten von Connectortools abhängen, benennen Sie diese explizit: "Verwenden Sie das search_case_law Tool, um..."
  • Halten Sie die primäre SKILL.md schlank. Detailliertes Referenzmaterial in das references/ Unterverzeichnis verschieben. Der Skill-Body sollte der Workflow sein, keine Enzyklopädie.

Vermeiden häufiger Fehler

  • Betten Sie keine Geheimnisse in SKILL.md Dateien ein. Verwenden Sie agentConnectors mit Authentifizierung für API-Anmeldeinformationen.
  • Duplizieren Sie integrierte Fertigkeiten nicht. Überprüfen Sie vor dem Erstellen die Liste der integrierten Skills.
  • Machen Sie die Fertigkeiten nicht zu umfassend. „Alles rund um Rechtsdokumente“ ist schlechter als spezifische Fertigkeiten für „Vertragsanalyse“, „Klauselextraktion“ und „Rechtsrecherche“.
  • Codieren Sie keine Dateipfade oder Systembefehle hart. Fähigkeiten sollten über alle Umgebungen hinweg übertragbar sein.
  • Legen Sie nicht alles in SKILL.md. Wenn Ihr Textkörper mehr als ~3.000 Wörter enthält, verschieben Sie detaillierte Inhalte in references/.

Validierungsregeln

Wenn Sie Ihr Paket übermitteln, validiert die Plattform es auf mehreren Ebenen. Beheben Sie diese Fehler vor der Übermittlung, um Ablehnungen zu vermeiden.

Um sie beim Erstellen statt zum Zeitpunkt des Uploads abzufangen, führen Sie wiqd plugin validate --mode deepaus. Dieser Befehl verpackt das Plug-In und führt dieselben Regeln lokal aus. Weitere Informationen finden Sie in Schritt 3: Validieren während des Erstellens.

Überprüfung auf Manifestebene

Code Regel Severity
ASKILL-M001 folder ist für jeden agentSkills Eintrag erforderlich Error
ASKILL-M002 agentSkills Array kann bis zu 20 Elemente enthalten Error
ASKILL-M003 folder Pfad kann bis zu 256 Zeichen umfassen Error

Überprüfung auf Paketebene

Code Regel Allgemeine Fehlerbehebung Severity
ASKILL-P001 Der Ordner, auf den im Manifest verwiesen wird, ist in ZIP vorhanden Überprüfen Sie Ihre ZIP-Struktur Error
ASKILL-P002 Ordner enthält eine SKILL.md Datei Fehlendes SKILL.md hinzufügen Error
ASKILL-P003 SKILL.md hat ein gültiges YAML-Frontmatter zwischen ----Trennzeichen YAML-Syntax korrigieren Error
ASKILL-P004 Frontmatter enthält name Feld name: zu Frontmatter hinzufügen Error
ASKILL-P005 Frontmatter enthält description Feld description: zu Frontmatter hinzufügen Error
ASKILL-P006 name Stimmt mit dem Ordnernamen überein (letztes Pfadsegment) Ordner umbenennen oder name: beheben Error
ASKILL-P007 name ist Kebab-Case Verwenden Sie my-skill, nicht MySkill oder my_skill Error
ASKILL-P008 Keine doppelten folder Werte im Array Entfernen von Duplikaten Error

Connector-Validierung

Regel Severity
Jeder Connector erfordert ein id und ein displayName Error
Alle Connectorwerte id müssen innerhalb des Manifests eindeutig sein Error
Genau eines von plugin oder remoteMcpServer Error
mcpServerUrl muss eine gültige HTTPS-URL sein. Error
Wenn mcpToolDescription vorhanden ist, muss ihre file in der ZIP-Datei enthalten sein Error
authorization.referenceId Erforderlich, es sei denn, Typ ist None Error
authorization.referenceId darf nicht vorhanden sein, wenn der Typ None ist Error

Validierung von Begleitdateien

Das Portal überprüft Begleitdateien (Referenzmaterialien, Skripte und andere Dateien neben SKILL.md) zum Zeitpunkt des Hochladens und Synchronisierens:

Regel Severity
Höchstens 20 Begleitdateien pro Skill (ohne SKILL.md) Error
Jede Begleitdatei darf höchstens 5 MB groß sein Error
Die Gesamtgröße aller Begleitdateien darf pro Skill maximal 10 MB betragen Error
Dateipfade müssen relativ sein (keine absoluten Pfade) Error
Keine Pfadtraversierungssegmente (..) Error
Keine umgekehrten Schrägstriche oder Nullbytes in Dateinamen Error
Keine versteckten Dateien (Namen beginnend mit .) Error
Keine reservierten Windows-Namen (CON, PRN, AUX, NUL, COM1–COM9, LPT9–LPT1) Error
Dateinamen dürfen nur sichere Zeichen verwenden (alphanumerische Zeichen, Bindestriche, Unterstriche, Punkte, Leerzeichen, !) Error

Plattformübergreifende Kompatibilität

Skills verwenden den offenen Standard Agent Skills. Dieselben SKILL.md Dateien funktionieren in mehreren KI-Tools:

Platform Compatibility
Claude Code Vollständig gleiches SKILL.md-Format
Claude.ai Projekte Full-Skills können als Projektdateien hochgeladen werden
VS Code / GitHub Copilot Im Agent-Modus unterstützte Full-Agent-Fähigkeiten
Gemini CLI Vollständige Agent-Fertigkeiten unterstützt
JetBrains Junie Vollständige Agent-Fertigkeiten unterstützt
OpenAI-Codex Vollständige Agent-Fertigkeiten unterstützt
Cursorfunctionen Vollständige Agent-Fertigkeiten unterstützt

Wenn Sie Fähigkeiten sowohl für Claude Code als auch für Copilot Cowork entwickeln, erstellen Sie das Plug-In mit wiqd. Führen Sie dann wiqd plugin export --format claude-plugin aus, um das Claude-Code-Layout zu erstellen. Wenn Sie lieber mit der Struktur des Claude Code-Plugins beginnen möchten – es ist die Obermenge – ist das Layout wie folgt:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Claude plugin manifest
├── skills/
│   ├── skill-one/
│   │   ├── SKILL.md       # Works in both Claude Code AND M365
│   │   └── references/
│   └── skill-two/
│       └── SKILL.md
└── .mcp.json              # MCP server config (optional)

Bringen Sie es dann in Microsoft 365, wenn Sie bereit sind, es im Microsoft 365-App Store zu veröffentlichen, entweder mit wiqd plugin import oder mit dem Konvertierungsskript:

atk import openplugin --path ./my-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

MCP-Annotations- und Bestätigungsverwaltung

Copilot Cowork liest das MCP-Standardobjekt annotations für Tools, die Ihr Server von tools/list zurückgibt, und entscheidet damit, ob ein Toolaufruf vom Benutzer bestätigt werden muss und welche Bezeichnung im Prompt angezeigt werden soll.

Verfügbare Felder

Feld Type Effect
readOnlyHint bool false: Bestätigung erforderlich, bevor das Tool ausgeführt wird.
destructiveHint bool true: Bestätigung erforderlich, bevor das Tool ausgeführt wird.
title string Für Menschen lesbare Beschriftung im Bestätigungsdialogfeld. Verwendet den Namen des Tools, wenn er nicht vorhanden ist.

Bestätigungsregeln

Bestätigung ist erforderlich, wenn readOnlyHint == false oder destructiveHint == true.

Für alle Tools müssen Sicherheitsanmerkungen angegeben sein. Tools ohne Anmerkungen werden als destruktiv behandelt und müssen bestätigt werden. Weitere Informationen finden Sie in der MCP-Schemareferenz.

MCP-Beispiele

Eine destruktive Aktion mit einer freundlichen Bezeichnung:

{
  "name": "send_email",
  "description": "Send an email message.",
  "annotations": {
    "title": "Send Email",
    "destructiveHint": true
  },
  "inputSchema": { ... }
}

Ein sicherer Lesezugriff mit automatischer Ausführung:

{
  "name": "search_docs",
  "annotations": {
    "title": "Search Documents",
    "readOnlyHint": true
  }
}

Was jetzt verfügbar ist

  • Microsoft-Tools (Graph, Dataverse und andere) unterliegen unabhängig von Anmerkungen den integrierten Zugriffsrichtlinien von Cowork.
  • Für MCP-Server, die nicht von Microsoft stammen, wird die annotationsgesteuerte Bestätigung schrittweise eingeführt. Das Festlegen der Hinweise ist jetzt zukunftssicher. Es werden Bestätigungsaufforderungen angezeigt, wenn das Rollout erweitert wird, ohne dass Entwickler Änderungen vornehmen müssen.

Dateien aus dem Cowork-Arbeitsbereich akzeptieren

Ein Konnektor-Tool kann eine Datei aus der Cowork-Sitzung des Benutzers als Eingabe verwenden – ein vom Benutzer angefügtes Dokument, eine E-Mail-Anlage, die Cowork gespeichert hat, oder eine Datei, die ein früherer Schritt erstellt hat. Deklarieren Sie den Parameter mit dem standardmäßigen JSON-Schema-Schlüsselwort contentEncoding: base64 und den Rest übernimmt Cowork. Es ist keine Microsoft-spezifische Schemaerweiterung erforderlich, und die API-Oberfläche Ihres Servers ändert sich nicht.

Cowork löst die Arbeitsbereichsdatei auf und codiert sie mit base64, bevor Cowork Ihren Server aufruft, sodass Dateibytes nie in den Kontext des Agents gelangen. Der Agent sieht und gibt immer nur Arbeitsbereichsdateipfade aus.

Hinweis

Weisen Sie den Agenten nicht an, eine Datei selbst base64 zu codieren und das Blob in einen Toolaufruf einzufügen. Bei dieser Vorgehensweise wird die gesamte Datei in den Kontext des Modells geladen und es hängt davon ab, ob das Modell den BLOB exakt wiedergibt. Es scheint bei kleinen Testdateien zu funktionieren und schlägt bei echten Dateien fehl.

Dateiparameter deklarieren

Eine string-Eigenschaft mit contentEncoding: base64 wird als Dateieingabe erkannt:

{
  "name": "analyze_contract",
  "description": "Extract key terms from a contract document.",
  "annotations": {
    "title": "Analyze Contract",
    "readOnlyHint": true
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "document": {
        "type": "string",
        "contentEncoding": "base64",
        "description": "The contract file to analyze."
      },
      "jurisdiction": {
        "type": "string",
        "description": "Two-letter country code governing the contract."
      }
    },
    "required": ["document"]
  }
}

Ein Array solcher Zeichenfolgen wird auch von Tools erkannt, die mehrere Dateien akzeptieren:

"attachments": {
  "type": "array",
  "items": { "type": "string", "contentEncoding": "base64" },
  "description": "Receipt images to attach to the expense line."
}

Was der Agent sieht

Für Dateiparameter, die auf der obersten Ebene von inputSchema.properties deklariert sind, werden von Cowork im modellseitigen Schema durch ein einzelnes direct_attachment_file_paths-Array ersetzt – denselben Parameter, den die integrierten Tools von Cowork verwenden, sodass der Agent bereits weiß, wie er gefüllt wird. Das obige Schema wird dem Agent wie folgt dargestellt:

{
  "type": "object",
  "properties": {
    "direct_attachment_file_paths": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Workspace file paths to attach."
    },
    "jurisdiction": { "type": "string" }
  }
}

Wenn Ihr Tool mehrere Dateiparameter der obersten Ebene deklariert, werden alle zu diesem einen direct_attachment_file_paths-Array zusammengefasst. Beim Aufruf ordnet Cowork die aufgelösten Dateien wieder ihren ursprünglichen Parameternamen entsprechend der Deklarationsreihenfolge zu.

Verschachtelte Dateiparameter

Der Agent unterstützt einen Dateiparameter, der in einem Objekt oder einem Array von Objekten geschachtelt ist. Der Agent behandelt diesen Parameter anders: Anstatt ihn zu reduzieren, schreibt der Agent ihn an Ort und Stelle in eine Pfadzeichenfolge an derselben Stelle um. Bei diesem Ansatz wird die Zuordnung zwischen einer Datei und ihren zugehörigen Feldern beibehalten. Beispielsweise erhalten Sie eine Quittung pro Ausgabenzeile:

"line_items": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "amount": { "type": "number" },
      "receipt": { "type": "string", "contentEncoding": "base64" }
    }
  }
}

Der Agent füllt line_items[].receipt mit einem Arbeitsbereichspfad auf, und Cowork tauscht jeden Pfad für Base64-Inhalte aus, bevor der Aufruf weitergeleitet wird.

Die Verschachtelung wird bis zu einer Tiefe von vier Ebenen unterhalb von inputSchema durchlaufen. $ref-Verweise werden nicht verfolgt – definieren Sie Dateiparameter inline, anstatt hinter einem $ref.

Was Ihr Server empfängt

Ihr Server empfängt einen gewöhnlichen tools/call, in dem Ihre ursprünglichen Parameternamen mit Base64-codiertem Inhalt gefüllt sind:

{
  "method": "tools/call",
  "params": {
    "name": "analyze_contract",
    "arguments": {
      "document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
      "jurisdiction": "US"
    }
  }
}

Ihr Server muss nicht wissen, dass der Agent eine pfadbasierte Schnittstelle verwendet hat, und Tools, die keine Parameter vom Typ contentEncoding: base64 deklarieren, sind davon nicht betroffen.

Limits

Begrenzung Wert
Dateien pro Toolaufruf 8
Größe pro Datei 150 MiB
Gesamtgröße pro Toolaufruf 150 MiB
Parameter für Arraydateien pro Tool 1 (mit einer beliebigen Anzahl von Skalardateiparametern kombinieren)
Maximale Schachtelungstiefe 4 Ebenen unterhalb des oberen Bereichs von inputSchema

Ein Aufruf, der die Dateianzahl oder eine Größenobergrenze überschreitet, schlägt mit einem Toolfehler fehl und erreicht nie Ihren Server. Dimensionierung der API und ihrer Timeouts unter Berücksichtigung der Obergrenze von 150 MiB: base64 bläht die Nutzlast um etwa ein Drittel gegenüber der Größe der Rohdatei auf, und der codierte Inhalt wird im JSON-RPC-Anforderungstext gesendet.

Recommendations

  • Beschreiben Sie den Parameter für einen menschlichen Leser. Der Agent entscheidet anhand der Beschreibung, welche Datei zu welchem Parameter gehört. Beispielsweise funktioniert "The signed contract PDF to analyze" besser als "file".
  • Geben Sie die Formate, die Sie akzeptieren , in der Parameterbeschreibung an. Cowork leitet alles weiter, was der Benutzer anhängt. Validiere den Inhaltstyp auf deiner Seite und gib einen klaren Toolfehler zurück, wenn er nicht verwendbar ist.
  • Legen Sie Anmerkungen fest. Ein Tool, das eine Datei empfängt und entsprechend handelt, ist normalerweise nicht schreibgeschützt und fordert daher zur Bestätigung auf. Erfahren Sie mehr unter MCP-Annotation und Bestätigungsmanagement.
  • Halten Sie Dateiparameter inline. Ein Parameter, der sich hinter einer $ref oder mehr als vier Ebenen tief verschachtelt befindet, wird nicht umgeschrieben. Ihr Server erhält eine Pfadzeichenfolge an der Stelle, an der er Inhalte erwartet.
  • Deklarieren Sie höchstens einen Arraydateiparameter pro Tool. Bei zwei oder mehr kann Cowork nicht erkennen, welche Datei in welches Array gehört, und der Aufruf schlägt mit einem Toolfehler fehl. Verwenden Sie ein Array oder mehrere Skalarparameter oder eine Mischung aus Skalaren und einem einzelnen Array.
  • Bei Tools, die ausschließlich Skalare verarbeiten, ist mit einer exakten Anzahl zu rechnen. Wenn Ihr Tool nur skalare Dateiparameter deklariert, muss die Anzahl der Dateien, die der Agent übergibt, mit der deklarierten Anzahl übereinstimmen. Markieren Sie optionale Dateiparameter deutlich in ihren Beschreibungen, damit der Agent nicht zu wenig oder zu viel liefert.

Hinweis

Dieser Mechanismus ist älter als die eigene Dateieingabe des Model Context Protocol, die von der MCP File Uploads Working Group standardisiert wird. Cowork kann Unterstützung für die standardisierte Form deklarativer Dateieingaben hinzufügen, sobald verfügbar. Der contentEncoding: base64 hier beschriebene Vertrag gilt weiterhin.

Cowork-Datenverkehr zu Ihrem Server identifizieren

Wenn Ihr MCP-Server die Toolsichtbarkeit nach Client steuert oder Sie den eingehenden Datenverkehr zuordnen möchten, können Sie Anfragen erkennen, die von Cowork stammen. Cowork präsentiert eine stabile Softwareidentität auf zwei Kanälen:

Channel Wo sie angezeigt wird Wert
User-Agent Anforderungsheader Jede ausgehende Anfrage, die Cowork an Ihren Server sendet copilot-cowork/1.0
clientInfoim MCP-Handshake initialize Nur die initialize-Anforderung { "name": "copilot-cowork", "version": "<version>" }

Übereinstimmung mit dem copilot-cowork Präfix

Stimmen Sie mit dem copilot-coworkPräfix ab, wobei die Groß-/Kleinschreibung für beide Kanäle nicht beachtet wird. Nicht mit der exakten copilot-cowork/1.0 Zeichenfolge oder einem bestimmten clientInfo.version. Die Version verfolgt den Client-Identitätsvertrag und wird sich voraussichtlich ändern. Eine Präfixübereinstimmung sorgt dafür, dass Ihr Gate über Versionsschwankungen hinweg funktioniert.

# Correct: case-insensitive prefix match
copilot-cowork

# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0

Den richtigen Kanal für Ihre Vorgabe auswählen

Die beiden Kanäle haben unterschiedliche Bereiche. Wählen Sie also denjenigen aus, der der Art und Weise entspricht, wie Ihr Server seine Vorgaben erzwingt:

  • Der User-Agent-Header ist in jeder Anfrage vorhanden, einschließlich tools/list und tools/call. Wenn Sie Vorgaben oder Attribute pro Anforderung verwenden, geben Sie diesen Header ein.
  • clientInfo wird nur beim initialize Handshake gesendet. Wenn Sie beim Verbindungsaufbau pro Sitzung prüfen, können Sie es dort auslesen, aber bei späteren Anfragen wird es nicht wiederholt.

Was die Identität beinhaltet und was nicht

Die Identität benennt nur die Software. Es ist für jeden Cowork-Benutzer und jede Verbindung gleich und trägt niemals eine Benutzeridentität. Die Benutzeridentität bleibt im Autorisierungsfluss, den die Authentifizierungskonfiguration Ihres Connectors definiert.

Die Identität umfasst Die Identität enthält Folgendes nicht
Ein stabiler Softwarename (copilot-cowork) und eine Vertragsversion Beliebige Mandanten-, Benutzer-, Sitzungs- oder Unterhaltungsbezeichner
Derselbe Wert für jede Anfrage und jede Verbindung Ein Bezeichner pro Connector

Da es keinen Bezeichner pro Connector gibt, können Sie diese Identität derzeit nicht verwenden, um zu bestimmen, welcher Connector einen Aufruf getätigt hat, oder um ein veröffentlichtes Microsoft-Plug-In von einem quergeladenen Server zu trennen, der auf dieselbe URL verweist. Wenn Sie diese Unterscheidung benötigen, erzwingen Sie sie durch die Autorisierungskonfiguration Ihres Connectors und nicht über die Clientidentität.

Häufig gestellte Fragen

Kann ich Skills aus dem M365-Paket in Claude Code verwenden?

Ja. Die Skill-Ordner enthalten standardmäßige Agent-Skills. Führen Sie wiqd plugin export --format claude-plugin aus, um das Claude Code-Layout zu erstellen, oder kopieren Sie die Fertigkeitsordner in .claude/skills/ eines beliebigen Claude Code-Projekts.

Benötige ich einen Remoteconnector?

No. Reine Fertigkeitspakete eignen sich gut für promptbasierte Workflows. Connectors sind nur erforderlich, wenn Ihre Fertigkeit Livedaten aus einem externen System benötigt.

Wie unterscheiden sich Plugin-Skills von integrierten Skills?

Plug-In-Fertigkeiten werden mit der Quelle "package" in der API angezeigt. Sie können integrierte Skills gleichen Namens nicht außer Kraft setzen. Vom Admin bereitgestellte Pakete zeigen isAdminDeployed: true an.

Können IT-Administratoren steuern, welche Plug-Ins verfügbar sind?

Ja. Es gelten die standardmäßigen M365-Administratorsteuerelemente: Zulassungs-/Sperrlisten auf Mandantenebene, vom Administrator verwaltete Bereitstellungen und Konformitätsrichtlinien.

Was geschieht, wenn ein Plug-In widerrufen wird?

Beim nächsten Synchronisierungszyklus werden die Fähigkeiten und Connectors aus diesem Paket aus der Sitzung des Benutzers entfernt. Aktive Unterhaltungen werden nicht unterbrochen, aber neue Sitzungen verfügen nicht über die Funktionen des Pakets.

Was ist die maximale Anzahl an Skills pro Paket?

Zwanzig (20) Fertigkeiten (pro ASKILL-M002). Für Connectors beträgt das Limit 10 pro Paket.

Können Fähigkeiten auf Konnektortools aus demselben Paket verweisen?

Ja, und das sollten sie. Benennen Sie die Tools explizit in Ihrem SKILL.md Workflow (z. B. "Verwenden Sie das search_case_law Tool, um ..."). Der Agent verbindet sie zur Laufzeit.

Können die Tools meines Plugins Dateien aus dem Cowork-Arbeitsbereich akzeptieren?

Ja. Deklarieren Sie den Toolparameter mit contentEncoding: base64; Cowork wandelt die Workspace-Datei des Benutzers in Base64-Inhalt um, bevor Ihr Server aufgerufen wird. Das Modell übergibt Dateipfade, nicht Dateiinhalte, sodass große Dateien nicht den Kontext des Modells beanspruchen. Deklarationsdetails und Limits finden Sie unter Akzeptieren von Dateien aus dem Cowork-Arbeitsbereich.

Wie generiere ich eine deterministische GUID für mein Paket?

wiqd plugin create generiert die App-ID für Sie und heftet sie an. Das Konvertierungsskript verwendet UUID v5 (SHA-1-basiert) aus Ihrem Plug-In-Namen, sodass bei zweimaliger Ausführung der Konvertierung dieselbe GUID erzeugt wird. Verwenden Sie für die manuelle Verpackung einen beliebigen GUID-Generator. Achten Sie darauf, dass er versionsübergreifend stabil bleibt.

Auf welche Manifestversion sollte ich abzielen?

Verwenden Sie 1.29, wenn Sie mit wiqd arbeiten, da diese für Sie angeheftet wird. Bei 1.29 sind agentConnectors[]-Einträge nur URLs und mcpToolDescription ist optional. Die handgeschriebenen Beispiele in diesem Artikel verwenden 1.28, wobei mcpToolDescription erforderlich ist und die Dateinamen in der ZIP-Datei enthalten sein müssen. atk import openplugin verwendet UUID v5 (SHA-1-basiert) aus deinem Plug-In-Namen. Wenn der Import zweimal ausgeführt wird, wird dieselbe GUID erzeugt. Übergeben Sie zum Festlegen Ihrer eigenen --app-id. Verwenden Sie für die manuelle Verpackung einen beliebigen GUID-Generator. Achten Sie darauf, dass er versionsübergreifend stabil bleibt.

  • Zuletzt aktualisiert um