Creare plug-in per Copilot Cowork

Microsoft Copilot Cowork supporta l'estendibilità tramite i pacchetti di app M365, lo stesso meccanismo di distribuzione usato dalle app di Teams, dagli agenti Copilot e dai componenti aggiuntivi di Office. Puoi estendere Cowork con:

• Competenze: flussi di lavoro basati su prompt che insegnano a Cowork nuove competenze specialistiche in nuovi domini, come analisi finanziaria, ricerca legale o flussi di lavoro delle risorse umane.
• Connettori: server remoti che consentono a Cowork di accedere a origini dati e API esterne.

Entrambi sono raggruppati in un pacchetto di app Microsoft 365 standard e distribuiti tramite Microsoft 365 App Store.

Importante

Barriere informative Microsoft Purview (IB) non è attualmente supportato per la gestione e la condivisione di plug-in o competenze. Nei tenant in cui IB è abilitato, i caricamenti di file di knowledge incorporati sono bloccati a livello di tenant. In questo modo si impedisce il caricamento o la pubblicazione dei plug-in e delle skill interessati.

Microsoft non crea né gestisce alcun indice persistente, grafo della conoscenza (incluso Microsoft Graph) o database che includa contenuto ISV, tramite ricerca per indicizzazione, scraping, raccolta, esportazione in blocco, inserimento o qualsiasi altro metodo (tramite API, server MCP o in altro modo). Microsoft potrebbe elaborare temporaneamente il contenuto ISV in base alle esigenze per rispondere alla query in tempo reale di un utente, ma non mantiene il contenuto ISV oltre la durata di tale sessione. Su richiesta scritta dell'ISV, Microsoft elimina qualsiasi contenuto ISV in suo possesso o controllo entro 10 giorni lavorativi e certifica tale eliminazione per iscritto. Per altre informazioni, vedere Protezione dei dati aziendali in Microsoft Copilot e Microsoft Copilot Chat.

Cosa costruirai

Un plugin di Cowork è un .zip pacchetto contenente:

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

Le competenze usano lo standard aperto Agent Skills, lo stesso formato supportato da Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie e altri 30 strumenti di intelligenza artificiale.

Scegliere il punto di partenza

Crea il tuo plug-in con la wiqd CLI. L'interfaccia della riga di comando esegue lo scaffolding del pacchetto e mantiene manifest.json e le cartelle delle tue competenze sincronizzati. Esegue inoltre le regole di convalida della piattaforma prima del caricamento, quindi effettua il provisioning e condivide il risultato. L'interfaccia della riga di comando è in anteprima, quindi i comandi e l'output generato possono cambiare prima della disponibilità generale. Tutto ciò che genera è un semplice pacchetto dell'app Microsoft 365, quindi è comunque possibile aprire, modificare e gestire direttamente il versioning dei file.

Assembla il pacchetto manualmente solo quando non è possibile installare gli strumenti o quando si crea una pipeline di packaging personalizzata. In tal caso, il riferimento al formato del pacchetto in questo articolo è ciò che serve: descrive esattamente ciò che wiqd produce.

Punto di partenza	Fai questo	Tempo per il primo pacchetto
Sto iniziando da zero	Crea un plugin con wiqd	circa 10 minuti
Ho un plug-in di Claude Code esistente	Convertilo	circa 5 minuti
Non riesco a installare gli strumenti o sto scrivendo uno script per il mio sistema di packaging	Assemblare un pacchetto di installazione a mano	circa 30 minuti

Crea un plugin con wiqd

L'interfaccia della riga di comando di wiqd esegue lo stesso ciclo di vita che altrimenti esegui manualmente: creazione, aggiunta di funzionalità, convalida, provisioning, creazione di pacchetti e condivisione. Il pacchetto che produce soddisfa già le regole di convalida descritte in questo articolo.

Passaggio 1: Installare wiqd e accedere

Installare l'interfaccia della riga di comando di wiqd seguendo la guida all'installazione di wiqd, che copre Windows, macOS e Linux. Quindi accedere al tenant Microsoft 365 su cui si sta sviluppando, perché sia il provisioning che la condivisione coinvolgono il tenant:

wiqd auth login --interactive

Il programma di installazione registra anche un plugin CLI di GitHub Copilot, in modo da poter gestire lo stesso ciclo di vita tramite conversazione. Ad esempio, è possibile pronunciare Crea un plug-in autonomo denominato Triage Helper o Convalida il mio plug-in. Il percorso di conversazione esegue gli stessi comandi di questa sezione. Usa i comandi direttamente quando stai scrivendo uno script per una pipeline o desideri un'automazione riproducibile e non interattiva.

Passaggio 2: eseguire lo scaffolding del plug-in e aggiungere funzionalità

Crea il contenitore del plug-in, quindi aggiungi tutte le funzionalità di cui hai bisogno, in qualsiasi combinazione:

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 esegue lo scaffolding di appPackage/skills/contract-analysis/SKILL.md e lo registra in agentSkills[]. add connector scrive la agentConnectors[] voce. Entrambi i comandi applicano i limiti di denominazione e di dimensione della piattaforma prima di scrivere, quindi una discordanza del nome della cartella o un nome id di lunghezza eccessiva non raggiunge mai il manifest.

Scrivi la logica della competenza nel SKILL.md generato. I limiti per i campi del frontmatter, il modello a caricamento progressivo e i file complementari sono gli stessi descritti nel Passaggio 1: Creare la prima skill e nel Passaggio 2: Aggiungere materiale di riferimento (facoltativo).

Importante

wiqd plugin create blocca il pacchetto su manifestVersion: "1.29", mentre gli esempi creati a mano in questo articolo usano 1.28. La differenza è importante per i connettori. Al punto 1.28, mcpToolDescription è obbligatorio e il file denominato deve essere nello stato ZIP. A 1.29, agentConnectors[] le voci sono solo URL ed mcpToolDescription è facoltativo, quindi un pacchetto generato da wiqd non incontra mai l'errore di caricamento. WIQD non esegue ancora lo scaffolding dell'autenticazione del connettore, ma configurala direttamente come descritto in Tipi di autenticazione supportati.

Passaggio 3: convalidare durante la compilazione

Convalidare continuamente invece di assemblare un pacchetto e sperare che il caricamento passi:

wiqd plugin validate
wiqd plugin validate --mode deep

