Bygg plugin-moduler for Copilot Cowork

Microsoft Copilot Cowork støtter utvidbarhet gjennom M365-apppakker – den samme distribusjonsmekanismen som brukes av Teams-apper, Copilot-agenter og Office-tillegg. Du kan utvide Cowork med:

• Ferdigheter: Spørsmålsbaserte arbeidsflyter som lærer Cowork ny domeneekspertise, for eksempel økonomisk analyse, juridiske undersøkelser eller HR-arbeidsflyter.
• Koblinger: Eksterne servere som gir Cowork tilgang til eksterne datakilder og API-er.

Begge er pakket sammen i en standard Microsoft 365-appakke og distribuert gjennom Microsoft 365 App Store.

Hva du bygger

Et Cowork-programtillegg er en .zip pakke som inneholder:

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

Ferdigheter bruker agentferdigheter åpen standard – samme format som støttes av Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie og 30+ andre KI-verktøy.

Velg ditt utgangspunkt

Importere et eksisterende programtillegg

Hvis du allerede har en Claude Code- eller Cursor plugin-modul med ferdigheter og MCP-servere, importerer CLI foratk Microsoft 365 Agents Toolkit den direkte. CLI kjører på Windows, macOS og Linux.

1. Installer CLI (krever versjon 1.1.12 eller nyere):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Bekreft versjonen:

   atk --version
   

3. Importer plugin-modulen:

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

Kommandoen leser plugin-ene (eller.cursor-plugin/plugin.json), , og skills/ katalogen, og stillas deretter et Agents Toolkit-prosjekt som inneholder appPackage/manifest.jsonferdighetene .claude-plugin/plugin.json dine og genererte .mcp.jsonikoner.

Du må inkludere --privacy-url og --terms-url fordi plugin-manifester ikke har tilsvarende felt, og Microsoft 365-manifestet krever begge.

Pakk resultatet til et opplastbart .zip:

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

Hva som importeres?

Hva konverteres ikke

Følgende funksjoner for Claude-plugin-modulen støttes ennå ikke i Microsoft 365-manifestet:

Alternativer for import

Automatisk gjenkjenning av godkjenningstype:

Hvis automatisk gjenkjenning ikke samsvarer med oppsettet, kan du bruke --default-auth-type til å overstyre den.

Eksportere tilbake til en katalog for programtillegg

Hvis du vil flytte et Agents Toolkit-prosjekt tilbake til en katalog for programtillegg, for eksempel hvis du vil holde et Claude Code-programtillegg og en Cowork-pakke synkronisert, kan du brukeatk export openplugin:

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

Eksport skriver en x-microsoft-365-agents-toolkit blokk inn i det genererte plugin.json. Denne blokken bærer manifestet id, utvikler-URL-er og koblingsinnstillinger, slik at en senere atk import openplugin rundreise uten behov --privacy-url eller --terms-url på nytt.

Eldre: PowerShell-konverteringsskript

Før atk støttet import av programtillegg, brukte konverteringen et PowerShell-skript bare for Windows, som fortsatt er tilgjengelig som konverteringsskript:

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

Bruk atk import openplugin i stedet. Den er på tvers av plattformer, støtter Cursor så vel som Claude Code-kilder, og kan eksportere tilbake til en plugin-katalog.

Bygg et programtillegg fra grunnen av

Følg disse trinnene for å opprette en plugin-pakke fra grunnen av, og start med den første ferdigheten din og bygg deg opp til en komplett, publiserbar pakke.

Trinn 1: Opprett din første kompetanse

En kompetanse er en mappe som inneholder en SKILL.md fil. Opprett følgende mappestruktur:

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

Skriv SKILL.md med YAML-frontmateriale og en Markdown-tekst:

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

Obligatoriske felt:

Navneregler (kebab-case): Bruk bare små alfanumeriske tegn og bindestreker. Ikke bruk etterfølgende bindestreker, og ikke bruk foranstilte eller etterfølgende bindestreker.

Trinn 2: Legge til referansemateriell (valgfritt)

For komplekse ferdigheter kan du holde hovedinnholdet SKILL.md lean og flytte detaljert innhold til underkataloger. Disse tilleggsfilene er hjelpefiler. Ferdigheten laster dem inn når det trengs.

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

