Criar plugins para Copilot Cowork

Microsoft Copilot Cowork suporta a extensibilidade através dos Pacotes de Aplicações do M365, o mesmo mecanismo de distribuição utilizado pelas aplicações do Teams, agentes do Copilot e suplementos do Office. Pode prolongar Cowork com:

• Habilidades: fluxos de trabalho baseados em prompts que ensinam ao Cowork novos conhecimentos de domínio, como análise financeira, pesquisa jurídica ou fluxos de trabalho de RH.
• Conectores: servidores remotos que dão ao Cowork acesso a fontes de dados externas e APIs.

Ambos são empacotados em conjunto num pacote de aplicações padrão do Microsoft 365 e distribuídos através do Microsoft 365 App Store.

Importante

Barreiras de Informação (IB) do Microsoft Purview não são atualmente suportadas para a gestão e partilha de plug-ins ou de competências. Nos locatários onde o IB está ativado, os carregamentos de ficheiros de conhecimento incorporados são bloqueados ao nível do locatário. Isto impede que plugins e competências afetados sejam carregados ou publicados.

A Microsoft não cria nem mantém qualquer índice persistente, gráfico de conhecimento (incluindo o Microsoft Graph) ou base de dados que inclua Conteúdo ISV, quer seja através de pesquisa, raspagem, colheita, exportação em massa, ingestão ou qualquer outro método (através de API, servidor MCP ou de outra forma). A Microsoft pode processar temporariamente o Conteúdo ISV conforme necessário para responder à consulta em tempo real de um utilizador, mas não mantém o Conteúdo ISV para além da duração dessa sessão. Mediante pedido por escrito da ISV, a Microsoft elimina qualquer Conteúdo ISV na sua posse ou controlo no prazo de 10 dias úteis e certifica essa eliminação por escrito. Saiba mais em Proteção de dados empresariais no Microsoft Copilot e Microsoft Copilot Chat.

O que vais construir

Um plugin Cowork é um .zip pacote que contém:

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

As competências utilizam o padrão open de Competências do Agente — o mesmo formato suportado pelo Claude Code, o Visual Studio Code Copilot, a CLI Gemini, o Cursor, o JetBrains Junie e mais de 30 outras ferramentas de IA.

Escolhe o teu ponto de partida

Crie seu plugin com o wiqd CLI. A CLI estrutura o pacote e mantém manifest.json suas pastas de habilidades sincronizadas. Também executa as próprias regras de validação da plataforma antes de carregar e, em seguida, provisiona e partilha o resultado. A CLI está em visualização, portanto, seus comandos e saída gerada podem mudar antes da disponibilidade geral. Tudo o que gera é um pacote de aplicações simples do Microsoft 365, pelo que ainda pode abrir, editar e formatar os ficheiros diretamente.

Monte o pacote manualmente somente quando não puder instalar ferramentas ou quando estiver criando seu próprio pipeline de embalagem. Nesse caso, a referência do formato de pacote neste artigo é aquilo de que precisa — descreve exatamente o que wiqd produz.

Ponto de partida	Faça isto	Tempo até ao primeiro pacote
Estou a começar do zero	Crie um plugin com wiqd	cerca de 10 minutos
Tenho um plug-in Claude Code existente	Converta	cerca de 5 minutos
Não consigo instalar ferramentas ou estou a criar scripts para o meu próprio empacotamento	Montar uma embalagem à mão	cerca de 30 minutos

Crie um plugin com wiqd

A wiqd CLI executa o mesmo ciclo de vida que você faria manualmente: criar, adicionar recursos, validar, provisionar, empacotar e compartilhar. O pacote que produz já satisfaz as regras de validação descritas neste artigo.

Passo 1: Instalar o wiqd e iniciar sessão

Instale a CLI wiqd seguindo o guia de instalação wiqd, que abrange Windows, macOS e Linux. Em seguida, inicie sessão no inquilino do Microsoft 365 contra o qual está a desenvolver, porque o aprovisionamento e a partilha afetam o seu inquilino:

wiqd auth login --interactive

O instalador também registra um plug-in GitHub Copilot CLI, para que você possa conduzir o mesmo ciclo de vida conversacionalmente. Por exemplo, pode dizer, Criar um plug-in autónomo chamado Auxiliar de Triagem ou Validar o meu plug-in. O caminho de conversação executa os mesmos comandos desta secção. Utilize os comandos diretamente quando estiver a criar um script para um pipeline ou quiser uma automação reproduzível e não interativa.

Passo 2: Andaime o plugin e adicione recursos

Crie o contêiner do plug-in e, em seguida, adicione os recursos de que precisar, em qualquer combinação:

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 gera o esqueleto appPackage/skills/contract-analysis/SKILL.md e regista-o em agentSkills[]. add connector escreve a entrada agentConnectors[]. Ambos os comandos impõem a nomenclatura e os limites de tamanho da plataforma antes de escrever no manifesto, para que uma incompatibilidade de nome de pasta ou um comprimento id excessivo nunca chegue ao manifesto.

Escreva a lógica da skill no SKILL.md gerado. Os campos frontmatter, modelo de carregamento progressivo e limites de arquivo complementar são os mesmos descritos em Etapa 1: crie sua primeira habilidade e Etapa 2: adicionar materiais de referência (opcional).

Importante

wiqd plugin create fixa a versão do pacote em manifestVersion: "1.29", enquanto os exemplos escritos manualmente neste artigo usam 1.28. Esta diferença é importante para os conectores. Em 1.28, mcpToolDescription é necessário, e o ficheiro a que ele dá nome deve estar no ZIP. Em 1.29, as entradas agentConnectors[] são apenas URL e mcpToolDescription é opcional, para que um pacote gerado pelo wiqd nunca encontra essa falha de carregamento. O wiqd ainda não gera a autenticação do conector — configure-a diretamente conforme descrito em Tipos de autenticação suportados.

Passo 3: Validar à medida que cria

Valide continuamente em vez de montar um pacote e esperar que o upload seja aprovado:

wiqd plugin validate
wiqd plugin validate --mode deep