validate è il controllo statico offline sulla superfice dell'agente dichiarativo. Un plug-in di sole competenze o un plug-in solo connettore lo passa senza nulla da controllare, il che è previsto: è un controllo per il ciclo di build, non la copertura completa. validate --mode deep impacchetta prima il plug-in, quindi convalida il file compilato .zip rispetto alla stessa libreria di convalida dell'app utilizzata dal caricamento. È qui che emergono i codici ASKILL e le regole dei connettori.

Passaggio 4: Effettuare il provisioning, creare pacchetti e condividere

Eseguire questi tre comandi nell'ordine:

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

Eseguire provision per primo perché scrive il file di ambiente da cui package e share dipendono. Usare --scope users per condividere con le persone elencate o --scope tenant con tutti gli utenti dell'organizzazione. In entrambi i casi, il plug-in viene visualizzato in Condivisi con me in Cowork>Sources & Skills>Plugins. Per elencarlo invece nella sezione Discover, un amministratore carica il pacchetto. Per altre informazioni, vedere Passaggio 8: pubblicare nel tenant. Per rimuovere ciò che provision ha creato, esegui wiqd plugin delete --env local --yes.

L'invio allo store pubblico è ancora un processo manuale nel Centro per i partner. Per altre informazioni, vedere Passaggio 9: pubblicare nel pubblico.

Portare un plug-in a un altro host

Per utilizzare le tue competenze in Claude Code, Cursor o qualsiasi altro host di Agent Skills, esporta il progetto anziché copiare le cartelle a mano:

wiqd plugin export --format claude-plugin

export si imposta in modo predefinito su --format open-plugin e accetta anche cursor-plugin. Scrive una directory non compressa in <path>/export/<format>.

Importare un plug-in esistente

Se hai già un plug-in Claude Code con skill e server MCP, hai due percorsi di conversione. Il percorso scelto dipende dal fatto che si preveda di continuare a sviluppare il plug-in o di distribuire semplicemente ciò che si ha.

Goal	Utilizza
Continua a sviluppare, convalidare e distribuire il plug-in per Microsoft 365	wiqd plugin import
Produci subito un file .zip pubblicabile da un plugin Claude esistente	Lo script di conversione

Importare con wiqd

wiqd plugin import riconosce una sorgente Apri plug-in, Plug-in Claude o Plug-in cursore e produce un progetto di plug-in wiqd da esso. Il plug-in importato si unisce allo stesso ciclo di vita di quello creato con wiqd plugin create:

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

--privacy-url e --terms-url sono necessari solo alla prima importazione di un plug-in. Se l'origine proviene da un precedente wiqd plugin export, i metadati di andata e ritorno li contengono già.

Importante

Un progetto importato supporta solo la parte di sola lettura del ciclo di vita—wiqd plugin validate, show, e list. Non può ancora essere creato un pacchetto, effettuato il provisioning o condiviso, perché l'importazione non esegue lo scaffolding dei file di distribuzione locali necessari a questi passaggi. Questo è un problema monitorato. Per lo stato corrente, controllare il riferimento della CLI di wiqd. Se oggi hai bisogno di un pacchetto pubblicabile, usa lo script di conversione.

Converti con lo script di conversione

Lo script di conversione traduce un plug-in Claude direttamente in un pacchetto M365 pubblicabile:

1. Installare la CLI (richiede la versione 1.1.12 o successiva):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Verificare la versione:

   atk --version
   

3. Importa il tuo plugin:

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

Il comando legge la directory .claude-plugin/plugin.json del plug-in (o .cursor-plugin/plugin.json), .mcp.json e skills/ , quindi esegue lo scaffolding di un progetto Agents Toolkit contenente appPackage/manifest.json, le tue competenze e le icone generate.

È necessario includere --privacy-url e --terms-url perché i manifesti dei plug-in non hanno campi equivalenti e il manifesto di Microsoft 365 richiede entrambi.

Annotazioni

atk import openplugin individua il manifesto di un plug-in in una directory il cui nome inizia con un punto—.claude-plugin/plugin.json, .cursor-plugin/plugin.json o .plugin/plugin.json—accanto a un .mcp.json. La specifica Agent Plugins 1.0.0 colloca il manifesto in plugin.json a livello superiore e la configurazione MCP in mcp.json. Per importare un plug-in che segue il layout 1.0.0, sposta il suo manifesto .plugin/plugin.json e rinominalo mcp.json in .mcp.json.

Impacchetta il risultato in un file caricabile .zip:

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

Annotazioni

atk import openplugin genera un manifesto devPreview. Gli esempi di manifesto altrove in questo articolo hanno come target lo schema v1.28. Se si pubblica tramite un canale che richiede la versione 1.28, aggiornare manifestVersion e $schema nella finestra appPackage/manifest.json generata.

Cosa viene importato