Begrensninger for hjelpefiler

Hver ferdighet kan inneholde opptil 20 hjelpefiler (alle andre filer enn SKILL.md). Følgende begrensninger gjelder per ferdighet:

Regler for hjelpefil

Baner for følgefiler må følge disse reglene:

• Bruk bare relative baner (ingen absolutte baner)
• Ingen banetraversering (.. segmenter)
• Ingen omvendte skråstreker eller nullbyte i filnavn
• Ingen skjulte filer (navn som begynner med .)
• Ingen reserverte navn i Windows (CON, PRN, AUX, COM1NUL–COM9, LPT1–LPT9)
• Selve filen SKILL.md teller ikke som en hjelpefil
• Filnavn må bruke klarerte tegn: alfanumeriske tegn, bindestreker, understrekingstegn, prikker, mellomrom og !

For å holde kontekstvinduet effektivt, laster systemet ferdigheter i tre lag:

Referer eksplisitt til underkatalogene slik SKILL.md at agenten vet at de finnes:

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

Trinn 3: Legg til en kobling (valgfritt)

Hvis utvidelsen trenger tilgang til eksterne data, kan du legge til en ekstern MCP-server. Dette trinnet er valgfritt. Pakker med bare ferdigheter fungerer bra for spørsmålsbaserte arbeidsflyter.

Krav til koblinger

Retningslinjer for verktøyutforming

• Ett verktøy per handling for små API-er (færre enn 15 operasjoner): search_case_law, get_ruling, cite_precedent
• Søk + kjør etter store API-er (50+ operasjoner): search_actions + execute_action
• Beskrivende navn: get_bond_price ikke getData
• Rike inndataskjemaer: Inkluder en beskrivelse for hver parameter – dette er det agenten leser
• Strukturerte utdata: Returner JSON som agenten kan formatere for brukeren
• Filinndata: Hvis du vil godta en fil fra brukerens arbeidsområde, deklarerer du parameteren med contentEncoding: base64. Mer informasjon i Godta filer fra Cowork-arbeidsområdet.

Beskriv koblingsverktøyene (mcpToolDescription)

Hver remoteMcpServer kobling må inneholde et mcpToolDescription objekt. Den nestede egenskapen peker file til en JSON-fil med verktøybeskrivelse som du pakker i og .zip refererer til av en relativ bane fra pakkeroten. Hvis du utelater mcpToolDescription, avviser pakketjenesten opplastingen med en HTTP 400-feil:

Nødvendige egenskaper mangler fra objektet: mcpToolDescription.

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

Den refererte filen (for eksempel tools/contoso-legal-tools.json) beskriver verktøyene koblingen viser og må finnes i ZIP-pakken. Inkluder den sammen med mappen din manifest.jsonskills/ når du pakker plugin-modulen.

Godkjenningstyper som støttes

For OAuthPluginVault og ApiKeyPluginVault, peker referenceId til legitimasjon som er lagret i Microsoft Enterprise Token Store – hemmeligheter vises aldri i manifest- eller ferdighetsfiler. Verdien referenceId er registrerings-ID-en for OAuth-klienten som du oppretter når du registrerer en OAuth-klient med Agents Toolkit.

MCP-godkjenning

Hvis du vil bruke OAuth eller ApiKey for godkjenning, kan du se Konfigurer godkjenning for MCP- og API-plugin-moduler i agenter i Microsoft 365 Copilot for konfigurasjonsinformasjon.

Dynamic Client Registration

Hvis MCP-serveren din støtter Dynamic Client Registration (DCR), kan du utelate en konfigurasjon fra koblingsdefinisjonenauthentication, og Cowork oppretter automatisk en OAuth-klient på vegne av programtillegget.

Du kan utelate objektet authorization , men du må likevel ta med mcpToolDescription. Konfigurer nettadressen og verktøybeskrivelsen for MCP-serveren, så tar Cowork seg av OAuth-klienten:

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

Trinn 4: Opprette manifestet

Opprett manifest.json i pakkeroten:

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

Hvis du vil legge til en kobling, må du ta med 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"
          }
        }
      }
    }
  ]
}