validate é a verificação estática offline sobre a superfície do agente declarativo. Um plugin apenas de skills ou apenas conector passa sem nada para verificar, o que é esperado — é uma verificação para o seu loop de construção, não cobertura total. validate --mode deep empacota o plug-in primeiro e, em seguida, valida a compilação gerada .zip em relação à mesma Biblioteca de Validação de Aplicativo usada pelo upload. É aí que os códigos ASKILL e as regras de conexão aparecem.

Passo 4: Aprovisionar, empacotar e partilhar

Execute estes três comandos por ordem:

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

Execute provision primeiro porque escreve o ficheiro de ambiente de que package e share dependem. Utilize --scope users para partilhar com as pessoas que listou ou --scope tenant para partilhar com todas as pessoas da sua organização. De qualquer forma, o plugin aparece em Compartilhado comigo em Cowork>Sources & Skills>Plugins. Para listá-lo na seção Discover, um administrador carrega o pacote. Saiba mais no Passo 8: Publicar no seu tenant. Para remover o que provision criou, execute wiqd plugin delete --env local --yes.

A submissão da loja pública ainda é um processo manual no Partner Center. Saiba mais no Passo 9: publicar para o público.

Leve um plugin para outro anfitrião

Para usar as suas competências no Claude Code, no Cursor ou em qualquer outro anfitrião de Competências de Agente, exporte o projeto em vez de copiar pastas manualmente:

wiqd plugin export --format claude-plugin

export padrão para --format open-plugin e também aceita cursor-plugin. Grava um diretório não compactado em <path>/export/<format>.

Importar um plug-in existente

Se você já tem um plugin Claude Code com habilidades e servidores MCP, você tem duas rotas de conversão. A rota que escolher depende de se planeia continuar a desenvolver o plugin ou apenas lançar o que tem.

Goal	Utilizar
Continue a desenvolver, validar e distribuir o plug-in a partir do Microsoft 365	wiqd plugin import
Produza uma publicação .zip a partir de um plugin de Claude existente agora mesmo	O script de conversão

Importar com wiqd

wiqd plugin import reconhece uma origem de Open Plugin, plug-in Claude ou plug-in Cursor e gera um projeto de plug-in do wiqd a partir dela. O plug-in importado integra-se no mesmo ciclo de vida que um plug-in que criou com 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 são obrigatórios apenas na primeira importação de um plugin. Se a fonte veio de uma instância anterior wiqd plugin export, os metadados de ida e volta já os carregam.

Importante

Um projeto importado suporta apenas a parte de leitura do ciclo de vida — wiqd plugin validate, show e list. Ainda não pode ser empacotado, provisionado ou partilhado, porque a importação não gera os ficheiros de implementação locais necessários para essas etapas. Esta é uma lacuna registada. Para obter o status atual, verifique a referência da CLI wiqd. Se precisar de um pacote pronto para publicação hoje, use o script de conversão.

Converta com o script de conversão

O script de conversão traduz um plugin Claude diretamente em um pacote M365 publicável:

1. Instale a CLI (requer a versão 1.1.12 ou posterior):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Verifique a versão:

   atk --version
   

3. Importe o seu plugin:

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

O comando lê o diretório .claude-plugin/plugin.json (ou .cursor-plugin/plugin.json), .mcp.json e skills/ do seu plug-in e, em seguida, cria um projeto do Agents Toolkit contendo appPackage/manifest.json, as suas habilidades e ícones gerados.

Tem de incluir --privacy-url e --terms-url porque os manifestos do plug-in não têm campos equivalentes e o manifesto do Microsoft 365 requer ambos.

Note

atk import openpluginLocaliza um manifesto de plug-in num diretório com prefixo de ponto—.claude-plugin/plugin.json, .plugin/plugin.json ou .cursor-plugin/plugin.json—ao lado de .mcp.json. A especificação Agent Plugins 1.0.0 situa o manifesto num plugin.json de nível superior e a configuração MCP em mcp.json. Para importar um plug-in que segue o layout 1.0.0, mova o seu ficheiro de manifesto para .plugin/plugin.json e renomeie mcp.json para .mcp.json.

Empacote o resultado num carregável .zip:

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

Note

atk import openplugin gera um devPreview manifest. Os exemplos de manifestos noutras partes deste artigo destinam-se ao esquema v1.28. Se você estiver publicando através de um canal que requer v1.28, atualize manifestVersion e $schema no gerado appPackage/manifest.json.

O que é importado

