Plug-ins bouwen voor Copilot Cowork

Microsoft Copilot Cowork ondersteunt uitbreidbaarheid via M365-app-pakketten, hetzelfde distributiemechanisme dat wordt gebruikt door Teams-apps, Copilot-agents en Office-invoegtoepassingen. Je kunt Cowork uitbreiden met:

• Vaardigheden: Werkstromen op basis van prompts die Cowork nieuwe domeinexpertise leren, zoals financiële analyse, juridisch onderzoek of HR-werkstromen.
• Connectors: servers op afstand die Cowork toegang geven tot externe gegevensbronnen en API's.

Beide zijn samen verpakt in een standaard Microsoft 365-app-pakket en worden gedistribueerd via de Microsoft 365 App Store.

Microsoft maakt of onderhoudt geen permanente index, knowledge graph (inclusief de Microsoft Graph) of database die ISV-inhoud bevat, hetzij door crawlen, scrapen, oogsten, bulksgewijze export, gegevensinvoer of enige andere methode (via API, MCP-server of anderszins). Microsoft kan ISV-inhoud tijdelijk verwerken als dat nodig is om te reageren op de realtimequery van een gebruiker, maar bewaart ISV-inhoud niet langer dan de duur van die sessie. Op schriftelijk verzoek van ISV verwijdert Microsoft binnen 10 werkdagen alle ISV-inhoud die zij in haar bezit of beheer heeft en bevestigt zij dit schriftelijk. Meer informatie in Zakelijke gegevensbescherming in Microsoft Copilot en Microsoft Copilot Chat.

Wat u gaat bouwen

Een Cowork-plug-in is een .zip pakket met:

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

Vaardigheden maken gebruik van de Agent Skills-open standaard: dezelfde indeling die wordt ondersteund door Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie en meer dan 30 andere AI-hulpprogramma's.

Uw beginpunt kiezen

Bouw uw plug-in met de wiqd CLI. De CLI maakt het pakket en houdt manifest.json en uw vaardigheidsmappen gesynchroniseerd. Het voert ook de eigen validatieregels van het platform uit voordat u uploadt, waarna het resultaat wordt ingericht en gedeeld. De CLI is in preview, dus de opdrachten en gegenereerde uitvoer kunnen veranderen voordat ze algemeen beschikbaar zijn. Er wordt alleen een eenvoudig Microsoft 365-app-pakket gegenereerd, zodat u de bestanden nog steeds rechtstreeks kunt openen, bewerken en van versies kunt voorzien.

Stel het pakket alleen handmatig samen wanneer u geen hulpprogramma's kunt installeren of wanneer u uw eigen verpakkingspijplijn bouwt. In dat geval hebt u de referentie voor de pakketindeling in dit artikel nodig: het beschrijft precies wat wiqd oplevert.

Een invoegtoepassing bouwen met wiqd

De wiqd-CLI doorloopt dezelfde levenscyclus die u anders handmatig uitvoert: creëren, mogelijkheden toevoegen, valideren, inrichten, inpakken en delen. Het pakket dat wordt geproduceerd, voldoet al aan de validatieregels in dit artikel.

Stap 1: Installeer wiqd en meld u aan

Installeer de wiqd CLI door de wiqd-installatiehandleiding te volgen, die betrekking heeft op Windows, macOS en Linux. Meld u vervolgens aan bij de Microsoft 365-tenant waarvoor u ontwikkelt, omdat het inrichten en delen beide gebruikmaken van uw tenant:

wiqd auth login --interactive

Het installatieprogramma registreert ook een GitHub Copilot CLI-invoegtoepassing, zodat u dezelfde levenscyclus in het gesprek kunt beheren. Je kunt bijvoorbeeld zeggen: maak een standalone plugin genaamd Triage Helper of Valideer mijn plugin. Het gesprekspad voert dezelfde opdrachten uit als deze sectie. Gebruik de opdrachten rechtstreeks wanneer u een script voor een pijplijn aan het uitvoeren bent of reproduceerbare, niet-interactieve automatisering wilt.

Stap 2: maak de invoegtoepassing en voeg mogelijkheden toe

Maak de plugincontainer en voeg vervolgens alle mogelijkheden toe die u nodig hebt, in een willekeurige combinatie:

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 genereert de basis voor appPackage/skills/contract-analysis/SKILL.md en registreert het in agentSkills[]. add connector schrijft de agentConnectors[] vermelding. Beide opdrachten dwingen de naamgeving en groottelimieten van het platform af voordat ze schrijven, dus een mapnaam die niet overeenkomt of een te lange id bereikt nooit het manifest.