Det skal være OAuth-registrerings-ID-en i koblingskonfigurasjonen referenceId , og mcpToolDescription.file må peke til en JSON-fil med verktøybeskrivelse som er inkludert i ZIP-pakken.

Trinn 5: Legge til ikoner

Opprett to PNG-ikoner:

Hvis du ikke har noen ikoner ennå, atk import openplugin genereres plassholdere med heldekkende farger. Bytt dem ut før innsending i butikk.

Trinn 6: Pakke

Opprett en ZIP-fil med alt innhold på rotnivå:

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

Hvis pakken inneholder en agentConnectors oppføring, inkluderer du JSON-filen for verktøybeskrivelse som mcpToolDescription.file. Pakker med bare ferdigheter trenger ikke en tools/ mappe.

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/

Bruke verktøysettet for Microsoft 365-agenter

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

Trinn 7: Test

Hvis du vil teste appen, kan du laste opp appakken til Teams som beskrevet i Last opp appen til Teams.

For personlig testing, installerer du appen direkte ved hjelp av kommandolinjegrensesnittet for Microsoft 365 Agents Toolkit:

1. Installer @microsoft/m365agentstoolkit-cli fra npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Kontroller installasjonen ved å kjøre:

   atk --version
   

3. Godkjenn med Microsoft 365-jobbkontoen:

   atk auth login
   

4. Logg på jobbkontoen din og installer agentpakken. Erstatt filbanen med plasseringen til ZIP-pakken:

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

   En vellykket installasjon returnerer utdata som inneholder en TitleId og AppId for kontoen din.

5. Lagre disse ID-ene for senere bruk når du oppdaterer eller avinstallerer.

Mer informasjon i kommandolinjegrensesnittet for Microsoft 365 Agents Toolkit.

Trinn 8: Publiser til leieren

1. Åpne administrasjonssenteret > for M365Behandle apper>Last opp egendefinert app.
2. Velg ellipseknappen (...) >Legg til agent.
3. Last opp .zip pakken.
4. Åpne Cowork>kilder &ferdighetsplugin-moduler>. Programtillegget vises i Discover-delen .

Trinn 9: Publiser til offentligheten

For plugin-moduler som er ment for offentlig distribusjon, kan du sende inn plugin-modulen til Microsoft 365 App Store via Partnersenter. Mer informasjon i Publiseringsagenter for Microsoft 365 Copilot.

Teste en kobling mot en lokal MCP-server

Koblinger mcpServerUrlkrever en HTTPS, så for å teste en server som kjører på maskinen, må du eksponere den over en offentlig HTTPS-nettadresse. Utviklertunneler har et relé som avslutter TLS for deg.

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

Feilsøking

Emballasjemønstre

Velg mønsteret som passer til utvidelsen:

Bare ferdigheter (ingen kobling)

Best for spørsmålsbaserte arbeidsflyter, dokumentanalyse og skrivehjelp.

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

Ferdigheter + ekstern kobling

Best for dataanalyse, API-integreringer og bedriftssystemer.

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

Bare tilkobling (ingen egendefinerte ferdigheter)

Bruk dette alternativet for datakilder som Cowork innebygde ferdigheter allerede kan bruke.

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

Importert Claude-kode eller markør-plugin

Bruk dette alternativet for eksisterende programtillegg fra andre KI-verktøy som er rettet mot Cowork.

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

Anbefalte fremgangsmåter for kompetanseredigering

Følg disse retningslinjene for å opprette ferdigheter som aktiveres pålitelig og gir konsekvente resultater.

Skrive effektive beskrivelser

Feltet description bestemmer når agenten aktiverer ferdigheten din. Vær spesifikk:

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

Skrive effektive arbeidsflyter

• Vær spesifikk i beskrivelsen. Inkluder utløseruttrykk: «Brukes når brukeren ber om å...» Denne beskrivelsen er hvordan agenten avgjør hvilken kompetanse som skal aktiveres.
• Struktur som en arbeidsflyt. Nummerer trinnene. Hvert trinn skal tilordnes til en konkret handling (lese en fil, kalle et verktøy, generere utdata).
• Definere utdataformat. Vise den nøyaktige tabell-, liste- eller dokumentstrukturen brukerne kan forvente. Denne definisjonen forbedrer konsistensen dramatisk.
• Referanseverktøy etter navn. Hvis ferdighetene dine avhenger av koblingsverktøy, kan du gi dem et navn: "Bruk verktøyet search_case_law til ..."
• Hold de viktigste SKILL.md slanke. Flytt detaljert referansemateriale til underkatalogen references/ . Kompetansegruppen bør være arbeidsflyten, ikke et leksikon.