Artefacto de plug-in	equivalente ao M365	Notes
.claude-plugin/plugin.json	manifest.json	Campos de nome, descrição e programador mapeados; GUID gerado automaticamente (UUID determinístico v5)
skills/*/SKILL.md	agentSkills[] entradas + skills/ pasta	Verbatim copiado - formato idêntico
.mcp.json servidores	agentConnectors[] entradas	URL e tipo de autenticação detetados automaticamente
color.png / outline.png	Ícones no pacote	Utilizado se estiver presente; marcadores de posição gerados se estiverem em falta

Importante

Para cada conector importado de authorization.referenceId, o .mcp.json gerado é um marcador de posição derivado do plug-in e do nome do servidor. Substitua-o pelo identificador de registo do seu cliente OAuth antes de o publicar. Saiba mais em Tipos de autenticação suportados.

O que não foi convertido

As seguintes funcionalidades de plug-in do Claude ainda não são suportadas no manifesto do Microsoft 365:

Funcionalidade do plug-in Claude	Status
commands/ (comandos com barra)	Ainda não suportado
agents/ (sub-agentes)	Ainda não suportado
hooks/ (processadores de eventos)	Ainda não suportado
settings.json	Não aplicável
bin/ (executáveis)	Não aplicável

Opções de importação

Option	Description
--path, -p	Required. Diretório de plug-ins contendo .claude-plugin/plugin.json, .cursor-plugin/plugin.json, ou .plugin/plugin.json
--output, -o	Pasta do projeto de destino (padrão: ./<plugin-name>)
--privacy-url	developer.privacyUrl para o manifesto gerado
--terms-url	developer.termsOfUseUrl para o manifesto gerado
--website-url	developer.websiteUrl. Recorre a homepage e, depois, a author.url
--app-id	Ignorar o UUID determinístico v5 gerado para o manifesto id
--default-auth-type	Auto (predefinição), None, OAuthPluginVault, ou ApiKeyPluginVault

Detecção automática do tipo de autenticação:

Source	Tipo de autenticação predefinido	Reason
URLs HTTPS externas	OAuthPluginVault	A maioria das APIs remotas precisa de autenticação
localhost e URLs não HTTPS	None	Servidores de desenvolvimento local

Se a deteção automática não corresponder à sua configuração, utilize --default-auth-type para ignorar essa deteção.

Exportar novamente para um diretório de plug-ins

Para mover um projeto do Agents Toolkit de volta para um diretório de plug-ins — por exemplo, para manter um plug-in Claude Code e um pacote de Cowork sincronizados — useatk export openplugin:

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

Option	Description
--path, -p	Required. Pasta de projeto do Agents Toolkit contendo appPackage/manifest.json
--output, -o	Diretório de plug-in de destino (padrão: ./<plugin-name>-openplugin)
--manifest-kind	open-plugin (predefinido, escreve em .plugin/plugin.json), claude-plugin, ou cursor-plugin

Export grava um bloco x-microsoft-365-agents-toolkit no ficheiro plugin.json gerado. Este bloco inclui o manifesto id, os URLs do programador e as configurações do conector, pelo que uma posterior operação de ida e volta atk import openplugin sem voltar a precisar de --privacy-url nem de --terms-url.

Note

O x-microsoft-365-agents-toolkit bloco é específico para Agents Toolkit, e o tipo padrão open-plugin grava o manifesto em .plugin/plugin.json. O Agent Plugins 1.0.0 usa um nível plugin.json superior e carrega dados específicos do cliente sob uma extensions chave com um namespace de domínio reverso, para que outros clientes ignorem esse bloqueio em vez de agir sobre ele. Quando o seu destino é Claude Code ou Cursor, use --manifest-kind claude-plugin ou cursor-plugin.

Herdado: script de conversão em PowerShell

Antes de o atk suportar a importação de plug-ins, a conversão utilizava um script do PowerShell apenas para Windows, que permanece disponível como script de conversão:

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

Utilize atk import openplugin em substituição. É multiplataforma, suporta Cursor e fontes de código Claude e pode exportar de volta para um diretório de plugins.

Montar uma embalagem à mão

Esta seção é a referência de formato de pacote: descreve exatamente o que Build a plugin with wiqd gera, campo por campo. Siga-o de ponta a ponta quando não conseguir instalar ferramentas ou estiver construindo seu próprio pipeline de embalagem. Utilize-o como referência quando precisar entender ou depurar um pacote gerado.

Passo 1: Crie a sua primeira competência

Uma competência é uma pasta que contém um SKILL.md ficheiro. Crie a seguinte estrutura de pastas:

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

Escreva SKILL.md com frontmatter YAML e um 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 |

SKILL.md campos Frontmatter

Campos obrigatórios:

Field	Constraints	Description
name	1-64 caracteres, kebab-case	Identificador de habilidade - deve corresponder exatamente ao nome da pasta
description	1-1024 carateres	Quando usar esta habilidade - inclua frases de gatilho

Importante

• O nome da pasta deve corresponder ao name campo no frontmatter. Essa incompatibilidade é a causa mais comum de falhas de habilidade.
• Os campos de listagem description de plug-ins não devem incluir chamadas à ação direcionando os utilizadores para mercados externos para comprar subscrições.

Caminho da pasta	name campo	É válido?	Porquê
skills/contract-analysis/SKILL.md	contract-analysis	Yes	A pasta e o nome correspondem
skills/contract-analysis/SKILL.md	ContractAnalysis	No	O nome usa PascalCase em vez de corresponder ao nome da pasta
skills/my-skill/SKILL.md	contract-analysis	No	Pasta é my-skill mas o nome é contract-analysis

Regras de nomenclatura (kebab-case): Utilize apenas carateres alfanuméricos minúsculos e hífenes. Não utilize hífenes consecutivos nem hífenes à esquerda ou à direita.

Example	É válido?	Issue
bond-relative-value	Yes	Minúsculas com hífenes
fx-carry-trade	Yes	Minúsculas com hífens
email	Yes	Palavra única, sem necessidade de hífenes
Bond_Relative_Value	No	Sublinhados e letras maiúsculas
--my-skill--	No	Hífens à esquerda e à direita
my--skill	No	Hífens consecutivos

Passo 2: Adicionar materiais de referência (opcional)

Para habilidades complexas, mantenha a enxuta principal SKILL.md e mova o conteúdo detalhado para subdiretórios. Estes ficheiros adicionais são ficheiros complementares. A skill carrega-os quando necessário.

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

Limites dos ficheiros complementares

Cada habilidade pode incluir até 20 arquivos complementares (qualquer arquivo diferente de SKILL.md). Aplicam-se os seguintes limites por competência:

Limit	Valor
Número máximo de ficheiros complementares	20
Tamanho máximo por ficheiro associado	5 MB
Tamanho total máximo do complemento	10 MB
Tempo limite da transferência (todos os complementos)	15 segundos

Regras para ficheiros associados

Os caminhos de ficheiros complementares têm de seguir estas regras:

• Use apenas caminhos relativos (sem caminhos absolutos).
• Sem travessia de caminhos (.. segmentos).
• Sem barras invertidas ou bytes nulos em nomes de ficheiros.
• Sem arquivos ocultos (nomes começando com .).
• Sem nomes reservados do Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
• O ficheiro SKILL.md em si não conta como um ficheiro complementar.
• Os nomes de ficheiro têm de utilizar carateres seguros: alfanuméricos, hífenes, carateres de sublinhado, pontos, espaços e !.

Para manter a janela de contexto eficiente, o sistema carrega habilidades em três camadas:

Camada	Quando carregado	Tamanho do alvo
Frontmatter (name + description)	Sempre - no arranque	~100 tokens
SKILL.md corpo	Ao ativar a skill	Menos de 5.000 tokens (1.500-2.000 palavras)
Referências (references/)	A pedido de agente	Unlimited
Scripts (scripts/)	Executado, não carregado no contexto	N/A

Faça referência aos subdiretórios explicitamente em SKILL.md para que o agente saiba que eles existem:

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

Passo 3: adicionar um conector (opcional)

Se a extensão precisar de acesso a dados externos, adicione um servidor MCP remoto. Esta etapa é opcional. Os pacotes apenas de competências funcionam bem para fluxos de trabalho baseados em prompts.

Tip

Se o seu servidor controlar a visibilidade da ferramenta por cliente ou atribuir tráfego de entrada, aceda a Identificar o tráfego do Cowork para o seu servidor para a identidade do cliente que o Cowork apresenta.

Note

Os plug-ins personalizados não são suportados no Cowork em dispositivos móveis.

Requisitos do conector

Requirement	Details
Transport	HTTP Streamable (HTTPS necessário, TLS 1.2+)
Protocol	Formato de mensagem JSON-RPC 2.0
Descoberta de ferramentas	Suporte tools/list para deteção dinâmica (recomendado)
Execução de ferramenta	Suporte tools/call à invocação
Availability	SLA de disponibilidade de 99,9% recomendado para aplicações publicadas na loja
Tempo de resposta	Menos de 30 segundos por chamada de ferramenta

Diretrizes de conceção de ferramentas

• Uma ferramenta por ação para pequenas APIs (menos de 15 operações): search_case_law, get_ruling, cite_precedent
• Pesquisar + executar para APIs grandes (50+ operações): search_actions + execute_action
• Nomes descritivos: get_bond_price não getData
• Esquemas de entrada avançados: inclua uma descrição para cada parâmetro — é isso que o agente lê
• Saída estruturada: retorna JSON que o agente pode formatar para o utilizador
• Entradas de arquivo: Para aceitar um arquivo do espaço de trabalho do usuário, declare o parâmetro com contentEncoding: base64. Saiba mais em Aceitar ficheiros do espaço de trabalho do Cowork.

Descreva as ferramentas do conector (mcpToolDescription)

Opcionalmente, um remoteMcpServer conector pode incluir um mcpToolDescription objeto. Quando fornecido, sua propriedade aninhada file aponta para um arquivo JSON de descrição de ferramenta que você empacota dentro do seu .zip e referencia por um caminho relativo da raiz do pacote. Cowork descobre ferramentas dinamicamente a partir do seu servidor MCP e não usa esse arquivo, mesmo quando ele está presente.

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

Se incluir mcpToolDescription, o ficheiro referenciado (por exemplo, tools/contoso-legal-tools.json) descreve as ferramentas que o conector expõe e tem de estar presente no pacote ZIP. Inclua-o ao lado da pasta manifest.json e da pasta skills/ quando empacotar o plugin.

Tip

Este requisito aplica-se ao manifest versão 1.28. Os pacotes que wiqd plugin create geram visam a versão 1.29, em que as entradas agentConnectors[] são apenas URLs, mcpToolDescription é opcional e não há nenhum arquivo de descrição de ferramenta para esquecer.

Tipos de autenticação suportados

Tipo de autenticação	Quando utilizar	Experiência de utilizador
None	APIs públicas ou anónimas, serviços internos	Transparente - sem pedido de autenticação
OAuthPluginVault	APIs OAuth 2.0 (recomendadas para produção)	O utilizador conclui o consentimento OAuth uma vez
ApiKeyPluginVault	Serviços baseados em chave de API	O utilizador fornece a chave uma vez

Note

• O suporte para a autenticação por chave de API ainda não está disponível no Cowork.
• Se o servidor MCP exigir uma chave API, use OAuthPluginVault ou Registo Dinâmico de Clientes em vez disso, ou exponha um ponto de extremidade que aceite None.

Para OAuthPluginVault e ApiKeyPluginVault, o referenceId aponta para credenciais armazenadas no Microsoft Enterprise Token Store - segredos nunca aparecem no manifesto ou ficheiros de skill. O referenceId valor é o ID de registo do cliente OAuth que cria ao registar um cliente OAuth com o Agents Toolkit.

Importante

Ao registar o seu cliente OAuth, defina a utilização por organização para Qualquer Organização do Microsoft 365 para garantir que o plug-in funciona em vários locatários.

Autenticação MCP

Para usar OAuth ou ApiKey para autenticação, consulte Configurar autenticação para plug-ins MCP e API em agentes no Microsoft 365 Copilot para obter detalhes de instalação e configuração.

Registo Dinâmico de Clientes

Se o seu servidor MCP suportar Registo Dinâmico de Clientes (DCR), pode omitir uma authentication configuração da sua definição de conector e Cowork cria automaticamente um cliente OAuth em nome do seu plug-in.

Note

A omissão da authentication configuração é suportada apenas no Cowork. Não é suportado no Copilot Chat. Se o plug-in também precisar funcionar no Copilot Chat, configure OAuthPluginVault a autenticação conforme descrito em Tipos de autenticação suportados.

Pode omitir totalmente o authorization objeto. Configure a URL do servidor MCP e Cowork cuida do cliente OAuth:

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

Passo 4: Criar o ficheiro de manifesto

Crie manifest.json na raiz do seu pacote. O exemplo usa manifest versão 1.28; wiqd plugin create fixa a versão 1.29 em vez disso, onde as entradas do conector são somente 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" }
  ]
}

Para adicionar um conector, inclua 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"
          }
        }
      }
    }
  ]
}

Na configuração do conector, referenceId deve estar o ID de registo OAuth. Se você incluir mcpToolDescription, o respetivo file deve apontar para um arquivo JSON de descrição da ferramenta incluído no pacote ZIP.

Importante

O esquema de manifesto v1.28 é estrito: é definido additionalProperties: false na raiz, portanto, qualquer campo que não esteja definido no esquema é rejeitado. Os campos que são válidos em manifestos padrão da aplicação Teams, como por exemplo packageName, fazem com que o carregamento falhe com um erro como Property 'packageName' has not been defined and the schema does not allow additional properties. Incluir apenas os campos aqui apresentados.

Passo 5: adicionar ícones

Crie dois ícones PNG:

Ícone	Size	Purpose
color.png	192×192 px	Ícone de aplicação colorido apresentado na loja e na lista de aplicações
outline.png	32×32 px	Ícone de contorno de cor única para vistas compactas

Se ainda não tiver ícones, atk import openplugin gera marcadores de posição de cor sólida. Substitua-os antes da submissão à loja.

Passo 6: Empacotar

Crie um arquivo ZIP com todos os conteúdos no nível raiz. wiqd plugin package( produz esta mesma estrutura após 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 um conector incluir mcpToolDescription, inclua o arquivo JSON de descrição da ferramenta ao qual ele faz referência. Os pacotes que não utilizam mcpToolDescription, incluindo os pacotes apenas de competências, não precisam de uma tools/ pasta.

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/

Utilizar o Toolkit de Agentes do Microsoft 365

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

Passo 7: Teste

Para testar a sua aplicação, carregue o pacote de aplicação para o Teams, conforme descrito em Carregar a sua aplicação para o Teams.

Se você construiu o plug-in com wiqd, execute wiqd plugin provision em vez disso — ele registra o plug-in com seu tenant para você. Para testes pessoais de um pacote montado à mão, faça o sideload da aplicação utilizando a interface da linha de comandos do Microsoft 365 Agents Toolkit:

1. Instalar @microsoft/m365agentstoolkit-cli a partir de npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Verifique a instalação executando:

   atk --version
   

3. Autentique-se com a sua conta profissional do Microsoft 365:

   atk auth login
   

4. Entre na sua conta profissional e instale o pacote do agente. Substitua o caminho do ficheiro pela localização do seu pacote ZIP:

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

   Uma instalação bem-sucedida retorna uma saída que inclui um TitleId e AppId para a sua conta.

5. Guarde estes IDs para utilização posterior quando atualizar ou desinstalar.

Saiba mais na interface da linha de comandos do Microsoft 365 Agents Toolkit.

Passo 8: publicar no seu tenant

Carregue o pacote no centro de administração para listar o seu plug-in na secção Descobrir , onde qualquer pessoa na sua organização o pode encontrar:

1. Abrir o centro de administração do M365Gerir aplicações>Carregue a aplicação personalizada.>
2. Selecione o botão de elipse (...) >Adicionar agente.
3. Carregue o seu pacote .zip
4. Abra Cowork>Sources & Skills>Plugins. O seu plug-in aparece na secção Discover.

wiqd plugin share coloca o plugin em Partilhado comigo em vez de Descoberta. Utilize-o para testes e para implementação direcionada a pessoas específicas. O carregamento no Centro de administração é o que permite listar um plug-in para deteção.

Passo 9: Publicar para o público

Para plug-ins destinados à distribuição pública, submeta o seu plug-in à App Store do Microsoft 365 através do Partner Center. Saiba mais em Publicar agentes para Microsoft 365 Copilot.

Testar um conector em relação a um servidor MCP local

Os conectores requerem um certificado HTTPS mcpServerUrl. Para testar um servidor em execução na sua máquina, tem de expô-lo através de um URL HTTPS público. Os túneis de desenvolvimento fornecem um relé que faz a terminação de TLS para si.

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

Importante

Use --protocol http, não https. A --protocol opção descreve o serviço local para o qual o túnel encaminha, não o URL do túnel público. A maioria dos servidores MCP locais fala HTTP simples, portanto, se você definir --protocol https enquanto seu servidor serve HTTP, cada solicitação através do túnel retornará um 502 erro. O reencaminhador faz a terminação de TLS e disponibiliza o URL público através de HTTPS, independentemente deste sinalizador.

Troubleshooting

Symptom	Motivo	Corrigir
Cada solicitação encapsulada retorna 502 e o servidor local fala HTTP	devtunnel port create foi executado com --protocol https	Recrie o porto com --protocol http
Os pedidos tunelados devolvem 502 no macOS, apesar de o servidor local estar em execução	O servidor está associado a 0.0.0.0 (apenas IPv4), mas o túnel estabelece ligação a localhost, que é resolvido primeiro para ::1 (IPv6)	Associe o servidor a :: para que aceite ligações IPv4 e IPv6
O upload falha com Property '<field>' has not been defined and the schema does not allow additional properties	O ficheiro manifest inclui um campo não permitido pelo esquema v1.28 (por exemplo, packageName)	Remova o campo; o esquema v1.28 utiliza additionalProperties: false

Padrões de embalagem

Escolha o padrão que se adapta à sua extensão:

Apenas competências (sem conector)

Ideal para fluxos de trabalho baseados em prompts, análise de documentos e assistência na escrita.

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

Skills + conector remoto

Ideal para análise de dados, integrações de API e sistemas empresariais.

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

Apenas o conector (sem competências personalizadas)

Utilize esta opção para fontes de dados que já podem ser utilizadas pelas competências integradas do Cowork.

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

Claude Code importado ou o plug-in Cursor

Utilize esta opção para plug-ins já existentes no ecossistema Claude concebidos para o Cowork. Para continuar a desenvolver o plug-in no Microsoft 365, importe-o:

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

Para produzir uma versão publicável .zip a partir do plugin no seu estado atual, use o script de conversão:

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

Melhores práticas de criação de habilidades

Siga estas diretrizes para criar competências que se ativem de forma fiável e produzam resultados consistentes.

Escrever descrições eficazes

O description campo determina quando o agente ativa sua habilidade. Seja específico:

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

Criar fluxos de trabalho eficazes

• Seja específico na descrição. Inclua frases de acionamento: "Utilizar quando o utilizador pedir..." Esta descrição é como o agente decide qual competência ativar.
• Estruturar como um fluxo de trabalho. Numere os passos. Cada etapa deve mapear para uma ação concreta (ler um arquivo, chamar uma ferramenta, gerar saída).
• Definir formato de saída. Mostre a tabela, lista ou estrutura de documento exata que os utilizadores devem esperar. Esta definição melhora drasticamente a consistência.
• Ferramentas de referência pelo nome. Se a sua capacidade depender das ferramentas de conector, nomeie-as explicitamente: "Utilize a ferramenta search_case_law para..."
• Mantenha o SKILL.md principal enxuto. Mova material de referência detalhado para o references/ subdiretório. O corpo da skill deve ser o fluxo de trabalho, não uma enciclopédia.

Evite erros comuns

• Não incorpore segredos em SKILL.md ficheiros. Utilize agentConnectors com autenticação com credenciais da API.
• Não duplique competências integradas. Verifique a lista de skills integradas antes de criar.
• Não torne as competências demasiado amplas. "Fazer tudo com documentos legais" é pior do que habilidades específicas para "análise de contratos", "extração de cláusulas" e "pesquisa jurídica".
• Não codifique caminhos de ficheiro de forma fixa ou comandos do sistema. As competências devem ser portáteis em todos os ambientes.
• Não coloque tudo em SKILL.md. Se o seu texto ultrapassar as ~3.000 palavras, transfira o conteúdo detalhado para references/.

Regras de validação

Quando submete a sua submissão, a plataforma valida-a a vários níveis. Corrija estes erros antes da submissão para evitar a rejeição.

Para capturá-los à medida que os cria, em vez de no momento do carregamento, execute wiqd plugin validate --mode deep. Este comando empacota o plug-in e executa estas mesmas regras localmente. Saiba mais no Passo 3: validar à medida que cria.

Validação ao nível do manifesto

Code	Regra	Severity
ASKILL-M001	folder é necessário em cada entrada agentSkills	Erro
ASKILL-M002	agentSkills array pode ter até 20 itens	Erro
ASKILL-M003	folder O caminho pode ter até 256 caracteres	Erro

Validação ao nível do pacote

Code	Regra	Correção frequente	Severity
ASKILL-P001	A pasta referenciada no manifesto existe no ZIP	Verifique a estrutura do seu zip	Erro
ASKILL-P002	A pasta contém um SKILL.md ficheiro	Adicionar o elemento em falta SKILL.md	Erro
ASKILL-P003	SKILL.md tem frontmatter YAML válido entre --- delimitadores	Corrigir sintaxe YAML	Erro
ASKILL-P004	Frontmatter inclui o campo name	Adicionar name: ao frontmatter	Erro
ASKILL-P005	Frontmatter inclui o campo description	Adicionar description: ao frontmatter	Erro
ASKILL-P006	name corresponde ao nome da pasta (segmento do último caminho)	Mudar o nome da pasta ou corrigir name:	Erro
ASKILL-P007	name é kebab-case	MySkill Não utilize my-skill oumy_skill	Erro
ASKILL-P008	Não existem valores duplicados folder na matriz	Eliminar duplicados	Erro

Validação do conector

Regra	Severity
Cada conector requer um id e um displayName	Erro
Todos os valores de conexão id devem ser exclusivos dentro do manifesto	Erro
Exatamente um dos plugin ou remoteMcpServer	Erro
mcpServerUrl tem de ser um URL HTTPS válido	Erro
Se mcpToolDescription estiver presente, o seu file tem de existir no ZIP	Erro
authorization.referenceId obrigatório, a menos que o tipo seja None	Erro
authorization.referenceId não deve estar presente quando o tipo é None	Erro

Validação de ficheiro complementar

O portal valida ficheiros complementares (materiais de referência, scripts e outros ficheiros juntamente com SKILL.md) aquando do carregamento e da sincronização:

Regra	Severity
Máximo de 20 ficheiros anexos por skill (excluindo SKILL.md)	Erro
Cada ficheiro complementar tem de ter 5 MB ou menos	Erro
O total dos ficheiros anexos não pode exceder 10 MB por aptidão.	Erro
Os caminhos de arquivo devem ser relativos (sem caminhos absolutos)	Erro
Sem segmentos de travessia de caminho (..)	Erro
Sem barras invertidas ou bytes nulos em nomes de ficheiro	Erro
Sem ficheiros ocultos (nomes a começar por .)	Erro
Sem nomes reservados do Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT9–LPT1)	Erro
Os nomes de ficheiro têm de utilizar apenas carateres seguros (alfanuméricos, hífenes, sublinhados, pontos, espaços, !)	Erro

Compatibilidade entre plataformas

As Skills usam a norma aberta Agent Skills. Os mesmos ficheiros SKILL.md funcionam em múltiplas ferramentas de IA:

Platform	Compatibility
Código Claude	Formato totalmente igual SKILL.md
Projetos do Claude.ai	full-skills podem ser carregadas como arquivos de projeto
VS Code / GitHub Copilot	Competências Full-Agent suportadas no modo de agente
Gemini CLI	Competências suportadas do agente completo
JetBrains Junie	Capacidades de agente completo suportadas
OpenAI Codex	Capacidades suportadas do Full-Agent
Cursor	Competências Full-Agent suportadas

Se você está desenvolvendo habilidades para Claude Code e Copilot Cowork, crie o plugin com wiqd. Em seguida, execute wiqd plugin export --format claude-plugin para produzir o layout do Claude Code. Se preferir partir da estrutura da extensão Claude Code — é o superconjunto — a estrutura é:

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)

Em seguida, traga-o para o Microsoft 365 quando estiver pronto para publicar no Microsoft 365 App Store, com wiqd plugin import ou com o script de conversão:

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

Gestão de anotações e confirmações do MCP

Copilot Cowork lê o objeto MCP annotations padrão das ferramentas que o seu servidor devolve a partir de tools/list, e usa-o para decidir se uma chamada de ferramenta precisa de confirmação do utilizador e que rótulo mostrar no prompt.

Campos disponíveis

Field	Tipo	Effect
readOnlyHint	bool	false: confirmação necessária antes de a ferramenta ser executada.
destructiveHint	bool	true: confirmação necessária antes de a ferramenta ser executada.
title	cadeia (de caracteres)	Etiqueta legível apresentada na caixa de diálogo de confirmação. Usa o nome da ferramenta como alternativa quando estiver ausente.

Regras de confirmação

É necessária confirmação se readOnlyHint == false ou destructiveHint == true.

Todas as ferramentas têm de ter anotações de segurança especificadas. As ferramentas sem anotações são tratadas como destrutivas e exigem confirmação. Saiba mais na referência de esquema MCP.

Exemplos de MCP

Uma ação destrutiva com um rótulo amigável:

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

Uma operação de leitura segura que é executada automaticamente:

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

O que está disponível agora

• As ferramentas da Microsoft (Graph, Dataverse e outras) estão limitadas pela política incorporada do Cowork, independentemente das anotações.
• Para servidores MCP que não sejam da Microsoft, a confirmação orientada por anotação está a ser implementada progressivamente. Definir agora as indicações é retrocompatível com versões futuras, e os pedidos de confirmação passam a ser apresentados à medida que a disponibilização é alargada, sem exigir qualquer alteração por parte do programador.

Aceitar ficheiros do espaço de trabalho do Cowork

Uma ferramenta de ligação pode receber um ficheiro da sessão do utilizador no Cowork como entrada — um documento anexado pelo utilizador, um anexo de e-mail guardado pelo Cowork ou um ficheiro produzido por uma etapa anterior. Declare o parâmetro com a palavra-chave padrão do JSON Schema contentEncoding: base64 e a Cowork trata do resto. Não é necessária nenhuma extensão específica do esquema da Microsoft, e a interface da API do seu servidor não se altera.

O Cowork resolve o ficheiro do espaço de trabalho e codifica-o em Base64 antes de chamar o seu servidor, pelo que os bytes do ficheiro nunca entram no contexto do agente. O agente apenas vê e produz caminhos para ficheiros no espaço de trabalho.

Note

Não instrua o agente a codificar um arquivo em si, base64 e colar o blob em uma chamada de ferramenta. Essa abordagem carrega o arquivo inteiro no contexto do modelo e depende do modelo que reproduz o blob exatamente. Parece funcionar em pequenos ficheiros de teste e falha em ficheiros reais.

Declarar um parâmetro de ficheiro

Uma propriedade de cadeia de caracteres com contentEncoding: base64 é reconhecida como uma entrada de arquivo:

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

Uma matriz dessas cadeias de caracteres também é reconhecida, para ferramentas que aceitam vários arquivos:

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

O que o agente vê

Para os parâmetros de ficheiro declarados no nível superior de inputSchema.properties, o Cowork substitui-os, no esquema voltado para o modelo, por um único array direct_attachment_file_paths — o mesmo parâmetro que as ferramentas integradas do Cowork utilizam, pelo que o agente já sabe como o preencher. O esquema acima é apresentado ao agente como:

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

Se a ferramenta declarar mais de um parâmetro de ficheiro de nível superior, todos eles serão recolhidos nesse único direct_attachment_file_paths array. No momento da chamada, o Cowork redistribui os ficheiros resolvidos pelos nomes originais dos parâmetros na ordem da declaração.

Parâmetros de ficheiro aninhados

O agente é compatível com um parâmetro de ficheiro aninhado num objeto ou num array de objetos. O agente manipula este parâmetro de forma diferente: em vez de colapsá-lo, o agente reescreve-o no próprio parâmetro numa cadeia de caracteres de caminho no seu próprio local. Esta abordagem preserva a associação entre um ficheiro e os seus campos associados do mesmo nível. Por exemplo, recebe um recibo por linha de despesa:

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

O agente preenche line_items[].receipt com um caminho da área de trabalho e Cowork troca cada caminho por conteúdo base64 no lugar antes de encaminhar a chamada.

O aninhamento é percorrido até uma profundidade de quatro níveis abaixo do topo do inputSchema. $ref Os ponteiros não são seguidos — defina os parâmetros do ficheiro em linha em vez de atrás de um $ref.

O que o seu servidor recebe

Seu servidor recebe um ordinário tools/call com seus nomes de parâmetros originais preenchidos com conteúdo codificado em base64:

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

O servidor não precisa saber que o agente usou uma interface baseada em caminho e as ferramentas que não declaram parâmetros contentEncoding: base64 não são afetadas.

Limits

Limit	Valor
Ficheiros por chamada de ferramenta	8
Tamanho por ficheiro	150 MiB
Tamanho total por chamada de ferramenta	150 MiB
Parâmetros do ficheiro de array por ferramenta	1 (combiná-lo com qualquer número de parâmetros de ficheiro escalar)
Profundidade máxima de nidificação	4 níveis abaixo do topo de inputSchema

Uma chamada que excede a contagem de ficheiros ou um limite de tamanho falha com um erro de ferramenta e nunca chega ao servidor. Dimensione a sua API e os seus tempos limite com o teto de 150 MiB em mente: o base64 infla a carga útil em aproximadamente um terço em relação ao tamanho do ficheiro bruto, e o conteúdo codificado é enviado no corpo do pedido JSON-RPC.

Recommendations

• Descreva o parâmetro para um leitor humano. O agente usa a descrição para decidir qual ficheiro pertence a qual parâmetro. Por exemplo, "The signed contract PDF to analyze" funciona melhor do que "file".
• Indique os formatos aceitos na descrição do parâmetro. O Cowork transmite tudo o que o utilizador anexar. Valide o tipo de conteúdo do seu lado e devolva um erro de ferramenta claro se não for utilizável.
• Definir anotações. Uma ferramenta que recebe um ficheiro e atua sobre o mesmo normalmente não é só de leitura, pelo que pede uma confirmação. Saiba mais em Gestão de anotações e confirmações MCP.
• Mantenha os parâmetros do ficheiro em linha. Um parâmetro atrás de um $ref, ou aninhado com profundidade superior a quatro níveis, não é reescrito. O servidor receberia uma cadeia de carateres de caminho onde esperaria conteúdo.
• Declare no máximo um parâmetro de arquivo de matriz por ferramenta. Com dois ou mais, o Cowork não consegue saber que ficheiro pertence a que array, e a chamada falha com um erro de ferramenta. Utilize um array, vários parâmetros escalares ou uma combinação de escalares e um único array.
• Espere uma contagem exata de ferramentas apenas escalares. Se a ferramenta declarar apenas parâmetros escalares de ficheiro, o número de ficheiros que o agente passa deve corresponder ao número declarado. Marque claramente os parâmetros de ficheiro opcionais nas descrições para que o agente não forneça nem a menos nem a mais.

Note

Esse mecanismo é anterior ao trabalho de entrada de arquivos do Protocolo de Contexto do Modelo, que está sendo padronizado pelo Grupo de Trabalho de Uploads de Arquivos MCP. Cowork pode adicionar suporte para a forma padronizada de entradas de arquivo declarativas assim que ela chegar. O contentEncoding: base64 contrato aqui descrito continua a funcionar.

Identificar Cowork tráfego para o servidor

Se o seu servidor MCP controla a visibilidade das ferramentas por cliente, ou se pretender atribuir a origem do tráfego que recebe, pode identificar pedidos provenientes do Cowork. Cowork apresenta uma identidade de software estável em dois canais:

Channel	Onde aparece	Valor
User-Agent cabeçalho da solicitação	Todos os pedidos de saída que o Cowork envia para o seu servidor	copilot-cowork/1.0
clientInfo no handshake do MCP initialize	Apenas o pedido initialize	{ "name": "copilot-cowork", "version": "<version>" }

Corresponder ao prefixo copilot-cowork

Corresponda ao prefixo, não sensível às maiúsculas copilot-cowork e minúsculas, em qualquer um dos canais. Não correspondam à cadeia exata copilot-cowork/1.0 ou a um clientInfo.versionficheiro . A versão acompanha o contrato de identidade do cliente e espera-se que mude; uma correspondência por prefixo mantém o seu gateway a funcionar em todas as mudanças de versão.

# Correct: case-insensitive prefix match
copilot-cowork

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

Escolha o canal certo para o seu portão

Os dois canais têm alcances diferentes, por isso baseie-se naquele que corresponde à forma como o seu servidor aplica o respetivo mecanismo de controlo de acesso:

• O User-Agent cabeçalho está presente em todas as solicitações, incluindo tools/list e tools/call. Se controla o acesso ou atribui por pedido, baseie-se neste cabeçalho.
• clientInfo é enviado apenas no initialize handshake. Se você restringir por sessão no momento da conexão, você pode lê-lo lá, mas não será repetido em solicitações posteriores.

O que a identidade inclui e não inclui

A identidade apenas nomeia o software . É o mesmo para todos os utilizadores e ligações do Cowork, e nunca transporta a identidade do utilizador. A identidade do utilizador permanece no fluxo de autorização definido pela configuração de autenticação do conector.

A identidade inclui	A identidade não inclui
Um nome de software estável (copilot-cowork) e uma versão de consenso	Qualquer identificador de locatário, utilizador, sessão ou conversa
O mesmo valor em cada solicitação e em cada ligação	Um qualificador por conector

Como não há qualificador por conector, atualmente não é possível usar essa identidade para saber qual conector fez uma chamada ou para separar um plug-in da Microsoft publicado de um servidor carregado lateralmente apontado para a mesma URL. Se precisar dessa distinção, impeça-a através da configuração de autorização do conector em vez da identidade do cliente.

Perguntas frequentes

Posso usar habilidades do pacote M365 no Claude Code?

Yes. As pastas de competências contêm competências padrão do agente. Execute wiqd plugin export --format claude-plugin para produzir o layout do Claude Code ou copie as pastas de skills para .claude/skills/ em qualquer projeto do Claude Code.

Preciso de um Remote Connector?

No. Os pacotes apenas de competências adequam-se bem a fluxos de trabalho assentes em prompts. Os conectores só são necessários quando a sua skill requer dados dinâmicos de um sistema externo.

Em que diferem as skills de plug-in das skills incorporadas?

As habilidades de plug-in aparecem com o código-fonte "package" na API. Não podem sobrepor-se às competências predefinidas com o mesmo nome. Os pacotes implantados pelo administrador mostram isAdminDeployed: true.

Os administradores de TI podem controlar quais plug-ins estão disponíveis?

Yes. Aplicam-se controlos de administrador padrão do M365: listas de permissões/bloqueios ao nível do inquilino, implementações geridas pelo administrador e políticas de conformidade.

O que acontece se um plug-in for revogado?

No ciclo de sincronização seguinte, as competências e os conectores desse pacote são removidos da sessão do utilizador. As conversações ativas não são interrompidas, mas as novas sessões não têm as funcionalidades do pacote.

Qual é o número máximo de competências por pacote?

Vinte (20) competências (por ASKILL-M002). Para conectores, o limite é de 10 por pacote.

As competências podem referenciar ferramentas de conexão do mesmo pacote?

Sim, e eles deveriam. Mencione explicitamente as ferramentas no seu fluxo de trabalho SKILL.md (por exemplo, "Utilize a ferramenta search_case_law para..."). O agente liga-os em tempo de execução.

As ferramentas do meu plugin podem aceitar ficheiros do espaço de trabalho Cowork?

Yes. Declare o parâmetro tool com contentEncoding: base64, e Cowork resolve o arquivo de espaço de trabalho do usuário para o conteúdo base64 antes de chamar o servidor. O modelo passa caminhos de ficheiro, não conteúdo de ficheiro, pelo que os ficheiros grandes não consomem o contexto do modelo. Para obter detalhes e limites da declaração, saiba mais em Aceitar ficheiros a partir do espaço de trabalho Cowork.

Como devo proceder para gerar um GUID determinístico para o meu pacote?

wiqd plugin create gera e afixa o ID da aplicação automaticamente. O script de conversão usa UUID v5 (baseado em SHA-1) do nome do seu plugin, portanto, executar a conversão duas vezes produz o mesmo GUID. Para empacotamento manual, use qualquer gerador de GUID. Certifique-se de que o mantém estável em todas as versões.

Que versão do manifesto devo visar?

Use a versão 1.29 como alvo se estiver a compilar com o wiqd, que a fixa por si. Em 1.29, agentConnectors[] as entradas são apenas URL e mcpToolDescription é opcional. Os exemplos criados à mão neste artigo utilizam 1.28, onde mcpToolDescription é obrigatório, e o ficheiro que nomeia tem de estar no ZIP. atk import openplugin usa UUID v5 (baseado em SHA-1) do nome do seu plugin. Executar a importação duas vezes produz o mesmo GUID. Para definir o seu, forneça --app-id. Para empacotamento manual, use qualquer gerador de GUID. Certifique-se de que o mantém estável em todas as versões.

Conteúdo relacionado

• Visão geral do Cowork
• Usar Cowork
• Gerir Cowork para a sua organização
• Gerir plug-ins do Cowork
• Referência da CLI do plug-in wiqd