Schrijf uw vaardigheidslogica in de gegenereerde SKILL.md. De frontmatter-velden, het model voor progressief laden en de limieten voor companion-bestanden zijn dezelfde als beschreven in Stap 1: Maak uw eerste vaardigheid en Stap 2: Voeg referentiemateriaal toe (optioneel).

Stap 3: Valideren tijdens het maken

Continu valideren in plaats van een pakket samen te stellen en hopen dat de upload slaagt:

wiqd plugin validate
wiqd plugin validate --mode deep

validate is de offline statische controle over het declaratieve agentoppervlak. Een invoegtoepassing met alleen vaardigheden of connectors slaagt zonder iets te controleren, wat te verwachten is. Het is een controle voor uw buildlus, niet voor volledige dekking. validate --mode deep verpakt eerst de invoegtoepassing en valideert vervolgens de gebouwde .zip aan de hand van dezelfde app-validatiebibliotheek die voor het uploaden wordt gebruikt. Dat is waar de ASKILL-codes en connectorregels opduiken.

Stap 4: Implementeren, verpakken en delen

Voer deze drie opdrachten in de aangegeven volgorde uit:

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

Voer eerst provision uit, omdat dat het omgevingsbestand schrijft waarvan package en share beide afhankelijk zijn. Gebruik --scope users om te delen met de personen die u opgeeft, of --scope tenant om te delen met iedereen in uw organisatie. Hoe dan ook, de plug-in verschijnt in Gedeeld met mij onder Cowork>Bronnen & Skills>Plugins. Als het pakket in de sectie Ontdekken wordt weergegeven, uploadt een beheerder het pakket. Meer informatie vindt u in stap 8: Publiceren naar uw tenant. Als u wilt verwijderen wat provision heeft gemaakt, voert u wiqd plugin delete --env local --yes uit.

Inzending in de openbare Store is nog steeds een handmatig proces in het Partnercentrum. Meer informatie vindt u in stap 9: publiceren voor het publiek.

Een invoegtoepassing overzetten naar een andere host

Als je je vaardigheden wilt gebruiken in Claude Code, Cursor of een andere Agent Skills-host, exporteer je het project in plaats van mappen handmatig te kopiëren:

wiqd plugin export --format claude-plugin

export is standaard ingesteld op --format open-plugin en accepteert ook cursor-plugin. Het schrijft een niet-gecomprimeerde map onder <path>/export/<format>.

Een bestaande invoegtoepassing importeren

Als u al een Claude Code-invoegtoepassingen hebt met vaardigheden en MCP-servers, hebt u twee conversieroutes. De route die je kiest, hangt af van of je van plan bent de plugin te blijven ontwikkelen of gewoon uit te brengen wat je hebt.

Importeren met wiqd

wiqd plugin import herkent een Open Plugin, Claude plugin of Cursor plugin source en produceert er een wiqd plugin project van. De geïmporteerde plug-in doorloopt dezelfde levenscyclus als een plug-in die u met wiqd plugin create hebt gemaakt:

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

--privacy-url en --terms-url zijn alleen vereist voor de eerste import van een invoegtoepassing. Als de bron afkomstig is van een vorige wiqd plugin export, bevat de roundtrip-metadata die gegevens al.

Converteren met het conversiescript

Het conversiescript vertaalt een Claude-plug-in rechtstreeks naar een publiceerbaar M365-pakket:

1. Installeer de CLI (versie 1.1.12 of hoger vereist):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Controleer de versie:

   atk --version
   

3. Importeer uw invoegtoepassing:

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

De opdracht leest uw invoegtoepassingsmap .claude-plugin/plugin.json (of .cursor-plugin/plugin.json), .mcp.json en skills/ en vervolgens een Agents Toolkit-project met appPackage/manifest.json, uw vaardigheden en gegenereerde pictogrammen.

U moet --privacy-url en --terms-url opnemen, omdat invoegtoepassingsmanifesten geen overeenkomende velden hebben en het Microsoft 365-manifest beide vereist.

Verpak het resultaat in een uploadbare .zip:

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

Wat wordt geïmporteerd

Wat wordt niet geconverteerd

De volgende functies van de Claude-invoegtoepassing worden nog niet ondersteund in het Microsoft 365-manifest:

Opties voor importeren

Automatische detectie van het verificatietype:

Als de automatische detectie niet overeenkomt met uw instellingen, gebruik --default-auth-type om dit te overschrijven.

Terug exporteren naar de map met invoegtoepassingen

Om een Agents Toolkit-project terug te verplaatsen naar een plug-inmap, bijvoorbeeld om een Claude Code-plug-in en een Cowork-pakket gesynchroniseerd te houden, gebruikt uatk export openplugin:

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin

Export schrijft een x-microsoft-365-agents-toolkit-blok naar het gegenereerde plugin.json. Dat blok bevat het manifest id, de ontwikkelaars-URL's en de connectorinstellingen, dus een latere atk import openplugin round-trip zonder dat --privacy-url weer nodig is of --terms-url.

Verouderd: PowerShell-conversiescript

Voordat atk de import van een invoegtoepassing ondersteunde, werd voor de conversie een PowerShell-script gebruikt dat alleen onder Windows beschikbaar is en beschikbaar blijft als het conversiescript:

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

Gebruik in plaats daarvan atk import openplugin. Het is platformonafhankelijk, ondersteunt zowel Cursor- als Claude Code-bronnen en kan terug exporteren naar een plug-inmap.

Een pakket handmatig samenstellen

Deze sectie is de referentie voor pakketformaten: het beschrijft precies wat Build a plugin with wiqd genereert, veld voor veld. Volg dit proces van begin tot eind wanneer u geen tools kunt installeren of wanneer u uw eigen verpakkingspijplijn opzet. Gebruik het als referentie wanneer u een gegenereerd pakket wilt begrijpen of fouten in een gegenereerd pakket wilt opsporen.

Stap 1: Maak je eerste vaardigheid

Een skill is een map die een SKILL.md bestand bevat. Maak de volgende mapstructuur:

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

Schrijf SKILL.md met YAML-frontmatter en een hoofdtekst in Markdown:

---
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-frontmattervelden

Vereiste velden:

Naamgevingsregels (kebab-case): Gebruik alleen alfanumerieke tekens in kleine letters en afbreekstreepjes. Gebruik geen opeenvolgende afbreekstreepjes en geen afbreekstreepjes aan het begin of einde.

Stap 2: Referentiemateriaal toevoegen (optioneel)

Voor complexe vaardigheden houdt u de hoofd- SKILL.md compact en verplaatst u gedetailleerde inhoud naar submappen. Deze extra bestanden zijn begeleidende bestanden. De vaardigheid laadt deze indien nodig.

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

Limieten voor bijbehorende bestanden

Elke vaardigheid kan maximaal 20 begeleidende bestanden bevatten (elk bestand behalve SKILL.md). Per vaardigheid gelden de volgende limieten:

Regels voor begeleidende bestanden

Begeleidende bestandspaden moeten voldoen aan de volgende regels:

• Gebruik alleen relatieve paden (geen absolute paden).
• Geen padtraversal (.. segmenten).
• Geen backslashes of nulbytes in bestandsnamen.
• Geen verborgen bestanden (namen die beginnen met .).
• Geen gereserveerde namen voor Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
• Het bestand SKILL.md zelf telt niet mee als begeleidend bestand.
• Bestandsnamen moeten veilige tekens bevatten: alfanumeriek, koppeltekens, onderstrepingstekens, punten, spaties en !.

Om het contextvenster efficiënt te houden, laadt het systeem vaardigheden in drie lagen:

Verwijs expliciet in SKILL.md naar de submappen, zodat de agent weet dat ze bestaan:

## 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

Stap 3: Een verbindingslijn toevoegen (optioneel)

Als uw extensie toegang nodig heeft tot externe gegevens, voegt u een externe MCP-server toe. Deze stap is optioneel. Pakketten met alleen vaardigheden werken goed voor op prompts gebaseerde werkstromen.

Connectorvereisten

Richtlijnen voor toolontwerp

• Eén hulpprogramma per actie voor kleine API's (minder dan 15 bewerkingen): search_case_law, get_ruling, cite_precedent
• Search + execute voor grote API's (50+ bewerkingen): search_actions + execute_action
• Beschrijvende namen: get_bond_price niet getData
• Uitgebreide invoerschema's: neem een beschrijving op voor elke parameter. Dit is wat de agent leest
• Gestructureerde uitvoer: Retourneer JSON dat de agent kan opmaken voor de gebruiker
• Bestandsinvoer: Als u een bestand wilt accepteren vanuit de werkruimte van de gebruiker, declareert u de parameter met contentEncoding: base64. Meer informatie vindt u in Bestanden accepteren uit de Cowork-werkruimte.

Beschrijf de hulpprogramma's van uw connector (mcpToolDescription)

Een remoteMcpServer connector kan optioneel een mcpToolDescription object bevatten. Als deze is opgegeven, verwijst de geneste file eigenschap naar een JSON-bestand met een hulpprogrammabeschrijving, dat u in uw .zip verpakt en waarnaar wordt verwezen via een relatief pad vanaf de hoofdmap van het pakket. Cowork detecteert hulpprogramma's dynamisch van uw MCP-server en gebruikt dit bestand niet, zelfs niet als het aanwezig is.

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

