Plug-Ins für Copilot Cowork erstellen

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.

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 Agent Skills open standard – das gleiche Format, das von Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie und 30+ anderen KI-Tools unterstützt wird.

Startpunkt auswählen

Vorhandenes Plug-In importieren

Wenn Sie bereits über ein Claude Code- oder Cursor-Plug-In mit Skills und MCP-Servern verfügen, wird es direkt von der Microsoft 365 Agents Toolkit CLI (atk) importiert. Die Befehlszeilenschnittstelle wird unter Windows, macOS und Linux ausgeführt.

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 das .claude-plugin/plugin.json Verzeichnis (oder .cursor-plugin/plugin.json), .mcp.jsonund skills/ des Plugins und erstellt dann ein Gerüst für ein Agents Toolkit-Projekt, das , Ihre Fähigkeiten und generierte Symbole enthält appPackage/manifest.json.

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

Verpacken Sie das Ergebnis in eine hochladbare Datei .zip:

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

Was wird importiert?

Was nicht konvertiert wird

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

Importoptionen

Automatische Erkennung des Authentifizierungstyps:

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

Exportieren zurück in ein Plug-In-Verzeichnis

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

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äterer atk import openplugin Roundtrip erforderlich --privacy-url ist oder --terms-url erneut.

Legacy: PowerShell-Konvertierungsskript

Vor dem atk unterstützten Plug-In-Import 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 atk import openplugin stattdessen. Es ist plattformübergreifend, unterstützt sowohl Cursor- als auch Claude-Code-Quellen und kann zurück in ein Plugin-Verzeichnis exportiert werden.

Ein Plug-In von Grund auf neu erstellen

Führen Sie die folgenden Schritte aus, um ein Plugin-Paket von Grund auf zu erstellen. Beginnen Sie mit Ihrer ersten Fertigkeit und bauen Sie sich dann zu einem vollständigen, veröffentlichungsfähigen Paket auf.

Schritt 1: Erstellen Ihrer ersten Fähigkeit

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 Frontmateriefelder

Erforderliche Felder:

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

Schritt 2: Referenzmaterialien hinzufügen (optional)

Bei komplexen Fähigkeiten sollten Sie den Hauptzugriff SKILL.md beibehalten und detaillierte Inhalte in Unterverzeichnisse verschieben. Bei diesen zusätzlichen Dateien handelt es sich um 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. Pro Skill gelten folgende Limits:

Regeln für Begleitdateien

Pfade von Begleitdateien müssen den folgenden Regeln entsprechen:

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

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

Verweisen Sie explizit auf SKILL.md 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: Hinzufügen eines Connectors (optional)

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

Connectoranforderungen

Richtlinien für den Werkzeugentwurf

• Ein Tool pro Aktion für kleine APIs (weniger als 15 Vorgänge): search_case_law, get_ruling, cite_precedent
• Suchen + 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 Benutzer formatieren kann
• Dateieingaben: Um eine Datei aus dem Arbeitsbereich des Benutzers zu akzeptieren, deklarieren Sie den Parameter mit contentEncoding: base64. Weitere Informationen finden Sie unter Akzeptieren von Dateien aus dem Cowork-Arbeitsbereich.

Beschreiben Sie die Tools Ihres Connectors (mcpToolDescription)

Jeder remoteMcpServer Verbinder muss ein mcpToolDescription Objekt enthalten. Die verschachtelte file Eigenschaft verweist auf eine JSON-Datei mit der Toolbeschreibung, die Sie in Ihrem .zip Paket packen und auf die Sie über einen relativen Pfad vom Paketstamm verweisen. Wenn Sie dies mcpToolDescriptionweglassen, lehnt der Paketdienst den Upload mit einem HTTP 400-Fehler ab:

Erforderliche Eigenschaften fehlen im Objekt: mcpToolDescription.

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

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

Unterstützte Authentifizierungstypen

Für OAuthPluginVault und ApiKeyPluginVaultverweisen die referenceId Punkte 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.

MCP-Authentifizierung

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

Dynamic Client Registration

Wenn Ihr MCP-Server die Dynamic Client Registration (DCR) unterstützt, können Sie eine authentication Konfiguration in Ihrer Connectordefinition weglassen, und Cowork erstellt automatisch einen OAuth-Client im Namen Ihres Plug-Ins.

Sie können das authorization Objekt weglassen, müssen aber trotzdem einfügen mcpToolDescription. Konfigurieren Sie die URL und die Toolbeschreibung Ihres MCP-Servers, und Cowork kümmert sich um den OAuth-Client:

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

Schritt 4: Erstellen des Manifests

Erstelle manifest.json in deinem Paketstamm:

{
  "$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 Folgendes ein agentConnectors:

{
  "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 die OAuth-Registrierungs-ID enthalten sein und mcpToolDescription.file auf eine JSON-Datei mit der Toolbeschreibung verweisen, die im ZIP-Paket enthalten ist.

Schritt 5: Hinzufügen von Symbolen

Erstelle zwei PNG-Symbole:

Wenn Sie noch keine Symbole haben, atk import openplugin werden einfarbige Platzhalter generiert. Ersetzen Sie sie vor der Übermittlung an den Shop.

Schritt 6: Verpacken

Erstellen Sie eine ZIP-Datei mit dem gesamten Inhalt auf der Stammebene:

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

Wenn Ihr Paket einen agentConnectors Eintrag enthält, fügen Sie die JSON-Datei mit der Tool-Beschreibung ein, auf die von verwiesen wird mcpToolDescription.file. Nur Skills-Pakete 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.

Laden Sie die App zum persönlichen Testen über die Befehlszeilenschnittstelle des Microsoft 365 Agents Toolkit quer:

1. Installieren @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 Geschäftskonto an und installieren Sie das Agent-Paket. 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 für die spätere Verwendung beim Aktualisieren oder Deinstallieren.

Weitere Informationen finden Sie unter Befehlszeilenschnittstelle Microsoft 365 Agents Toolkit.

Schritt 8: Veröffentlichen in Ihrem Mandanten

1. Öffnen des M365 Admin Centers>Verwalten von Apps>Benutzerdefinierte App hochladen.
2. Wählen Sie die Schaltfläche mit den Auslassungspunkten (...)>Agent hinzufügen.
3. Laden Sie Ihr .zip Paket hoch.
4. Öffnen Sie Cowork>Sources &Skills-Plug-Ins>. Ihr Plug-In wird im Abschnitt "Entdecken" angezeigt.

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

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

Testen eines Connectors mit einem lokalen MCP-Server

Connectors erfordern ein HTTPS-Token mcpServerUrl, daher müssen Sie ihn zum Testen eines auf Ihrem Computer ausgeführten Servers über eine öffentliche HTTPS-URL verfügbar machen. Dev-Tunnel stellen ein Relay bereit, das TLS für Sie beendet.

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

Problembehandlung

Verpackungsmuster

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

Nur Skills (kein Connector)

Am besten geeignet für zeitnahe 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
│   └── 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 die integrierten Fähigkeiten von Cowork bereits verwenden können.

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

Importierter Claude-Code oder Cursor-Plug-In

Verwenden Sie diese Option für vorhandene Plug-Ins von anderen KI-Tools, die auf Cowork ausgerichtet sind.

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 zur Erstellung von Fähigkeiten

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

Effektive Beschreibungen verfassen

Das description Feld bestimmt, wann der Agent Ihren Skill aktiviert. Seien Sie 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.

Schreiben effektiver Workflows

• Seien Sie in der Beschreibung genau. Triggerphrasen einschließen: "Verwenden, wenn Benutzer darum bittet..." Mit dieser Beschreibung entscheidet der Agent, welche Fertigkeit aktiviert werden soll.
• Struktur als Workflow. Nummerieren Sie die Schritte. 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.
• Referenztools nach Namen. Wenn Ihre Fähigkeiten von Connectortools abhängen, benennen Sie diese explizit: "Verwenden Sie das search_case_law Tool, um..."
• Halten Sie die Haupt 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. Verwendung agentConnectors mit Auth für API-Anmeldeinformationen.
• Duplizieren Sie integrierte Skills nicht. Überprüfen Sie vor dem Erstellen die integrierte Liste der Fähigkeiten .
• Machen Sie die Fähigkeiten nicht zu breit. "Alles mit Rechtsdokumenten machen" ist schlechter als spezifische Fähigkeiten 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 Text mehr als ~3.000 Wörter enthält, verschieben Sie detaillierte Inhalte in references/.

Gültigkeitsprüfungsregeln

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

Überprüfung auf Manifestebene

Überprüfung auf Paketebene

Connector-Validierung

Überprüfung von Begleitdateien

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

Plattformübergreifende Kompatibilität

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

Wenn Sie Fähigkeiten für Claude Code und Cowork entwickeln, beginnen Sie mit der Claude Code-Plugin-Struktur - es ist die Obermenge:

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)

Importieren Sie es dann in ein M365-Projekt, wenn Sie bereit sind, es im Microsoft 365 App Store zu veröffentlichen:

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 auf Tools, von denen tools/listIhr Server zurückkehrt, und entscheidet damit, ob ein Toolaufruf vom Benutzer bestätigt werden muss und welche Bezeichnung in der Eingabeaufforderung angezeigt werden soll.

Verfügbare Felder

Regeln für die Bestätigung

Eine 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 Lesewert, der automatisch ausgeführt wird:

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

Was ist jetzt verfügbar?

• Microsoft-Tools (Graph, Dataverse und andere) werden unabhängig von Anmerkungen durch die integrierte Richtlinie von Cowork begrenzt.
• Für MCP-Server, die nicht von Microsoft stammen, erfolgt das schrittweise Rollout der anmerkungsgesteuerten Bestätigung. Das Festlegen der Hinweise ist jetzt vorwärtskompatibel, und Bestätigungsaufforderungen werden angezeigt, wenn das Rollout erweitert wird, ohne dass ein Entwicklerwechsel erforderlich ist.

Akzeptieren von Dateien aus dem Cowork-Arbeitsbereich

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 (keyword)contentEncoding: base64, und Cowork kümmert sich um den Rest. 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 base64-codiert, bevor Sie Ihren Server aufrufen, sodass Dateibytes nie in den Kontext des Agenten gelangen. Der Agent sieht und gibt immer nur Arbeitsbereichsdateipfade aus.

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 für 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.propertiesdeklariert sind, ersetzt Cowork sie im modellseitigen Schema durch ein einzelnes direct_attachment_file_paths Array – denselben Parameter, den die integrierten Tools von Cowork verwenden, sodass der Agent bereits weiß, wie er aufgefü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 in diesem einen direct_attachment_file_paths Array reduziert. Zur Aufrufzeit fächert Cowork die aufgelösten Dateien wieder in Ihre ursprünglichen Parameternamen in Deklarationsreihenfolge auf.

Parameter geschachtelter Dateien

Ein Dateiparameter, der in einem Objekt oder einem Array von Objekten geschachtelt ist, wird ebenfalls unterstützt und anders behandelt: Anstatt reduziert zu werden, wird er an Ort und Stelle in eine Pfadzeichenfolge an seinem eigenen Speicherort neu geschrieben. Dadurch wird die Zuordnung zwischen einer Datei und ihren gleichgeordneten Feldern beibehalten, z. B. 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 Anruf weitergeleitet wird.

Das Nisten erfolgt bis zu einer Tiefe von vier Ebenen unterhalb der Spitze des .inputSchema $ref Zeiger werden nicht befolgt – definieren Sie Dateiparameter inline und nicht hinter einer $ref.

Was Ihr Server empfängt

Ihr Server erhält eine gewöhnliche tools/call App, in der Ihre ursprünglichen Parameternamen mit Base64-codiertem Inhalt ausgefü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 Parameter nicht deklarieren contentEncoding: base64 , sind davon nicht betroffen.

Einschränkungen

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.

Empfehlungen

• Beschreiben Sie den Parameter für einen menschlichen Leser. Der Agent entscheidet anhand der Beschreibung, welche Datei zu welchem Parameter gehört. Funktioniert "The signed contract PDF to analyze" beispielsweise besser als "file".
• Geben Sie die Formate, die Sie akzeptieren , in der Parameterbeschreibung an. Cowork durchläuft alles, was der Benutzer anfügt. Validiere den Inhaltstyp auf deiner Seite und gib einen klaren Toolfehler zurück, wenn er nicht verwendbar ist.
• Festlegen von Anmerkungen. Ein Tool, das eine Datei empfängt und entsprechend handelt, ist normalerweise nicht schreibgeschützt und fordert daher zur Bestätigung auf. Siehe MCP-Annotation und Bestätigungsverwaltung.
• Halten Sie Dateiparameter inline. Ein Parameter, der sich hinter einer $refoder tiefer als vier Ebenen 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.
• Erwarten Sie eine genaue Anzahl von Tools, die nur skalare Komponenten verwenden. 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.

Identifizieren des Cowork-Datenverkehrs zu Ihrem Server

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

Ü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 dein Gate über Versionsschwankungen hinweg funktioniert.

# Correct: case-insensitive prefix match
copilot-cowork

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

Wählen Sie den richtigen Kanal für Ihr Tor

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

• Der User-Agent Header ist in jeder Anforderung vorhanden, einschließlich tools/list und tools/call. Wenn Sie Gate oder Attribut pro Anforderung verwenden, geben Sie diesen Header ein.
• clientInfo wird nur beim initialize Handshake gesendet. Wenn Sie ein Gate pro Sitzung zur Verbindungszeit verwenden, können Sie es dort lesen, aber es wird bei späteren Anforderungen 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.

Da es keinen Grenzwert 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äufige Fragen

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

Ja. Die Skill-Ordner enthalten standardmäßige Agent-Skills. Kopieren Sie sie in .claude/skills/ ein beliebiges Claude Code-Projekt oder führen Sie sie ausatk export openplugin, um das gesamte Projekt wieder in ein Claude Code-Plugin zu konvertieren.

Benötige ich einen Remoteconnector?

Nein Reine Skill-Pakete eignen sich gut für Prompt-basierte Workflows. Connectors werden nur benötigt, wenn Ihr Skill Livedaten von einem externen System benötigt.

Wie unterscheiden sich Plugin-Skills von integrierten Skills?

Plugin-Fähigkeiten 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

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 Skills 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.

Wie viele Skills können pro Paket maximal verwendet werden?

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, und Cowork löst die Arbeitsbereichsdatei des Benutzers in base64-Inhalt auf, bevor Sie Ihren Server aufrufen. 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.

Gewusst wie eine deterministische GUID für mein Paket generieren?

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. Um ein eigenes zu erstellen, übergeben --app-idSie . Verwenden Sie für die manuelle Verpackung einen beliebigen GUID-Generator. Achten Sie darauf, dass sie versionsübergreifend stabil bleibt.

Verwandte Inhalte

• Übersicht über Cowork
• Verwenden von Cowork
• Verwalten von Cowork für Ihre organization
• Plugins für Cowork verwalten