Artefatto plug-in	Equivalente a M365	Note
.claude-plugin/plugin.json	manifest.json	Nome, descrizione e campi sviluppatore mappati; GUID generato automaticamente (UUID deterministico v5)
skills/*/SKILL.md	voci agentSkills[] + cartella skills/	Copiato testualmente - formato identico
server .mcp.json	agentConnectors[] voci	Rilevamento automatico di URL e tipo di autenticazione
color.png / outline.png	Icone nel pacchetto	Utilizzato se presente; vengono generati segnaposto se mancanti

Importante

Per ogni connettore importato da .mcp.json, il authorization.referenceId generato è un segnaposto derivato dal plug-in e dal nome del server. Prima di pubblicarlo, sostituiscilo con l'ID di registrazione del client OAuth effettivo. Per altre informazioni, vedere Tipi di autenticazione supportati.

Elementi che non vengono convertiti

Le funzionalità del plug-in di Claude seguenti non sono ancora supportate nel manifesto di Microsoft 365:

Funzionalità del plug-in Claude	Status
commands/ (comandi barra)	Non ancora supportato
agents/ (subagenti)	Non ancora supportato
hooks/ (gestori eventi)	Non ancora supportato
settings.json	Non applicabile
bin/ (eseguibili)	Non applicabile

Opzioni di importazione

Option	Description
--path, -p	Required. Directory del plug-in contenente .claude-plugin/plugin.json, .cursor-plugin/plugin.json, o .plugin/plugin.json
--output, -o	Cartella del progetto di destinazione (impostazione predefinita: ./<plugin-name>)
--privacy-url	developer.privacyUrl per il manifesto generato
--terms-url	developer.termsOfUseUrl per il manifesto generato
--website-url	developer.websiteUrl. Se non disponibile, usa homepage, quindi author.url
--app-id	Eseguire l'override dell'UUID deterministico v5 generato per l'id del manifest
--default-auth-type	Auto (predefinito), None, OAuthPluginVault, o ApiKeyPluginVault

Rilevamento automatico del tipo di autenticazione:

Source	Tipo di autenticazione predefinito	Reason
URL HTTPS esterni	OAuthPluginVault	La maggior parte delle API remote richiede l'autenticazione
localhost e URL non-HTTPS	None	Server di sviluppo locali

Se il rilevamento automatico non corrisponde alla configurazione, usa --default-auth-type per sovrascriverlo.

Esportare di nuovo in una directory di plugin

Per spostare un progetto Agents Toolkit in una directory di plug-in, ad esempio per mantenere sincronizzati un plug-in Claude Code e un pacchetto Cowork, utilizza:atk export openplugin

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

Option	Description
--path, -p	Required. Cartella del progetto Agents Toolkit contenente appPackage/manifest.json
--output, -o	Directory del plug-in di destinazione (impostazione predefinita: ./<plugin-name>-openplugin)
--manifest-kind	open-plugin (impostazione predefinita, scrive .plugin/plugin.json), claude-plugin, o cursor-plugin

Export scrive un blocco x-microsoft-365-agents-toolkit nel file plugin.json generato. Tale blocco contiene il manifesto id, gli URL per sviluppatori e le impostazioni del connettore, quindi un successivo atk import openplugin esegue round trip senza bisogno di --privacy-url o --terms-url di nuovo.

Annotazioni

Il blocco x-microsoft-365-agents-toolkit è specifico di Agents Toolkit e il tipo predefinito open-plugin scrive il manifesto in .plugin/plugin.json. Agent Plugins 1.0.0 utilizza un livello plugin.json principale e trasporta i dati specifici del client sotto una chiave extensions con uno spazio dei nomi di dominio inverso, quindi altri client ignorano questo blocco anziché agire su di esso. Quando l'obiettivo è Codice Claude o Cursore, usa --manifest-kind claude-plugin o cursor-plugin.

Legacy: script di conversione di PowerShell

Prima che atk supportasse l'importazione di plug-in, la conversione usava uno script PowerShell solo per Windows, che rimane disponibile come script di conversione:

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

Utilizzare invece atk import openplugin. È multipiattaforma, supporta i sorgenti di Cursor e di Claude Code e può esportare nuovamente in una directory di plugin.

Assemblare un pacchetto di installazione a mano

Questa sezione è il riferimento al formato del pacchetto: descrive esattamente cosa genera Build a plugin with wiqd , campo per campo. Segui questa procedura dall'inizio alla fine quando non puoi installare gli strumenti necessari o stai creando la tua pipeline di pacchettizzazione. Usalo come riferimento quando devi comprendere o fare il debug di un pacchetto generato.

Passaggio 1: creare la prima competenza

Una competenza è una cartella contenente un file SKILL.md. Crea la seguente struttura di cartelle:

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

Scrivere SKILL.md con la parte introduttiva YAML e un corpo 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 |

campi frontmatter SKILL.md

Campi obbligatori:

Field	Constraints	Description
name	1-64 caratteri, kebab-case	Identificatore di competenza: deve corrispondere esattamente al nome della cartella
description	1-1024 caratteri	Quando usare questa abilità - includi frasi di attivazione

Importante

• Il nome della cartella deve corrispondere al campo name in primo piano. Questa mancata corrispondenza è la causa più comune di errori della competenza.
• I campi dell'elenco description dei plug-in non dovrebbero includere inviti all'azione che indirizzano gli utenti a mercati esterni per acquistare abbonamenti.

Percorso della cartella	name Campo	Valido?	Perché
skills/contract-analysis/SKILL.md	contract-analysis	Yes	La cartella e il nome corrispondono
skills/contract-analysis/SKILL.md	ContractAnalysis	No	Il nome usa PascalCase invece di corrispondere alla cartella
skills/my-skill/SKILL.md	contract-analysis	No	La cartella è my-skill ma il nome è contract-analysis

Regole di denominazione (kebab-case): Usare solo caratteri alfanumerici minuscoli e trattini. Non usare trattini consecutivi e non usare trattini iniziali o finali.

Example	Valido?	Issue
bond-relative-value	Yes	Minuscolo con trattini
fx-carry-trade	Yes	Minuscole con trattini
email	Yes	Parola singola, senza trattini necessari
Bond_Relative_Value	No	Caratteri di sottolineatura e lettere maiuscole
--my-skill--	No	Trattini iniziali e finali
my--skill	No	Trattini consecutivi

Passaggio 2: Aggiungi materiali di riferimento (facoltativo)

Per competenze complesse, mantieni l'elemento principale SKILL.md essenziale e sposta i contenuti dettagliati nelle sottodirectory. Questi file aggiuntivi sono file complementari. L'abilità li carica quando necessario.

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

Limiti dei file associati

Ogni abilità può includere fino a 20 file complementari (qualsiasi file diverso da SKILL.md). Per ogni competenza, si applicano i limiti seguenti:

Limit	Value
Numero massimo dei file associati	20
Dimensioni massime per file associato	5 Megabyte
Dimensione totale massima associato	10 MB
Timeout download (tutti gli associati)	15 secondi

Regole del file di accompagnamento

I percorsi di file associati devono seguire queste regole:

• Usare solo percorsi relativi (non percorsi assoluti).
• Nessun attraversamento percorso (segmenti ..).
• Nessun backslash o byte null nei nomi di file.
• Nessun file nascosto (nomi che iniziano con .).
• Nessun nome riservato di Windows (CON, PRN, AUX, COM1, NUL–COM9, LPT9–LPT1).
• Il file SKILL.md in sé non viene conteggiato come file complementare.
• I nomi file devono usare caratteri sicuri: alfanumerici, trattini, caratteri di sottolineatura, punti, spazi e !.

Per mantenere efficiente la finestra di contesto, il sistema carica le competenze in tre livelli:

Livello	Quando caricato	Dimensioni obiettivo
Frontespizio (name + description)	Sempre - all'avvio	~100 token
SKILL.md corpo	Quando la competenza si attiva	Meno di 5.000 token (1.500-2.000 parole)
Riferimenti (references/)	Su richiesta dell'agente	Unlimited
Script (scripts/)	Eseguito, non caricato nel contesto	N/A

Fare riferimento alle directory secondarie in modo esplicito in SKILL.md in modo che l'agente sappia che esistono:

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

Passaggio 3: Aggiungere un connettore (facoltativo)

Se l'estensione deve accedere a dati esterni, aggiungi un server MCP remoto. Questo passaggio è facoltativo. I pacchetti di sole competenze funzionano bene per i flussi di lavoro basati su prompt.

Tip

Se il server controlla la visibilità dello strumento per client o classifica il traffico in entrata, passare a Identifica il traffico di Cowork verso il server per informazioni sull'identità client presentata da Cowork.

Annotazioni

I plug-in personalizzati non sono supportati in Cowork su dispositivi mobili.

Requisiti del connettore

Requirement	Details
Trasporto	HTTP streamable (HTTPS obbligatorio, TLS 1.2+)
Protocol	Formato messaggio JSON-RPC 2.0
Individuazione degli strumenti	Supporto tools/list per l'individuazione dinamica (scelta consigliata)
Esecuzione dello strumento	Supporto tools/call per l'invocazione
Availability	Tempo di attività del 99,9% SLA consigliato per le app pubblicate nello Store
Ora di risposta	Meno di 30 secondi per chiamata utensile

Linee guida per la progettazione degli strumenti

• Uno strumento per azione per API di piccole dimensioni (meno di 15 operazioni): search_case_law, get_ruling, cite_precedent
• Cerca + esegui per API di grandi dimensioni (50+ operazioni): search_actions + execute_action
• Nomi descrittivi: get_bond_price non getData
• Schemi di input avanzati: includi una descrizione per ogni parametro: questo è ciò che legge l'agente
• Output strutturato: restituisci JSON che l'agente può formattare per l'utente
• Input file: Per accettare un file dall'area di lavoro dell'utente, dichiarare il parametro con contentEncoding: base64. Per altre informazioni, vedere Accettare file dall'area di lavoro Cowork.

Descrivere gli strumenti del connettore (mcpToolDescription)

Un remoteMcpServer connettore può facoltativamente includere un mcpToolDescription oggetto. Quando viene fornita, la proprietà annidata file punta a un file JSON di descrizione dello strumento che viene inserito all’interno del tuo .zip e a cui si fa riferimento tramite un percorso relativo dalla radice del pacchetto. Cowork rileva gli strumenti in modo dinamico dal server MCP e non usa questo file, anche quando è presente.

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

Se si include mcpToolDescription, il file a cui si fa riferimento (ad esempio, tools/contoso-legal-tools.json) descrive gli strumenti resi disponibili dal connettore e deve essere presente nel pacchetto ZIP. Includilo insieme alla cartella manifest.json e skills/ quando crei il pacchetto del plug-in.

Tip

Questo requisito si applica alla versione 1.28 del manifest. I pacchetti creati da wiqd plugin create hanno come target la versione 1.29, in cui le voci di agentConnectors[] contengono solo URL, mcpToolDescription è facoltativo e non c'è alcun file di descrizione dello strumento da dimenticare.

Tipi di autenticazione supportati

Tipo di autenticazione	Quando utilizzare	Esperienza utente
None	API pubbliche o anonime, servizi interni	Trasparente: nessuna richiesta di autenticazione
OAuthPluginVault	API OAuth 2.0 (consigliate per la produzione)	L'utente completa il consenso OAuth una sola volta
ApiKeyPluginVault	Servizi basati su chiavi API	L'utente fornisce la chiave una volta

Annotazioni

• Il supporto per l'autenticazione con chiave API non è ancora disponibile in Cowork.
• Se il server MCP richiede una chiave API, utilizzare OAuthPluginVault invece o Dynamic Client Registration o esporre un endpoint che accetti None.

Per OAuthPluginVault e ApiKeyPluginVault, referenceId punta alle credenziali archiviate nell'archivio dei token di Microsoft Enterprise - i segreti non vengono mai visualizzati nel manifesto o nei file di competenza. Il valore referenceId è l'ID di registrazione del client OAuth creato quando si registra un client OAuth con Agents Toolkit.

Importante

Quando registri il client OAuth, imposta l'utilizzo per organizzazione su Qualsiasi organizzazione Microsoft 365 per assicurarti che il plug-in funzioni tra tenant.

Autenticazione MCP

Per usare OAuth o ApiKey per l'autenticazione, consulta Configurare l'autenticazione per i plug-in MCP e API negli agenti in Microsoft 365 Copilot per i dettagli sull'installazione e la configurazione.

Registrazione dinamica del client

Se il server MCP supporta Dynamic Client Registration (DCR), è possibile omettere una configurazione authentication dalla definizione del connettore e Cowork crea automaticamente un client OAuth per conto del plug-in.

Annotazioni

L'omissione della authentication configurazione è supportata solo in Cowork. Non è supportato in Copilot Chat. Se il plug-in deve funzionare anche in Copilot Chat, configurare OAuthPluginVault l'autenticazione come descritto in Tipi di autenticazione supportati.

È possibile omettere completamente l'oggetto authorization . Configura l'URL del server MCP e Cowork si occuperà del client OAuth:

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

Passaggio 4: creare il manifesto

Crea manifest.json nella radice del pacchetto. Nell'esempio viene utilizzata la versione manifest 1.28; wiqd plugin create usa invece la versione 1.29, in cui le voci del connettore sono solo URL.

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

Per aggiungere un connettore, includere 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"
          }
        }
      }
    }
  ]
}

Nella configurazione del connettore, referenceId deve essere l'ID di registrazione OAuth. Se includi mcpToolDescription, file è necessario che punti a un file JSON tool-description incluso nel pacchetto ZIP.

Importante

Lo schema del manifesto v1.28 è rigoroso: imposta additionalProperties: false nella radice, quindi qualsiasi campo non definito nello schema viene rifiutato. I campi validi nei manifesti standard dell'app Teams, ad esempio packageName, causano il mancato caricamento con un errore simile a Property 'packageName' has not been defined and the schema does not allow additional properties.. Includi solo i campi visualizzati qui.

Passaggio 5: Aggiungere icone

Crea due icone in formato PNG:

Icon	Size	Purpose
color.png	192×192 px	Icona dell'app a colori visualizzata nello Store e nell'elenco delle app
outline.png	32×32 px	Icona contorno monocolore per visualizzazioni compatte

Se non hai ancora le icone, atk import openplugin genera segnaposto a tinta unita. Sostituirli prima dell'invio allo Store.

Passaggio 6: pacchetto

Crea un file ZIP con tutto il contenuto a livello radice. (wiqd plugin package produce la stessa struttura dopo 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

Se un connettore include mcpToolDescription, includere il file JSON tool-description a cui fa riferimento. I pacchetti che non usano mcpToolDescription, inclusi i pacchetti di sole competenze, non hanno bisogno di una tools/ cartella.

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/

Utilizzo di Microsoft 365 Agents Toolkit

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

Passaggio 7: eseguire il test

Per testare l'app, caricare il pacchetto dell'app in Teams come descritto in Caricare l'app in Teams.

Se hai creato il plugin con wiqd, esegui invece wiqd plugin provision: registrerà il plugin con il tuo tenant per te. Per il test personale di un pacchetto assemblato a mano, eseguire il sideload dell'app usando l'interfaccia a riga di comando di Microsoft 365 Agents Toolkit:

1. Installazione di @microsoft/m365agentstoolkit-cli da npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Verificare l'installazione eseguendo:

   atk --version
   

3. Autenticarsi con l'account aziendale Microsoft 365:

   atk auth login
   

4. Accedi all'account aziendale e installa il pacchetto dell'agente. Sostituire il percorso del file con il percorso del pacchetto ZIP:

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

   Se l'installazione riesce, viene restituito un output che include un TitleId e AppId per l'account.

5. Salva questi ID per utilizzarli in seguito quando aggiorni o disinstalli.

Per altre informazioni, vedi l'interfaccia della riga di comando di Microsoft 365 Agents Toolkit.

Passaggio 8: pubblicare nel tuo tenant

Caricare il pacchetto nell'interfaccia di amministrazione per elencare il plug-in nella sezione Discover, dove può essere trovato da tutti gli utenti dell'organizzazione:

1. Aprire l'interfaccia di amministrazione M365>Gestisci app>Carica app personalizzata.
2. Seleziona il pulsante con i puntini di sospensione (...) >quindi Aggiungi agente.
3. Caricare il .zip pacchetto.
4. Apri Cowork>Origini & Competenze>Plugin. Il tuo plugin appare nella sezione Discover.

wiqd plugin share inserisce il plug-in in Condivisi con l'utente corrente anziché in Scopri. Usalo per i test e per l'implementazione mirata a utenti specifici. Il caricamento nell'interfaccia di amministrazione è ciò che consente di elencare un plug-in per il rilevamento.

Passaggio 9: Pubblicare al pubblico

Per i plug-in destinati alla distribuzione pubblica, inviare il plug-in all'App Store di Microsoft 365 tramite il Centro per i partner. Altre informazioni in Pubblica agenti per Microsoft 365 Copilot.

Testa un connettore con un server MCP locale

I connettori richiedono un mcpServerUrl HTTPS. Per testare un server in esecuzione sul tuo computer, è necessario esporlo tramite un URL HTTPS pubblico. Dev tunnels forniscono un relay che termina TLS per te.

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

Importante

Usare --protocol http, non https. Il flag --protocol descrive il servizio locale verso cui il tunnel inoltra il traffico, non l'URL del tunnel pubblico. La maggior parte dei server MCP locali parla HTTP semplice, quindi se si imposta --protocol https mentre il server serve HTTP, ogni richiesta attraverso il tunnel restituisce un 502 errore. Il relay termina TLS e espone l'URL pubblico tramite HTTPS indipendentemente da questo flag.

Troubleshooting

Sintomo	Cause	Correzione
Ogni richiesta instradata tramite tunnel restituisce 502 e il server locale usa HTTP	devtunnel port create è stato eseguito con --protocol https	Ricrea la porta con --protocol http
Le richieste instradate tramite tunnel restituiscono 502 su macOS anche se il server locale è in esecuzione	Il server è associato a 0.0.0.0 (solo IPv4), ma il tunnel contatta localhost, che si risolve prima in ::1 (IPv6)	Associare il server a :: in modo che accetti entrambe le connessioni IPv4 e IPv6
Il caricamento non va a buon fine con Property '<field>' has not been defined and the schema does not allow additional properties	Il manifesto include un campo che lo schema v1.28 non consente (ad esempio, packageName)	Rimuovere il campo; Lo schema v1.28 usa additionalProperties: false

Schemi di imballaggio

Scegli lo schema più adatto alla tua estensione:

Solo competenze (nessun connettore)

Ideale per flussi di lavoro basati su prompt, analisi dei documenti e assistenza alla scrittura.

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

Competenze + connettore remoto

Ideale per l'analisi dei dati, le integrazioni API e i sistemi aziendali.

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

Solo connettore (nessuna competenza personalizzata)

Usa questa opzione per le origini dati che le skill integrate di Cowork possono già utilizzare.

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

Plugin importato Claude Code o Cursor

Usa questa opzione per i plug-in esistenti dell'ecosistema Claude rivolti a Cowork. Per continuare a sviluppare il plugin per Microsoft 365, importalo:

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

Per produrre uno .zip pubblicabile dal plug-in così com'è oggi, usa lo script di conversione:

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

Procedure consigliate per la creazione delle competenze

Segui queste linee guida per creare skill che si attivano in modo affidabile e producono risultati coerenti.

Scrivi descrizioni efficaci

Il campo description determina quando l'agente attiva la tua competenza. Sii specifico:

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

Scrivere flussi di lavoro efficaci

• Sii specifico nella descrizione. Includi frasi trigger: "Usa quando l'utente chiede di..." Questa descrizione è il modo in cui l'agente decide quale abilità attivare.
• Struttura come flusso di lavoro. Numerare i passaggi. Ogni passaggio deve corrispondere a un'azione concreta (leggere un file, chiamare uno strumento, generare output).
• Definire il formato di output. Mostra l'esatta struttura di tabella, elenco o documento che gli utenti si devono aspettare. Questa definizione migliora notevolmente la coerenza.
• Strumenti di riferimento per nome. Se la tua competenza dipende dagli strumenti del connettore, indicali esplicitamente: "Usa lo strumento search_case_law per..."
• Mantenere lo SKILL.md principale snello. Spostare il materiale di riferimento dettagliato nella references/ sottodirectory. Il corpo dello skill dovrebbe essere il flusso di lavoro, non un'enciclopedia.

Evitare errori comuni

• Non incorporare segreti nei file SKILL.md. Usa agentConnectors per l'autenticazione delle credenziali API.
• Non duplicare le competenze predefinite. Controlla l'elenco integrato delle competenze prima di iniziare a creare.
• Non rendere le competenze troppo ampie. "Saper fare tutto con i documenti legali" è peggio che avere competenze specifiche per "analisi del contratto", "estrazione di clausole" e "ricerca legale".
• Non inserire direttamente nel codice i percorsi di file o i comandi di sistema. Le competenze devono essere trasferibili tra gli ambienti.
• Non mettere tutto in SKILL.md. Se il corpo supera ~3.000 parole, spostare il contenuto dettagliato in references/.

Regole di convalida

Quando invii il pacchetto, la piattaforma lo convalida a più livelli. Correggi questi errori prima dell'invio per evitare il rigetto.

Per individuarli durante la compilazione anziché al momento del caricamento, eseguire wiqd plugin validate --mode deep. Questo comando crea il pacchetto del plugin ed esegue localmente queste stesse regole. Scopri di più in Fase 3: convalida durante la compilazione.

Convalida a livello del manifesto

Code	Rule	Severity
ASKILL-M001	folder è obbligatorio su ogni voce agentSkills	Error
ASKILL-M002	agentSkills L'array può contenere fino a 20 elementi	Error
ASKILL-M003	folder Il percorso può contenere fino a 256 caratteri	Error

Convalida a livello di pacchetto

Code	Rule	Soluzione comune	Severity
ASKILL-P001	La cartella a cui fa riferimento il manifesto esiste nel file ZIP	Controllare la struttura ZIP	Error
ASKILL-P002	La cartella contiene un file SKILL.md	Aggiungi il mancante SKILL.md	Error
ASKILL-P003	SKILL.md ha un frontmatter YAML valido tra i delimitatori ---	Correggere la sintassi YAML	Error
ASKILL-P004	Il frontmatter anteriore include il campo name	Aggiungi name: al frontmatter	Error
ASKILL-P005	Il frontmatter anteriore include il campo description	Aggiungi description: al frontmatter	Error
ASKILL-P006	name Corrisponde al nome della cartella (ultimo segmento di percorso)	Rinominare la cartella o correggere name:	Error
ASKILL-P007	name è kebab-case	Utilizzare my-skill non MySkill o my_skill	Error
ASKILL-P008	Nessun valore duplicato folder nell'array	Rimuovere duplicati	Error

Convalida del connettore

Rule	Severity
Ogni connettore richiede un id e un displayName	Error
Tutti i valori id del connettore devono essere univoci all'interno del manifesto	Error
Esattamente uno di plugin o remoteMcpServer	Error
mcpServerUrl deve essere un URL HTTPS valido	Error
Se mcpToolDescription è presente, file deve esistere nello ZIP	Error
authorization.referenceId obbligatorio, a meno che il tipo non sia None	Error
authorization.referenceId non deve essere presente quando il tipo è None	Error

Convalida file associato

Il portale convalida i file complementari (materiali di riferimento, script e altri file insieme a SKILL.md) al momento del caricamento e della sincronizzazione:

Rule	Severity
Massimo 20 file complementari per competenza (escluso SKILL.md)	Error
Ogni file associato non deve superare 5 MB	Error
Il totale dei file associati non deve superare i 10 MB per competenza	Error
I percorsi dei file devono essere relativi (nessun percorso assoluto)	Error
Nessun segmento attraversamento percorso (..)	Error
Nessuna barra rovesciata o byte null nei nomi dei file	Error
Nessun file nascosto (nomi che iniziano con .)	Error
Nessun nome riservato di Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9)	Error
I nomi file devono contenere solo caratteri sicuri (alfanumerici, trattini, caratteri di sottolineatura, punti, spazi, !)	Error

Compatibilità multipiattaforma

Le competenze usano lo standard aperto Competenze agente. Gli stessi SKILL.md file funzionano su più strumenti di intelligenza artificiale:

Platform	Compatibility
Claude Code	Formato SKILL.md identico completo
Progetti Claude.ai	Le competenze complete possono essere caricate come file di progetto
VS Code / GitHub Copilot	Competenze dell'agente complete supportate in modalità agente
Interfaccia della riga di comando Gemini	Competenze agente complete supportate
JetBrains Junie	Competenze agente complete supportate
OpenAI Codex	Competenze agente complete supportate
Cursor	Competenze agente complete supportate

Se stai sviluppando competenze sia per Claude Code che per Copilot Cowork, sviluppa il plug-in con wiqd. Quindi eseguire wiqd plugin export --format claude-plugin per produrre il layout di Claude Code. Se preferisci iniziare dalla struttura del plugin Claude Code - è il superset - il layout è:

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)

Quindi importalo in Microsoft 365 quando sei pronto per pubblicare nell'App Store di Microsoft 365, con wiqd plugin import o con lo script di conversione:

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

Gestione annotazioni e conferme MCP

Copilot Cowork legge l'oggetto annotations MCP standard sugli strumenti restituiti dal server da tools/list e lo usa per decidere se una chiamata allo strumento richiede la conferma dell'utente e quale etichetta mostrare nel prompt.

Campi disponibili

Field	Type	Effect
readOnlyHint	bool	false: è necessaria una conferma prima che lo strumento venga eseguito.
destructiveHint	bool	true: è necessaria una conferma prima dell'esecuzione dello strumento.
title	string	Etichetta leggibile nella finestra di dialogo di conferma. Usa il nome dello strumento quando assente.

Regole di conferma

È richiesta la conferma se readOnlyHint == false o destructiveHint == true.

Tutti gli strumenti devono avere annotazioni di sicurezza specificate. Gli strumenti senza annotazioni vengono considerati distruttivi e richiedono conferma. Per altre informazioni, vedi la guida di riferimento allo schema MCP.

Esempi di MCP

Un'azione distruttiva con un'etichetta rassicurante:

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

Una lettura sicura che esegue automaticamente:

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

Cosa è disponibile ora

• Gli strumenti Microsoft (Graph, Dataverse e altri) sono controllati dai criteri integrati di Cowork indipendentemente dalle annotazioni.
• Per i server non Microsoft MCP, la conferma basata su annotazioni viene distribuita progressivamente. L'impostazione dei suggerimenti ora è compatibile con le versioni successive e la richiesta di conferma viene visualizzata man mano che l'implementazione si espande senza richiedere alcuna modifica da parte dello sviluppatore.

Accettare file dall'area di lavoro Cowork

Uno strumento connettore può prendere come input un file dalla sessione Cowork dell'utente, ovvero un documento allegato dall'utente, un allegato e-mail salvato da Cowork o un file prodotto da un passaggio precedente. Dichiara il parametro con la parola chiave standard di JSON Schema contentEncoding: base64 e Cowork gestisce il resto. Non è necessaria alcuna estensione dello schema specifica di Microsoft e la superficie API del server non cambia.

Cowork risolve il file dell'area di lavoro e lo codifica in base 64 prima di chiamare il server, quindi i byte di file non entrano mai nel contesto dell'agente. L'agente vede e restituisce solo i percorsi dei file dell'area di lavoro.

Annotazioni

Non indicare all'agente di codificare in base64 un file e incollare il BLOB in una chiamata allo strumento. Questo approccio carica l'intero file nel contesto del modello e dipende dal modello che riproduce esattamente il BLOB. Sembra funzionare su piccoli file di prova e fallisce su quelli reali.

Dichiarare un parametro di file

Una proprietà stringa con contentEncoding: base64 è riconosciuta come input di file:

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

Viene riconosciuto anche un array di tali stringhe, per gli strumenti che accettano diversi file:

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

Cosa vede l'agente

Per i parametri di file dichiarati al livello superiore di inputSchema.properties, Cowork li sostituisce nello schema rivolto al modello con una singola matrice direct_attachment_file_paths, lo stesso parametro utilizzato dagli strumenti integrati di Cowork, quindi l'agente sa già come popolarlo. Lo schema precedente viene presentato all'agente come:

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

Se lo strumento dichiara più parametri di file di primo livello, tutti vengono compressi in quella singola matrice direct_attachment_file_paths. Al momento della chiamata, Cowork apre a ventaglio i file risolti nei nomi dei parametri originali nell'ordine della dichiarazione.

Parametri di file annidati

L'agente supporta un parametro di file annidato all'interno di un oggetto o di un array di oggetti. L'agente gestisce questo parametro in modo diverso: invece di comprimerlo, l'agente lo riscrive sul posto in una stringa di percorso nella propria posizione. Questo approccio mantiene l'associazione tra un file e i relativi campi correlati. Ad esempio, si ottiene una ricevuta per ogni riga di spesa:

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

L'agente popola line_items[].receipt con un percorso dell'area di lavoro e Cowork scambia ogni percorso con il contenuto base64 sul posto prima di inoltrare la chiamata.

L'annidamento viene attraversato fino a una profondità di quattro livelli al di sotto della sommità di inputSchema. I puntatori $ref non vengono seguiti: definire i parametri del file in linea anziché dietro un file $ref.

Cosa riceve il server

Il server riceve un normale tools/call con i nomi dei parametri originali popolati con contenuto con codifica base64:

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

Il server non deve sapere che l'agente ha usato un'interfaccia basata su percorso e gli strumenti che non dichiarano i parametri contentEncoding: base64 non sono interessati.

Limits

Limit	Value
File per chiamata dello strumento	8
Dimensioni per file	150 MiB
Dimensione totale per chiamata dello strumento	150 MiB
Parametri del file array per strumento	1 (combinalo con un numero qualsiasi di parametri di file scalari)
Profondità di annidamento massima	4 livelli sotto la parte superiore di inputSchema

Una chiamata che supera il numero di file o un limite di dimensione ha esito negativo con un errore dello strumento e non raggiunge mai il server. Dimensiona la tua API e i relativi timeout tenendo presente il limite di 150 MiB: Base64 aumenta le dimensioni del payload di circa un terzo rispetto alla dimensione originale del file e il contenuto codificato viene inviato nel corpo della richiesta JSON-RPC.

Recommendations

• Descrivi il parametro per un lettore umano. L'agente usa la descrizione per decidere quale file va in quale parametro. Ad esempio, "The signed contract PDF to analyze" funziona meglio di "file".
• Indicare i formati accettati nella descrizione del parametro. Cowork passa attraverso qualsiasi cosa l'utente collega. Verifica il tipo di contenuto dal tuo lato e restituisci un messaggio di errore chiaro dello strumento se non è utilizzabile.
• Impostare le annotazioni. Uno strumento che riceve un file e agisce su di esso in genere non è di sola lettura, quindi richiede una conferma. Scopri di più in gestione delle annotazioni e delle conferme MCP.
• Mantieni i parametri del file in linea. Un parametro dietro a $ref o annidato più in profondità di quattro livelli, non viene riscritto. Il server riceverà una stringa di percorso laddove si aspetta del contenuto.
• Dichiara al massimo un parametro file array per strumento. Con due o più, Cowork non è in grado di stabilire quale file appartiene a quale array e la chiamata ha esito negativo con un errore dello strumento. Utilizzare un array, o più parametri scalari, o una combinazione di scalari e un singolo array.
• Aspettatevi un conteggio esatto con gli strumenti che supportano solo valori scalari. Se lo strumento dichiara solo parametri di file scalari, il numero di file passati dall'agente deve corrispondere al numero dichiarato. Contrassegna chiaramente i parametri di file facoltativi nelle relative descrizioni, in modo che l'agente non ne fornisca troppi o troppo pochi.

Annotazioni

Questo meccanismo è precedente al lavoro del Model Context Protocol sulla gestione dell'input dei file, che viene standardizzato dal Gruppo di lavoro sui caricamenti di file MCP. Cowork potrebbe aggiungere il supporto per la forma standardizzata degli input file dichiarativi quando sarà disponibile. Il contentEncoding: base64 contratto qui descritto continua a funzionare.

Identificare il traffico di Cowork verso il tuo server

Se il server MCP regola la visibilità degli strumenti in base al client o si desidera attribuire il traffico ricevuto, è possibile riconoscere le richieste provenienti da Cowork. Cowork presenta un'identità software stabile su due canali:

Channel	Dove appare	Value
User-Agent intestazione della richiesta	Ogni richiesta in uscita che Cowork invia al tuo server	copilot-cowork/1.0
clientInfo nell'handshake MCP initialize	Solo initialize la richiesta	{ "name": "copilot-cowork", "version": "<version>" }

Corrispondenza in base al prefisso copilot-cowork

Abbinare il copilot-coworkprefisso, senza distinzione tra maiuscole e minuscole, su uno dei due canali. Non associare alla stringa esatta copilot-cowork/1.0 o a un elemento specifico clientInfo.version. La versione segue il contratto dell'identità del client e si prevede che cambi; una corrispondenza per prefisso mantiene il controllo operativo tra un incremento di versione e l'altro.

# Correct: case-insensitive prefix match
copilot-cowork

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

Scegliere il canale giusto per il gate

I due canali hanno ambiti diversi, quindi scegli quello che corrisponde al modo in cui il server applica il suo gate:

• L'intestazione User-Agent è presente in ogni richiesta, comprese tools/list e tools/call. Se si esegue il gate o l'attributo per richiesta, usa questa intestazione come chiave.
• clientInfo viene inviato solo durante l'handshake initialize. Se si applica il gate per sessione al momento della connessione, è possibile leggerlo lì, ma non viene ripetuto nelle richieste successive.

Cosa include e cosa non include l'identità

L'identità indica solo il software . È lo stesso per ogni utente e connessione di Cowork e non trasmette mai l'identità dell'utente. L'identità dell'utente rimane nel flusso di autorizzazione definito dalla configurazione dell'autenticazione del tuo connettore.

L'identità comprende	L'identità non comprende
Un nome software stabile (copilot-cowork) e una versione del contratto	Qualsiasi identificatore di tenant, utente, sessione o conversazione
Lo stesso valore su ogni richiesta e ogni connessione	Qualificatore per singolo connettore

Poiché non esiste alcun qualificatore per connettore, al momento non è possibile usare questa identità per indicare quale connettore ha effettuato una chiamata o per separare un plug-in Microsoft pubblicato da un server trasferito localmente che punta allo stesso URL. Se è necessaria tale distinzione, applicarla tramite la configurazione dell'autorizzazione del connettore anziché l'identità client.

Domande comuni

È possibile usare le competenze del pacchetto M365 in Claude Code?

Yes. Le cartelle della competenza contengono le competenze standard degli agenti. Esegui wiqd plugin export --format claude-plugin per produrre il layout di Claude Code oppure copia le cartelle skill in .claude/skills/ in un qualsiasi progetto di Claude Code.

È necessario un connettore remoto?

No. I pacchetti di sole competenze funzionano bene per i flussi di lavoro basati su prompt. I connettori sono necessari solo quando la tua skill richiede dati in tempo reale da un sistema esterno.

In che modo le abilità dei plug-in sono diverse dalle abilità integrate?

Le competenze dei plug-in vengono visualizzate con origine "package" nell'API. Non possono sovrascrivere le competenze predefinite con lo stesso nome. I pacchetti distribuiti dall'Amministrazione mostrano isAdminDeployed: true.

Gli amministratori IT possono controllare quali plug-in sono disponibili?

Yes. Si applicano i controlli di amministrazione standard di M365: elenchi di elementi consentiti/bloccati a livello di tenant, distribuzioni gestite dagli amministratori e criteri di conformità.

Cosa succede se un plugin viene revocato?

Nel ciclo di sincronizzazione successivo, le competenze e i connettori di quel pacchetto vengono rimossi dalla sessione dell'utente. Le conversazioni attive non vengono interrotte, ma le nuove sessioni non dispongono delle funzionalità del pacchetto.

Qual è il numero massimo di competenze in un pacchetto?

Venti (20) competenze (per ASKILL-M002). Per i connettori, il limite è di 10 per pacchetto.

Le competenze possono fare riferimento agli strumenti connettore dello stesso pacchetto?

Sì, e dovrebbero. Indica esplicitamente gli strumenti nel flusso di lavoro SKILL.md (ad esempio, "Usa lo strumento search_case_law per..."). L'agent li connette al momento del runtime.

Gli strumenti del mio plugin possono accettare file dall'area di lavoro di Cowork?

Yes. Dichiara il parametro dello strumento con contentEncoding: base64, e Cowork risolve il file dell'area di lavoro dell'utente in contenuto base64 prima di chiamare il server. Il modello trasmette i percorsi dei file, non il contenuto del file, quindi i file di grandi dimensioni non consumano il contesto del modello. Per i dettagli e i limiti della dichiarazione, vedere Accettare file dall'area di lavoro Cowork.

Come faccio a generare un GUID deterministico per il mio pacchetto?

wiqd plugin create genera e fissa l'ID app. Lo script di conversione usa un UUID v5 (basato su SHA-1) a partire dal nome del plug-in, quindi eseguendo due volte la conversione produce lo stesso GUID. Per la creazione manuale del pacchetto, utilizza un qualsiasi generatore di GUID. Assicurati di mantenerlo stabile tra le versioni.

Quale versione del manifesto devo scegliere come target?

Target 1.29 se stai costruendo con wiqd, che lo blocca per te. A 1.29, agentConnectors[] le voci sono solo URL ed mcpToolDescription è facoltativo. Gli esempi redatti manualmente in questo articolo usano la versione 1.28, in cui mcpToolDescription è obbligatorio e il file che esso designa deve trovarsi nel file ZIP. atk import openplugin utilizza UUID v5 (basato su SHA-1) in base al nome del tuo plugin. Se si esegue l'importazione due volte, si produce lo stesso GUID. Per impostare il proprio, passare --app-id. Per la creazione manuale del pacchetto, utilizzare un generatore GUID qualsiasi. Assicurati di mantenerlo stabile tra le versioni.

Contenuti correlati

• Panoramica di Cowork
• Usare Cowork
• Gestisci Cowork per la tua organizzazione
• Gestisci i plugin per Cowork
• Riferimento CLI plug-in wiqd