Unngå vanlige feil

• Ikke bygg inn hemmeligheter i SKILL.md filer. Bruk agentConnectors med godkjenning for API-legitimasjon.
• Ikke duplisere innebygde ferdigheter. Kontroller den innebygde ferdighetslisten før du bygger.
• Ikke gjør ferdigheter for brede. "Gjør alt med juridiske dokumenter" er verre enn spesifikke ferdigheter for "kontraktsanalyse", "klausuluttrekking" og "juridisk forskning".
• Ikke hardkode filbaner eller systemkommandoer. Ferdigheter skal være flyttbare på tvers av miljøer.
• Ikke legg alt i SKILL.md. Hvis kroppen din overskrider ~3000 ord, flytter du detaljert innhold til references/.

Valideringsregler

Når du sender inn pakken din, validerer plattformen den på flere nivåer. Rett disse feilene før innsending for å unngå avvisning.

Validering på manifestnivå

Validering på pakkenivå

Validering av kobling

Validering av hjelpefiler

Portalen validerer følgefiler (referansemateriale, skript og andre filer sammen SKILL.mdmed ) på opplastings- og synkroniseringstidspunktet:

Kompatibilitet på tvers av plattformer

Ferdigheter bruker den åpne standarden Agentferdigheter. De samme SKILL.md filene fungerer på tvers av flere KI-verktøy:

Hvis du utvikler ferdigheter for både Claude Code og Cowork, starter du med Claude Code-plugin-strukturen – det er supersettet:

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)

Importer det deretter til et M365-prosjekt når du er klar til å publisere på Microsoft 365 App Store:

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

MCP-behandling av merknader og bekreftelser

Copilot Cowork leser standard MCP-objektet annotations på verktøy serveren returnerer fra tools/list, og bruker det til å avgjøre om et verktøykall trenger brukerbekreftelse og hvilken etikett som skal vises i ledeteksten.

Tilgjengelige felt

Regler for bekreftelse

Bekreftelse kreves hvis readOnlyHint == false eller destructiveHint == true.

Alle verktøy må ha sikkerhetsmerknader angitt. Verktøy uten merknader behandles som destruktive og krever bekreftelse. Mer informasjon i MCP-skjemareferansen.

MCP-eksempler

En destruktiv handling med en egendefinert etikett:

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

En trygg lesning som kjører automatisk:

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

Hva er tilgjengelig nå

• Microsoft-verktøy (Graph, Dataverse og andre) er underlagt den innebygde policyen til Cowork, uavhengig av merknader.
• For MCP-servere som ikke er fra Microsoft, rulles merknadsdrevet bekreftelse ut gradvis. Angivelse av hint nå er fremoverkompatibel, og bekreftelsesmeldinger vises etter hvert som utrullingen utvides uten at det kreves utviklerendringer.

Godta filer fra Cowork-arbeidsområdet

Et koblingsverktøy kan hente en fil fra brukerens Cowork-økt som inndata – et dokument brukeren har lagt ved, et e-postvedlegg som Cowork har lagret, eller en fil som et tidligere trinn har produsert. Deklarer parameteren med standard JSON Schema-nøkkelordcontentEncoding: base64, så håndterer Cowork resten. Ingen Microsoft-spesifikk skjemautvidelse kreves, og serverens API-overflate endres ikke.

Cowork løser arbeidsområdefilen og base64-koder den før du ringer serveren, slik at filbyte aldri angir agentens kontekst. Agenten ser og avgir bare filbaner for arbeidsområdet.

Deklarer en filparameter

En strengegenskap gjenkjennes contentEncoding: base64 som en inndata for filen:

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

En matrise av slike strenger gjenkjennes også, for verktøy som godtar flere filer:

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

Hva agenten ser