Als u mcpToolDescription opneemt, beschrijft het bestand waarnaar wordt verwezen (bijvoorbeeld tools/contoso-legal-tools.json) de hulpprogramma's die de connector beschikbaar stelt en aanwezig moet zijn in het ZIP-pakket. Voeg deze toe aan uw manifest.json en skills/ map wanneer u de invoegverpakking verpakt.

Ondersteunde authenticatietypen

U vindt een referentiepatroon dat Cowork verbindt met een met API-sleutel beveiligde service via een met Entra beveiligd MCP-eindpunt in Build a plugin voor een Line-Of-Business-API.

Voor OAuthPluginVault en ApiKeyPluginVault, verwijst de referenceId naar referenties die zijn opgeslagen in de Microsoft Enterprise Token Store. Geheimen worden nooit weergegeven in het manifest- of vaardigheidsbestand. De referenceId waarde is de OAuth-clientregistratie-id die u maakt wanneer u een OAuth-client registreert bij Agents Toolkit.

MCP-verificatie

Raadpleeg Authenticatie configureren voor MCP- en API-plug-ins in agents in Microsoft 365 Copilot voor installatie- en configuratiedetails als u OAuth of ApiKey wilt gebruiken voor authenticatie.

Dynamische clientregistratie

Als uw MCP-server Dynamic Client Registration (DCR) ondersteunt, kunt u een authentication-configuratie uit uw connectordefinitie weglaten en maakt Cowork automatisch een OAuth-client namens uw invoegtoepassing.

U kunt het authorization object helemaal weglaten. Configureer de URL van uw MCP-server en Cowork zorgt voor de OAuth-client:

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

Stap 4: Het manifest maken

Maak manifest.json aan in de hoofdmap van je pakket. In het voorbeeld wordt gebruikgemaakt van manifestversie 1.28; wiqd plugin create zet in plaats daarvan versie 1.29 vast, waar connectorvermeldingen alleen uit URL's bestaan.

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

Om een connector toe te voegen, neemt u agentConnectors op:

{
  "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 de connectorconfiguratie moet referenceId de OAuth-registratie-id zijn. Als u mcpToolDescription opneemt, moet de bijbehorende file verwijzen naar een JSON-bestand met de beschrijving van het hulpprogramma dat is opgenomen in het ZIP-pakket.

Stap 5: Pictogrammen toevoegen

Maak twee PNG-pictogrammen:

Als u nog geen pictogrammen hebt, genereert u atk import openplugin effen plaatsaanduidingen. Vervang ze voordat u deze indient bij de Store.

Stap 6: Verpakken

Maak een ZIP-bestand met alle inhoud in de hoofdmap. (wiqd plugin package produceert dezelfde structuur na 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

Als een connector mcpToolDescription bevat, moet u het JSON-bestand met de beschrijving van het hulpprogramma opnemen waarnaar dit verwijst. Pakketten die geen gebruikmaken van mcpToolDescription, waaronder pakketten met alleen vaardigheden, hebben geen tools/ map nodig.

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/

Microsoft 365 Agents Toolkit gebruiken

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

Stap 7: Test

Als u uw app wilt testen, uploadt u het app-pakket naar Teams, zoals beschreven in Uw app uploaden naar Teams.

Als u de plug-in met wiqd hebt gebouwd, voert u in plaats daarvan wiqd plugin provision uit: het registreert de plug-in voor u bij uw tenant. Voor persoonlijk testen van een met de hand samengesteld pakket, sideload de app met behulp van de opdrachtregelinterface van de Microsoft 365 Agents Toolkit:

1. Installeer @microsoft/m365agentstoolkit-cli vanaf npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Controleer de installatie door het volgende uit te voeren:

   atk --version
   

3. Aanmelden met uw Microsoft 365-werkaccount:

   atk auth login
   

4. Meld u aan bij uw werkaccount en installeer het agentpakket. Vervang het bestandspad door die van uw ZIP-bestand:

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

   Een geslaagde installatie retourneert uitvoer met een TitleId en AppId voor uw account.

5. Sla deze id's op voor later gebruik wanneer u ze bijwerkt of deïnstalleert.

Meer informatie vindt u in de opdrachtregelinterface van de Microsoft 365 Agents Toolkit.

Stap 8: Publiceren naar uw tenant

Upload het pakket in het beheercentrum om uw plug-in te vermelden in de sectie Discover, waar iedereen in uw organisatie de plug-in kan vinden:

1. M365-beheercentrum> openenApps> beherenAangepaste app uploaden.
2. Selecteer het beletselteken (...) >Agent toevoegen.
3. Laad uw .zip pakket op.
4. Open Cowork>Bronnen & vaardigheden>Invoegtoepassingen. Uw invoegtoepassing wordt weergegeven in de sectie Ontdekken.

wiqd plugin share plaatst de plugin in Gedeeld met mij in plaats van Discover. Gebruik het voor tests en voor gerichte implementatie bij specifieke personen. Uploads vanuit het Beheercentrum zorgen ervoor dat een invoegtoepassing wordt gedetecteerd.

Stap 9: Publiceer voor het publiek

Voor invoegtoepassingen die zijn bedoeld voor openbare distributie, dient u uw invoegtoepassing in bij de Microsoft 365 App Store via Partner Center. Meer informatie in Agents publiceren voor Microsoft 365 Copilot.

Een connector testen met een lokale MCP-server

Voor connectors is een HTTPS mcpServerUrlvereist. Als u een server die op uw computer wordt uitgevoerd, wilt testen, moet u deze toegankelijk maken via een openbare HTTPS-URL. Dev-tunnels bieden een relay waarmee TLS voor u wordt beëindigd.

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

Troubleshooting

Verpakkingspatronen

Kies het patroon dat bij jouw extensie past:

Alleen Skills (geen connector)

Geschikt voor werkstromen op basis van prompts, documentanalyse en hulp bij het schrijven.

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

Vaardigheden + externe connector

Ideaal voor gegevensanalyse, API-integraties en bedrijfssystemen.

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

Alleen de connector (geen aangepaste vaardigheden)

Gebruik deze optie voor gegevensbronnen die de ingebouwde vaardigheden van Cowork al kunnen gebruiken.

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

Geïmporteerde Claude Code of Cursor-invoegtoepassing

Gebruik deze optie voor bestaande plug-ins voor het Claude-ecosysteem die gericht zijn op Cowork. Als u de invoegtoepassing in Microsoft 365 wilt blijven ontwikkelen, importeert u deze:

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

Gebruik het conversiescript om een publiceerbaar .zip te produceren vanuit de invoegtoepassing zoals die er nu uitziet:

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

Best practices voor het ontwerpen van vaardigheden

Volg deze richtlijnen om vaardigheden te ontwikkelen die betrouwbaar worden geactiveerd en consistente resultaten produceren.

Effectieve beschrijvingen schrijven

Het description veld bepaalt wanneer de agent je vaardigheid activeert. Wees specifiek:

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

Schrijf effectieve werkstromen

• Wees specifiek in de beschrijving. Voeg triggerzinnen toe: "Gebruik wanneer de gebruiker vraagt om..." Met deze beschrijving bepaalt de agent welke vaardigheid moet worden geactiveerd.
• Structureer als een workflow. Geef de stappen een nummer. Elke stap moet worden toegewezen aan een concrete actie (een bestand lezen, een tool aanroepen, uitvoer genereren).
• Uitvoerindeling definiëren. Geef de exacte tabel-, lijst- of documentstructuur weer die gebruikers mogen verwachten. Deze definitie verbetert de consistentie drastisch.
• Verwijs naar tools bij naam. Als uw vaardigheid afhankelijk is van connectors, noem die dan expliciet: "Gebruik het hulpprogramma search_case_law om..."
• Houd de SKILL.md beknopt. Verplaats gedetailleerd referentiemateriaal naar de references/ submap. De inhoud van de vaardigheid moet de werkstroom zijn, geen encyclopedie.

Veelvoorkomende fouten voorkomen

• Neem geen geheimen op in SKILL.md-bestanden. Gebruik agentConnectors voor verificatie met API-inloggegevens.
• Dupliceer geen ingebouwde vaardigheden. Controleer de lijst met ingebouwde vaardigheden voordat u gaat bouwen.
• Maak geen vaardigheden te breed. "Alles doen met juridische documenten" werkt slechter dan specifieke vaardigheden voor "contractanalyse", "clausule-extractie" en "juridisch onderzoek".
• Hardcodeer geen bestandspaden of systeemopdrachten. Vaardigheden moeten in verschillende omgevingen inzetbaar zijn.
• Zet niet alles in SKILL.md. Als uw hoofdtekst meer dan ~3.000 woorden bevat, verplaatst u gedetailleerde inhoud naar references/.

Validatieregels

Wanneer u uw pakket indient, valideert het platform het op meerdere niveaus. Corrigeer deze fouten voordat u ze inzendt om afwijzing te voorkomen.

Als u ze tijdens het bouwen wilt opvangen in plaats van tijdens het uploaden, voert u het volgende uit wiqd plugin validate --mode deep. Deze opdracht verpakt de invoegtoepassing en voert dezelfde regels lokaal uit. Meer informatie in Stap 3: Valideren tijdens het bouwen.

Validatie op manifestniveau

Validatie op pakketniveau

Connectorvalidatie

Validatie van bijbehorend bestand

Het portaal valideert begeleidende bestanden (referentiemateriaal, scripts en andere bestanden naast SKILL.md) tijdens het uploaden en synchroniseren:

Platformoverschrijdende compatibiliteit

Skills maken gebruik van de open standaard van Agent Skills. Dezelfde SKILL.md bestanden werken in meerdere AI-hulpprogramma's:

Als u vaardigheden ontwikkelt voor zowel Claude Code als Copilot Cowork, schrijf de invoegtoepassing dan met wiqd. Voer vervolgens wiqd plugin export --format claude-plugin uit om de Claude Code-indeling te genereren. Als u liever begint met de structuur van de Claude Code-invoegtoepassing — dat is de meest uitgebreide variant — dan is de indeling:

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)

Breng het vervolgens naar Microsoft 365 wanneer u klaar bent om in de Microsoft 365 App Store te publiceren, met wiqd plugin import of met het conversiescript:

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

Beheer van MCP-annotaties en bevestigingen

Copilot Cowork leest het standaard MCP-object annotations bij hulpprogramma's die uw server van tools/list retourneert en gebruikt dit om te bepalen of een hulpprogramma-aanroep door de gebruiker moet worden bevestigd en welk label op de prompt moet worden weergegeven.

Beschikbare velden

Bevestigingsregels

Bevestiging is vereist als readOnlyHint == false of destructiveHint == true.

Voor alle gereedschappen moeten veiligheidsannotaties zijn gespecificeerd. Hulpprogramma's zonder aantekeningen worden als destructief beschouwd en vereisen bevestiging. Meer informatie vindt u in de MCP-schemaverwijzing.

MCP-voorbeelden

Een destructieve actie met een vriendelijk label:

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

Een veilige leesbewerking die automatisch wordt uitgevoerd:

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

Wat is er nu beschikbaar

• Microsoft-hulpprogramma's (Graph, Dataverse en andere) vallen onder het ingebouwde beleid van Cowork, ongeacht eventuele aantekeningen.
• Voor MCP-servers die niet van Microsoft zijn, wordt aantekeninggestuurde bevestiging geleidelijk geïmplementeerd. Het instellen van de hints is nu toekomstbestendig en bevestigingsprompts verschijnen wanneer de implementatie wordt uitgebreid, zonder dat er een wijziging van de ontwikkelaar nodig is.

Accepteer bestanden uit de Cowork-werkruimte

Een connectorhulpprogramma kan een bestand uit de Cowork-sessie van de gebruiker als invoer gebruiken: een document dat de gebruiker heeft bijgevoegd, een e-mailbijlage die door Cowork is opgeslagen of een bestand dat een eerdere stap heeft geproduceerd. Definieer de parameter met het standaard JSON Schema-trefwoord contentEncoding: base64 en Cowork regelt de rest. Er is geen vereiste Microsoft-specifieke schema-extensie en het API-oppervlak van uw server verandert niet.

Cowork bepaalt het werkruimtebestand en base64 codeert het voordat uw server wordt aangeroepen, zodat bestandsbytes nooit in de context van de agent belanden. De agent ziet en geeft alleen werkruimtebestandspaden door.

Een bestandsparameter declareren

Een tekenreekseigenschap met contentEncoding: base64 wordt herkend als bestandsinvoer:

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

Een lijst van dergelijke tekenreeksen wordt ook herkend voor hulpprogramma's die meerdere bestanden accepteren:

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

Wat de agent ziet

Voor bestandsparameters die op het hoogste niveau zijn inputSchema.propertiesgedeclareerd, vervangt Cowork deze in het modelgerichte schema door een enkele direct_attachment_file_paths array - dezelfde parameter die de ingebouwde tools van Cowork gebruiken, zodat de agent al weet hoe deze moet worden ingevuld. Het bovenstaande schema wordt aan de agent gepresenteerd als:

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

Als uw hulpprogramma meer dan één bestandsparameter op het hoogste niveau declareert, worden deze allemaal samengevouwen in die ene direct_attachment_file_paths array. Op het moment van aanroepen wijst Cowork de opgeloste bestanden opnieuw toe aan uw oorspronkelijke parameternamen in declaratievolgorde.

Geneste bestandsparameters

De agent ondersteunt een bestandsparameter die is genest in een object of een matrix van objecten. De agent verwerkt deze parameter anders: in plaats van deze samen te voegen, herschrijft de agent deze op dezelfde plaats naar een padstring op de oorspronkelijke locatie. Bij deze benadering blijft de koppeling tussen een bestand en de verwante velden behouden. U ontvangt bijvoorbeeld één kwitantie per onkostenpost:

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

De agent vult line_items[].receipt met een werkruimtepad en Cowork vervangt elk pad ter plekke door base64-inhoud voordat de aanroep wordt doorgeschakeld.

Geneste structuren worden doorlopen tot een diepte van vier niveaus onder de top van inputSchema. $ref aanwijzers worden niet gevolgd: definieer bestandsparameters inline in plaats van achter een $ref.

Wat uw server ontvangt

Je server ontvangt een standaard tools/call met je oorspronkelijke parameternamen ingevuld met inhoud die is gecodeerd met base64:

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

Uw server hoeft niet te weten dat de agent een op paden gebaseerde interface heeft gebruikt en hulpprogramma's die geen parameters declareren contentEncoding: base64 , worden niet beïnvloed.

Limits

Een aanroep die het maximale aantal bestanden of een groottelimiet overschrijdt, mislukt met een hulpprogrammafout en bereikt uw server nooit. Bepaal de grootte van uw API en de time-outs met het plafond van 150 MiB in gedachten: base64 blaast de payload met ongeveer een derde op ten opzichte van de onbewerkte bestandsgrootte en de gecodeerde inhoud wordt verzonden in de JSON-RPC-aanvraagtekst.

Recommendations

• Beschrijf de parameter voor een menselijke lezer. De agent bepaalt aan de hand van de beschrijving welk bestand bij welke parameter hoort. Bijvoorbeeld werkt "The signed contract PDF to analyze" beter dan "file".
• Geef de notaties op die u accepteert in de parameterbeschrijving. Cowork voert alles wat de gebruiker bijvoegt door. Valideer het inhoudstype aan jouw kant en retourneer een duidelijke toolfout als deze niet bruikbaar is.
• Aantekeningen instellen. Een hulpprogramma dat een bestand ontvangt en hierop bewerkingen uitvoert, is normaal gesproken niet alleen-leesbaar, dus vraagt het om bevestiging. Lees meer in Beheer van MCP-annotaties en -bevestiging.
• Houd bestandsparameters inline. Een parameter achter een $ref, of meer dan vier niveaus diep genest, wordt niet opnieuw geschreven. De server zou een padtekenreeks ontvangen waar inhoud wordt verwacht.
• Definieer ten hoogste één arraybestandsparameter per hulpprogramma. Bij twee of meer bestanden kan Cowork niet bepalen welk bestand bij welke matrix hoort, en mislukt de oproep met een hulpprogrammafout. Gebruik één matrix of meerdere scalaire parameters of een combinatie van scalaire waarden en één matrix.
• Verwacht een exacte telling voor hulpprogramma's die alleen scalaire waarden ondersteunen. Als je hulpprogramma alleen scalaire bestandsparameters declareert, moet het aantal bestanden dat de agent doorgeeft overeenkomen met het gedeclareerde aantal. Markeer optionele bestandsparameters duidelijk in hun beschrijvingen, zodat de agent niet te weinig of te veel levert.

Detecteer het Cowork-verkeer naar uw server

Als uw MCP-server de zichtbaarheid van hulpprogramma's per client beperkt, of als u het verkeer dat deze ontvangt wilt toewijzen, kunt u verzoeken van Cowork herkennen. Cowork presenteert een stabiele software-identiteit op twee kanalen:

Zoeken op het copilot-cowork voorvoegsel

Laat het copilot-coworkvoorvoegsel (niet hoofdlettergevoelig) overeenkomen op beide kanalen. Laat geen exacte copilot-cowork/1.0 tekenreeks of een specifiek clientInfo.version overeenkomen. De versie volgt het client-identiteitscontract en zal naar verwachting veranderen; een voorvoegselovereenkomst zorgt ervoor dat uw poort blijft werken bij versiewijzigingen.

# Correct: case-insensitive prefix match
copilot-cowork

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

Het juiste kanaal kiezen voor uw poort

De twee kanalen hebben verschillende bereiken, dus baseer u op het kanaal dat overeenkomt met de manier waarop uw server de toegang afdwingt:

• De User-Agent header is aanwezig op elk verzoek, inclusief tools/list en tools/call. Als u de toegang beperkt of toewijst per aanvraag, baseer dit dan op deze header.
• clientInfo wordt alleen verzonden op de initialize handshake. Als u de toegang per sessie beperkt bij het tot stand brengen van de verbinding, kunt u dit daar lezen, maar het wordt niet herhaald bij latere aanvragen.

Wat de identiteit wel en niet omvat

De identiteit benoemt alleen de software. Het is hetzelfde voor elke Cowork-gebruiker en -verbinding, en het draagt nooit een gebruikersidentiteit. De gebruikers-id blijft aanwezig in de autorisatiestroom die door de verificatieconfiguratie van de connector wordt gedefinieerd.

Omdat er geen kwalificatie per connector is, kunt u deze identiteit momenteel niet gebruiken om te bepalen welke connector een aanroep heeft gedaan of om een gepubliceerde Microsoft-invoegtoepassing te scheiden van een zijdelings geladen server die naar dezelfde URL wijst. Als u dat onderscheid nodig hebt, dwingt u dit af via de autorisatieconfiguratie van uw connector in plaats van via de clientidentiteit.

Veelgestelde vragen

Kan ik vaardigheden uit het M365-pakket gebruiken in Claude Code?

Yes. De vaardigheidsmappen bevatten standaard agentvaardigheden. Voer wiqd plugin export --format claude-plugin uit om de Claude Code-indeling te genereren, of kopieer de vaardigheidsmappen naar .claude/skills/ in elk willekeurig Claude Code-project.

Heb ik een externe connector nodig?

No. Pakketten met alleen vaardigheden werken goed voor op prompts gebaseerde werkstromen. Connectors zijn alleen nodig wanneer uw vaardigheid livegegevens uit een extern systeem vereist.

Hoe verschillen invoegtoepassingsvaardigheden van ingebouwde vaardigheden?

Plugin-vaardigheden verschijnen met de bron "package" in de API. Ze kunnen ingebouwde vaardigheden met dezelfde naam niet overschrijven. Pakketten die door beheer zijn geïmplementeerd tonen isAdminDeployed: true.

Kunnen IT-beheerders bepalen welke invoegtoepassingen beschikbaar zijn?

Yes. Standaard M365-beheerelementen zijn van toepassing: lijsten voor toestaan/blokkeren op tenantniveau, door beheerders beheerde implementaties en nalevingsbeleid.

Wat gebeurt er als een invoegtoepassing wordt ingetrokken?

Bij de volgende synchronisatiecyclus worden de vaardigheden en connectors uit dit pakket verwijderd uit de sessie van de gebruiker. Actieve gesprekken worden niet onderbroken, maar nieuwe sessies hebben niet de mogelijkheden van het pakket.

Wat is het maximum aantal skills per pakket?

Twintig (20) vaardigheden (per ASKILL-M002). Voor de connectoren geldt een limiet van 10 per pakket.

Kunnen hulpprogramma's voor vaardigheden verwijzen naar connectortools uit hetzelfde pakket?

Ja, en dat zouden ze ook moeten doen. Geef de hulpprogramma's expliciet een naam in uw SKILL.md werkstroom (bijvoorbeeld 'Gebruik het search_case_law hulpprogramma om...'). De agent verbindt ze tijdens runtime.

Kunnen de hulpprogramma's van mijn invoegtoepassing bestanden accepteren vanuit de werkruimte Cowork?

Yes. Declareer de hulpprogrammaparameter met contentEncoding: base64, en Cowork zet het werkruimtebestand van de gebruiker om naar base64-inhoud voordat u uw server aanroept. Het model passeert bestandspaden, geen bestandsinhoud, zodat grote bestanden de context van het model niet gebruiken. Meer informatie over declaraties en limieten vindt u in Bestanden accepteren vanuit de Cowork-werkruimte.

Hoe genereer ik een deterministische GUID voor mijn pakket?

wiqd plugin create genereert en legt de app-id vast. Het conversiescript gebruikt UUID v5 (op basis van SHA-1) van de naam van uw plugin, dus als u de conversie twee keer uitvoert, wordt dezelfde GUID geproduceerd. Gebruik voor handmatig verpakken een GUID-generator. Zorg ervoor dat deze over verschillende versies heen stabiel blijft.

Op welke manifestversie moet ik me richten?

Gebruik 1.29 als u met wiqd bouwt, want dat zet de versie voor u vast. Bij 1.29 bevatten de agentConnectors[]-vermeldingen alleen een URL en mcpToolDescription is optioneel. De handmatig opgestelde voorbeelden in dit artikel gebruiken 1.28, waarin mcpToolDescription vereist is en het bestand waarnaar het verwijst zich in het ZIP-bestand moet bevinden. atk import openplugin maakt gebruik van UUID v5 (SHA-1 gebaseerd) op basis van de naam van uw invoegtoepassing. Als u de import tweemaal uitvoert, levert dit dezelfde GUID op. Om je eigen waarde in te stellen, geef --app-id op. Gebruik voor handmatig verpakken een GUID-generator. Zorg ervoor dat deze over verschillende versies heen stabiel blijft.

Verwante gegevens

• Overzicht van Cowork
• Cowork gebruiken
• Cowork beheren voor uw organisatie
• Invoegtoepassingen voor Cowork beheren
• Naslaginformatie over de wiqd plugin-CLI