For filparametere som er deklarert på øverste nivå i inputSchema.properties, erstatter Cowork dem i det modellrettede skjemaet med én enkelt direct_attachment_file_paths matrise – den samme parameteren som Cowork innebygde verktøy bruker, slik at agenten allerede vet hvordan den skal fylle den ut. Skjemaet ovenfor presenteres for agenten som:

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

Hvis verktøyet deklarerer mer enn én filparameter på øverste nivå, skjules alle til den ene direct_attachment_file_paths matrisen. Ved anropstid vifter Cowork de løste filene tilbake til de opprinnelige parameternavnene i deklarasjonsrekkefølge.

Nestede filparametere

En filparameter som er nestet inne i et objekt eller en matrise med objekter, støttes også, og håndteres på en annen måte: I stedet for å skjules, skrives den på plass til en banestreng på sin egen plassering. Dette bevarer tilknytningen mellom en fil og dens sideordnede felt, for eksempel én kvittering per utgiftslinje:

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

Agenten fylles line_items[].receipt ut med en arbeidsområdebane, og Cowork bytter hver bane for base64-innhold på plass før anropet viderekobles.

Hekkingen krysses til en dybde på fire nivåer under toppen av inputSchema. $refPekere følges ikke – definer filparametere innebygd i stedet for bak .$ref

Hva serveren mottar

Serveren mottar en ordinær tools/call med de opprinnelige parameternavnene utfylt med base64-kodet innhold:

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

Serveren trenger ikke å vite at agenten brukte et banebasert grensesnitt, og verktøy som ikke deklarerer contentEncoding: base64 parametere, påvirkes ikke.

Grenser

Et kall som overskrider filantallet eller en størrelsesgrense, mislykkes med en verktøyfeil og når aldri serveren. Dimensjoner API-en og dens tidsavbrudd med 150 MB tak i tankene: base64 blåser opp nyttelasten med omtrent en tredjedel over raw-filstørrelsen, og det kodede innholdet sendes i JSON-RPC-forespørselsteksten.

Anbefalinger

• Beskriv parameteren for en menneskelig leser. Agenten bruker beskrivelsen til å bestemme hvilken fil som tilhører i hvilken parameter. Fungerer for eksempel "The signed contract PDF to analyze" bedre enn "file".
• Angi formatene du godtar i parameterbeskrivelsen. Cowork går gjennom det brukeren legger ved. Valider innholdstypen på din side, og returner en klar verktøyfeil hvis den ikke kan brukes.
• Angi merknader. Et verktøy som mottar en fil og handler på den, er vanligvis ikke skrivebeskyttet, så det ber om bekreftelse. Se behandling av MCP-merknader og bekreftelser.
• Behold filparametere på linjen. En parameter bak en $ref, eller nestet dypere enn fire nivåer, skrives ikke om. Serveren vil motta en banestreng der den forventer innhold.
• Deklarer maksimalt én matrisefilparameter per verktøy. Med to eller flere kan ikke Cowork se hvilken fil som tilhører i hvilken matrise, og kallet mislykkes med en verktøyfeil. Bruk én matrise, eller flere skalarparametere, eller en blanding av skalarer og én enkelt matrise.
• Forvent et nøyaktig antall skalarverktøy. Hvis verktøyet bare deklarerer skalarfilparametere, må antallet filer agenten passerer, samsvare med tallet som er deklarert. Merk valgfrie filparametere tydelig i beskrivelsene, slik at agenten ikke under- eller overleverer.

Identifiser Cowork-trafikk til serveren

Hvis MCP-serveren porterer verktøysynlighet etter klient, eller du vil tilskrive trafikken den mottar, kan du gjenkjenne forespørsler som kommer fra Cowork. Cowork presenterer en stabil programvareidentitet på to kanaler:

Samsvar med prefikset copilot-cowork

Samsvarer med prefiksetcopilot-cowork, uten skille mellom store og små bokstaver, på en av kanalene. Ikke samsvarer nøyaktig med strengen copilot-cowork/1.0 eller en bestemt clientInfo.version. Versjonen sporer klient-identitetskontrakten og forventes å endres; Et prefikssamsvar sørger for at porten fungerer på tvers av versjonsbump.

# Correct: case-insensitive prefix match
copilot-cowork

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

Velg riktig kanal for porten din

De to kanalene har forskjellige omfang, så velg den som samsvarer med hvordan serveren håndhever porten:

• Toppteksten User-Agent finnes på alle forespørsler, inkludert tools/list og tools/call. Hvis du gate eller attributter per forespørsel, angir du dette hodet.
• clientInfosendes bare ved håndtrykk.initialize Hvis du porterer per økt på tilkoblingstidspunktet, kan du lese det der, men det gjentas ikke ved senere forespørsler.

Hva identiteten inkluderer og ikke inkluderer

Bare navnet på identiteten av programvaren . Det er likt for alle Cowork-brukere og -tilkoblinger, og det bærer aldri brukeridentitet. Brukeridentiteten forblir i godkjenningsflyten som defineres i godkjenningskonfigurasjonen for koblingen.

Siden det ikke finnes noen kvalifikator per kobling, kan du for øyeblikket ikke bruke denne identiteten til å finne ut hvilken kobling som gjorde et kall, eller til å skille et publisert Microsoft-programtillegg fra en server som er installert direkte, peker på samme URL-adresse. Hvis du trenger denne distinksjonen, kan du håndheve den gjennom konvolutionens autorisasjonskonfigurasjon i stedet for klientidentiteten.

Vanlige spørsmål

Kan jeg bruke ferdigheter fra M365-pakken i Claude Code?

Ja. Kompetansemappene inneholder standard agentferdigheter. Kopier dem til .claude/skills/ i et hvilket som helst Claude Code-prosjekt, eller kjør atk export openplugin for å konvertere hele prosjektet tilbake til en Claude Code-plugin.

Trenger jeg en ekstern kontakt?

Nei. Pakker med bare ferdigheter fungerer bra for spørsmålsbaserte arbeidsflyter. Koblinger er bare nødvendig når ferdigheten krever direkte data fra et eksternt system.

Hvordan skiller plugin-ferdigheter seg fra innebygde ferdigheter?

Plugin-ferdigheter vises med kilde "package" i API-en. De kan ikke overstyre innebygde ferdigheter med samme navn. Admin-distribuerte pakker viser isAdminDeployed: true.

Kan IT-administratorer kontrollere hvilke programtillegg som er tilgjengelige?

Ja. Standard M365-administrasjonskontroller gjelder: tillatelses-/blokkeringslister på leiernivå, administratoradministrerte distribusjoner og samsvarspolicyer.

Hva skjer hvis et programtillegg tilbakekalles?

I den neste synkroniseringssyklusen fjernes ferdighetene og koblingene fra den pakken fra brukerens økt. Aktive samtaler blir ikke avbrutt, men nye økter har ikke pakkefunksjonalitet.

Hva er maksimalt antall ferdigheter per pakke?

Tjue (20) ferdigheter (per ASKILL-M002). For koblinger er grensen 10 per pakke.

Kan ferdigheter referere til koblingsverktøy fra samme pakke?

Ja, og det burde de. Gi verktøyene eksplisitt navn i SKILL.md arbeidsflyten (for eksempel Bruk search_case_law verktøyet til å ...). Agenten kobler dem til under kjøring.

Kan programtilleggets verktøy godta filer fra Cowork-arbeidsområdet?

Ja. Deklarer verktøyparameteren med contentEncoding: base64, så løser Cowork brukerens arbeidsområdefil til base64-innhold før serveren kalles. Modellen sender filbaner, ikke filinnhold, slik at store filer ikke bruker modellens kontekst. Hvis du vil ha deklarasjonsdetaljer og begrensninger, kan du finne ut mer i Godta filer fra Cowork-arbeidsområdet.

Hvordan genererer jeg en deterministisk GUID for pakken min?

atk import openplugin bruker UUID v5 (SHA-1-basert) fra plugin-navnet ditt. Hvis du kjører importen to ganger, får du samme GUID. Hvis du vil angi dine egne, sender du --app-id. For manuell emballasje, bruk en hvilken som helst GUID-generator. Sørg for å holde den stabil på tvers av versjoner.

Beslektet innhold

• Cowork oversikt
• Bruk Cowork
• Administrer Cowork for organisasjonen
• Administrer programtillegg for Cowork