Criar plug-ins para o Copilot Cowork

Microsoft Copilot Cowork dá suporte à extensibilidade por meio de pacotes de aplicativos do M365, o mesmo mecanismo de distribuição usado por aplicativos do Teams, agentes do Copilot e suplementos do Office. Você pode estender o 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 fornecem aos Cowork acesso a fontes de dados externas e APIs.

Ambos são empacotados juntos em um pacote de aplicativo padrão do Microsoft 365 e distribuídos pela Microsoft 365 App Store.

A Microsoft não cria ou mantém nenhum índice persistente, gráfico de conhecimento (incluindo o Microsoft Graph) ou banco de dados que inclua Conteúdo ISV, seja por rastreamento, coleta, exportação em massa, ingestão ou qualquer outro método (via API, servidor MCP ou outro). Microsoft pode processar temporariamente o Conteúdo ISV conforme necessário para responder à consulta em tempo real de um usuário, mas não retém o conteúdo ISV além da duração dessa sessão. Mediante solicitação por escrito do ISV, a Microsoft exclui qualquer Conteúdo do ISV em sua posse ou controle dentro de 10 dias úteis e certifica essa exclusão por escrito. Saiba mais em Proteção de dados empresariais em Microsoft Copilot e Microsoft Copilot Chat.

O que você vai construir

Um plugin do 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, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie e mais de 30 ferramentas de IA.

Escolha o ponto de partida

Crie seu plug-in com o wiqd CLI. A CLI cria um scaffolding do pacote e mantém manifest.json suas pastas de habilidades em sincronia. Ele também executa as próprias regras de validação da plataforma antes de fazer o upload e, em seguida, provisiona e compartilha o resultado. A CLI está em versão prévia, portanto, seus comandos e saída gerada podem mudar antes da disponibilidade geral. Tudo o que ele gera é um pacote simples do aplicativo Microsoft 365, para que você ainda possa abrir, editar e controlar a versão dos arquivos diretamente.

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

Crie um plugin com wiqd

A CLI wiqd executa o mesmo ciclo de vida que você faz manualmente: criar, adicionar recursos, validar, provisionar, empacotar e compartilhar. O pacote produzido já atende às regras de validação neste artigo.

Etapa 1: instalar o wiqd e entrar

Instale a CLI do wiqd seguindo o guia de instalação do wiqd, que abrange Windows, macOS e Linux. Em seguida, entre no locatário do Microsoft 365 no qual você está desenvolvendo, pois o provisionamento e o compartilhamento tocam seu locatário:

wiqd auth login --interactive

O instalador também registra um plug-in da CLI do GitHub Copilot, para que você possa conduzir o mesmo ciclo de vida conversacionalmente. Por exemplo, você pode dizer, Crie um plugin autônomo chamado Triage Helper ou Valide meu plugin. O caminho de conversa executa os mesmos comandos desta seção. Use os comandos diretamente quando estiver criando scripts de um pipeline ou quiser automação reproduzível e não interativa.

Etapa 2: criar o plug-in e adicionar recursos

Crie o contêiner de plug-ins e adicione os recursos necessários, 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 scaffolds appPackage/skills/contract-analysis/SKILL.md e os registra em agentSkills[]. add connector grava a agentConnectors[] entrada. Ambos os comandos impõem a nomenclatura e os limites de tamanho da plataforma antes de gravar, para que uma incompatibilidade de nome de pasta ou um comprimento id excessivo nunca atinja o manifesto.

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

Etapa 3: validar ao compilar

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

wiqd plugin validate
wiqd plugin validate --mode deep

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

Etapa 4: provisionar, empacotar e compartilhar

Execute estes três comandos na ordem:

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

Execute provision primeiro porque ele grava o arquivo de ambiente do qual package e share ambos dependem. Use --scope users para compartilhar com as pessoas listadas ou --scope tenant para compartilhar com todos em sua organização. De qualquer forma, o plug-in aparece em Compartilhado comigo em Cowork>Fontes & Plug-ins de habilidades>. Para listá-lo na seção Descobrir , em vez disso, um administrador carrega o pacote. Saiba mais em Etapa 8: Publicar em seu locatário. Para remover o que foi provision criado, execute wiqd plugin delete --env local --yes.

O envio de repositório público ainda é um processo manual no Partner Center. Saiba mais em Etapa 9: publicar para o público.

Levar um plug-in para outro host

Para usar suas habilidades no Código Claude, Cursor ou qualquer outro host de Habilidades do Agente, exporte o projeto em vez de copiar pastas manualmente:

wiqd plugin export --format claude-plugin

export O padrão é e --format open-plugin também aceita cursor-plugin. Ele grava um diretório descompactado em <path>/export/<format>.

Importar um plug-in existente

Se você já tiver um plug-in do Claude Code com habilidades e servidores MCP, terá duas rotas de conversão. O caminho escolhido depende se você planeja continuar desenvolvendo o plug-in ou apenas enviar o que você tem.

Importar com wiqd

wiqd plugin importreconhece uma fonte de plug-in Open, plug-in Claude ou plug-in de cursor e produz um projeto de plug-in wiqd a partir dele. O plug-in importado une o mesmo ciclo de vida que você 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 necessários apenas na primeira importação de um plug-in. Se a fonte veio de um anterior wiqd plugin export, os metadados de ida e volta já os carregam.

Converter com o script de conversão

O script de conversão traduz um plug-in do Claude diretamente em um pacote do 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 seu plug-in:

   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 .claude-plugin/plugin.json diretório (ou .cursor-plugin/plugin.json), .mcp.jsone skills/ do seu plug-in e, em seguida, cria um projeto do Agents Toolkit contendo appPackage/manifest.json, suas habilidades e ícones gerados.

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

Empacotar o resultado em um arquivo :.zip

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

O que é importado

O que não é convertido

Os seguintes recursos do plug-in de Claude ainda não têm suporte no manifesto do Microsoft 365:

Opções de importação

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

Se a detecção automática não corresponder à sua configuração, use --default-auth-type para substituí-la.

Exportar de volta para um diretório de plug-in

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

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

A exportação grava um x-microsoft-365-agents-toolkit bloco no arquivo .plugin.json Esse bloco carrega o manifesto id, URLs de desenvolvedor e configurações de conector, portanto, uma viagem de ida e volta posterior atk import openplugin sem precisar --privacy-url ou --terms-url novamente.

Herdado: script de conversão do PowerShell

Antes da atk importação de plug-in com suporte, a conversão usava um script do PowerShell somente Windows, que permanece disponível como o script de conversão:

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

Use atk import openplugin em seu lugar. É multiplataforma, oferece suporte a fontes Cursor e Claude Code e pode exportar de volta para um diretório de plug-ins.

Montar um pacote manualmente

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 criando seu próprio pipeline de empacotamento. Use-o como referência quando precisar entender ou depurar um pacote gerado.

Etapa 1: Criar sua primeira habilidade

Uma habilidade é uma pasta que contém um SKILL.md arquivo. 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 de frontmatter

Campos necessários:

Regras de nomenclatura (kebab-case): Use apenas caracteres alfanuméricos minúsculos e hifens. Não use hifens consecutivos e não use hifens à esquerda ou à direita.

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

Para habilidades complexas, mantenha o lean principal SKILL.md e mova o conteúdo detalhado para subdiretórios. Esses arquivos extras são arquivos complementares. A habilidade os carrega 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 de arquivos complementares

Cada habilidade pode incluir até 20 arquivos complementares (qualquer arquivo diferente de SKILL.md). Os seguintes limites se aplicam por habilidade:

Regras de arquivos complementares

Os caminhos de arquivo complementares devem seguir estas regras:

• Use apenas caminhos relativos (sem caminhos absolutos).
• Nenhuma travessia de caminho (.. segmentos).
• Nenhuma barra invertida ou bytes nulos em nomes de arquivo.
• Não há arquivos ocultos (nomes começando com .).
• Não há nomes reservados do Windows (CON, PRN, AUXCOM1NUL, –COM9, –). LPT1LPT9
• O arquivo SKILL.md em si não conta como um arquivo complementar.
• Os nomes de arquivo devem usar caracteres seguros: alfanuméricos, hífens, sublinhados, pontos, espaços e !.

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

Faça referência aos subdiretórios explicitamente para SKILL.md 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

Etapa 3: Adicionar um conector (opcional)

Se sua extensão precisar de acesso a dados externos, adicione um servidor MCP remoto. Esta etapa é opcional. Os pacotes somente de habilidades funcionam bem para fluxos de trabalho baseados em prompt.

Requisitos do conector

Diretrizes de design de ferramentas

• Uma ferramenta por ação para APIs pequenas (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 é o que o agente lê
• Saída estruturada: JSON de retorno que o agente pode formatar para o usuário
• 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 arquivos do espaço de trabalho do Cowork.

Descreva as ferramentas do conector (mcpToolDescription)

Opcionalmente, um remoteMcpServer conector pode incluir um mcpToolDescription objeto. Quando fornecida, sua propriedade aninhada aponta para um arquivo JSON tool-description que você empacota dentro de seu .zip e referencia file por um caminho relativo da raiz do pacote. O Cowork descobre ferramentas dinamicamente 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 você incluir mcpToolDescription, o arquivo referenciado (por exemplo, tools/contoso-legal-tools.json) descreve as ferramentas que o conector expõe e devem estar presentes no pacote ZIP. Inclua-o junto com sua manifest.json pasta and skills/ ao empacotar o plug-in.

Tipos de autenticação com suporte

Para OAuthPluginVault e ApiKeyPluginVault, os referenceId pontos para as credenciais armazenadas no Microsoft Enterprise Token Store - os segredos nunca aparecem nos arquivos de manifesto ou de habilidade. O referenceId valor é a ID de registro do cliente OAuth que você cria ao registrar um cliente OAuth com o Agents Toolkit.

Autenticação MCP

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

Registro dinâmico do cliente

Se o servidor MCP der suporte a Registro dinâmico de clientes (DCR), você poderá omitir uma authentication configuração da definição do conector e Cowork criará automaticamente um cliente OAuth em nome do plug-in.

Você pode omitir o authorization objeto inteiramente. Configure a URL do servidor MCP e Cowork cuidará do cliente OAuth:

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

Etapa 4: criar o manifesto

Crie manifest.json na raiz do pacote. O exemplo usa o manifesto versão 1.28; wiqd plugin create pinos 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 a ID de registro do OAuth. Se você incluir mcpToolDescription, ele file deverá apontar para um arquivo JSON de descrição da ferramenta incluído no pacote ZIP.

Etapa 5: adicionar ícones

Crie dois ícones PNG:

Se você ainda não tiver ícones, atk import openplugin gera espaços reservados de cor sólida. Substitua-os antes do envio à loja.

Etapa 6: Pacote

Crie um arquivo ZIP com todo o conteúdo no nível raiz. wiqd plugin package( produz esta mesma estrutura depois wiqd plugin provisionde .)

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 tool-description que ele referencia. Os pacotes que não usam mcpToolDescription, incluindo pacotes somente de habilidades, 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/

Usando o Kit de Ferramentas de Agentes do Microsoft 365

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

Etapa 7: teste

Para testar seu aplicativo, carregue seu pacote de aplicativos no Teams conforme descrito em Carregue seu aplicativo no Teams.

Se você criou o plug-in com wiqd, execute wiqd plugin provision em vez disso, ele registra o plug-in com seu locatário para você. Para testes pessoais de um pacote montado à mão, faça o sideload do aplicativo usando a interface de linha de comando do Kit de Ferramentas de Agentes do Microsoft 365:

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 sua conta corporativa do Microsoft 365:

   atk auth login
   

4. Entre em sua conta corporativa e instale o pacote do agente. Substitua o caminho do arquivo pelo local do 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 sua conta.

5. Salve essas IDs para uso posterior ao atualizar ou desinstalar.

Saiba mais na interface de linha de comando do Kit de Ferramentas de Agentes do Microsoft 365.

Etapa 8: Publicar em seu locatário

Carregue o pacote no centro de administração para listar o plug-in na seção Descobrir , onde qualquer pessoa em sua organização pode encontrá-lo:

1. Abra o centro >de administração do M365Gerenciar aplicativosCarregar aplicativo> personalizado.
2. Selecione o botão de reticências (...) >Adicionar agente.
3. Carregue seu .zip pacote.
4. Abra Cowork>Fontes & Plug-ins de habilidades>. Seu plug-in aparece na seção Descobrir .

wiqd plugin share coloca o plug-in em Compartilhado Comigo em vez de Descobrir. Use-o para testes e distribuição direcionada a pessoas específicas. Administração upload do centro é o que lista um plug-in para descoberta.

Etapa 9: Publicar para o público

Para plug-ins destinados à distribuição pública, envie seu plug-in para a Microsoft 365 App Store por meio do Partner Center. Saiba mais em Publicar agentes para o Microsoft 365 Copilot.

Testar um conector em um servidor MCP local

Os conectores exigem um atributo HTTPS mcpServerUrl. Para testar um servidor em execução em seu computador, você precisa expô-lo por meio de uma URL HTTPS pública. Os túneis de desenvolvimento fornecem uma retransmissão que encerra o TLS para você.

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

Troubleshooting

Padrões de embalagem

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

Somente habilidades (sem conector)

Ideal para fluxos de trabalho baseados em prompts, análise de documentos e assistência de redação.

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

Habilidades + 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

Somente conector (sem habilidades personalizadas)

Use esta opção para fontes de dados que as habilidades internas do Cowork já podem usar.

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

Código Claude importado ou plug-in de cursor

Use esta opção para plug-ins existentes do ecossistema Claude direcionados ao Cowork. Para continuar desenvolvendo 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 um publicável .zip a partir do plug-in como está hoje, 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

Práticas recomendadas de criação de habilidades

Siga estas diretrizes para criar habilidades que são ativadas de forma confiável e produzem resultados consistentes.

Escreva descrições efetivas

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.

Escreva fluxos de trabalho eficazes

• Seja específico na descrição. Inclua frases de gatilho: "Use quando o usuário pedir..." Essa descrição é como o agente decide qual habilidade ativar.
• Estrutura como um fluxo de trabalho. Numere as etapas. Cada etapa deve mapear para uma ação concreta (ler um arquivo, chamar uma ferramenta, gerar saída).
• Defina o formato de saída. Mostre a estrutura exata de tabela, lista ou documento que os usuários devem esperar. Essa definição melhora drasticamente a consistência.
• Ferramentas de referência por nome. Se sua habilidade depender de ferramentas de conector, nomeie-as explicitamente: "Use a search_case_law ferramenta para..."
• Mantenha o SKILL.md principal enxuto. Mova o material de referência detalhada para o references/ subdiretório. O corpo da habilidade deve ser o fluxo de trabalho, não uma enciclopédia.

Evitar erros comuns

• Não insira segredos em SKILL.md arquivos. Use agentConnectors com autenticação para credenciais de API.
• Não duplique habilidades internas. Verifique a lista de habilidades internas antes de criar.
• Não torne as habilidades muito 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 arquivo ou comandos do sistema. As habilidades devem ser portáteis entre ambientes.
• Não coloque tudo no SKILL.md. Se o corpo exceder ~3.000 palavras, mova o conteúdo detalhado para references/.

Regras de validação

Quando você envia seu pacote, a plataforma o valida em vários níveis. Corrija esses erros antes do envio para evitar a rejeição.

Para capturá-los enquanto você cria em vez de no momento do upload, execute wiqd plugin validate --mode deep. Esse comando empacota o plug-in e executa essas mesmas regras localmente. Saiba mais na Etapa 3: validar à medida que você cria.

Validação no nível do manifesto

Validação no nível do pacote

Validação do conector

Validação de arquivo complementar

O portal valida arquivos complementares (materiais de referência, scripts e outros arquivos ao lado SKILL.md) no momento do upload e da sincronização:

Compatibilidade entre plataformas

As habilidades usam o padrão aberto Agent Skills. Os mesmos SKILL.md arquivos funcionam em várias ferramentas de IA:

Se você estiver desenvolvendo habilidades para o Claude Code e o Copilot Cowork, crie o plug-in com o wiqd. Em seguida, execute wiqd plugin export --format claude-plugin para produzir o layout do Código Claude. Se você preferir começar a partir da estrutura do plug-in do Código Claude - é o superconjunto - o 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)

Em seguida, traga-o para o Microsoft 365 quando estiver pronto para publicar na 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

Gerenciamento de anotação e confirmação de MCP

O Copilot Cowork lê o objeto MCP annotations padrão nas ferramentas das quais seu servidor retorna e o usa para decidir se uma chamada de ferramenta precisa de tools/listconfirmação do usuário e qual rótulo mostrar no prompt.

Campos disponíveis

Regras de confirmação

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

Todas as ferramentas devem ter as anotações de segurança especificadas. Ferramentas sem anotações são tratadas como destrutivas e exigem confirmação. Saiba mais na referência do 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 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) são controladas pela política interna do Cowork, independentemente das anotações.
• Para servidores MCP que não são da Microsoft, a confirmação controlada por anotação está sendo implementada progressivamente. A definição das dicas agora é compatível com versões anteriores, e os prompts de confirmação são exibidos à medida que a distribuição se expande sem a necessidade de alteração de desenvolvedor.

Aceitar arquivos do espaço de trabalho do Cowork

Uma ferramenta de conector pode usar um arquivo da sessão do Cowork do usuário como entrada - um documento que o usuário anexou, um anexo de email que o Cowork salvou ou um arquivo produzido por uma etapa anterior. Declare o parâmetro com o palavra-chave contentEncoding: base64 de esquema JSON padrão e Cowork lida com o resto. Nenhuma extensão de esquema específica da Microsoft é necessária, e a superfície de API do servidor não é alterada.

Cowork resolve o arquivo do espaço de trabalho e codifica-o em base64 antes de chamar o servidor, para que os bytes do arquivo nunca entrem no contexto do agente. O agente só vê e emite caminhos de arquivo do espaço de trabalho.

Declarar um parâmetro de arquivo

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 parâmetros de arquivo declarados no nível superior do inputSchema.properties, o Cowork os substitui no esquema voltado para o modelo por uma única direct_attachment_file_paths matriz, o mesmo parâmetro que as ferramentas internas do Cowork usam, para que o agente já saiba como preenchê-lo. 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 sua ferramenta declarar mais de um parâmetro de arquivo de nível superior, todos eles serão recolhidos nessa única direct_attachment_file_paths matriz. No momento da chamada, o Cowork ventila os arquivos resolvidos de volta para seus nomes de parâmetros originais na ordem da declaração.

Parâmetros de arquivo aninhados

O agente dá suporte a um parâmetro de arquivo aninhado dentro de um objeto ou de uma matriz de objetos. O agente lida com esse parâmetro de maneira diferente: em vez de recolhê-lo, o agente o regrava em um local em uma cadeia de caracteres de caminho em seu próprio local. Essa abordagem preserva a associação entre um arquivo e seus campos irmãos. Por exemplo, você 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 de espaço de trabalho e o Cowork troca cada caminho por conteúdo base64 no local antes de encaminhar a chamada.

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

O que 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"
    }
  }
}

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

Limits

Uma chamada que excede a contagem de arquivos ou um limite de tamanho falha com um erro de ferramenta e nunca chega ao servidor. Dimensione sua API e seus tempos limite com o teto de 150 MiB em mente: base64 aumenta a carga em aproximadamente um terço sobre o tamanho do arquivo bruto e o conteúdo codificado é enviado no corpo da solicitação JSON-RPC.

Recommendations

• Descreva o parâmetro para um leitor humano. O agente usa a descrição para decidir qual arquivo 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. Cowork passa por tudo o que o usuário anexa. Valide o tipo de conteúdo do seu lado e retorne um erro de ferramenta claro se ele não for utilizável.
• Definir anotações. Uma ferramenta que recebe um arquivo e age sobre ele normalmente não é somente leitura, portanto, solicita confirmação. Saiba mais em Gerenciamento de anotações e confirmações de MCP.
• Mantenha os parâmetros do arquivo embutidos. Um parâmetro por trás de um $ref, ou aninhado em mais de quatro níveis, não é reescrito. Seu servidor receberia uma cadeia de caracteres de caminho onde espera conteúdo.
• Declare no máximo um parâmetro de arquivo de matriz por ferramenta. Com dois ou mais, o Cowork não consegue dizer qual arquivo pertence a qual matriz e a chamada falha com um erro de ferramenta. Use uma matriz, ou vários parâmetros escalares, ou uma combinação de escalares e uma única matriz.
• Espere uma contagem exata em ferramentas apenas escalares. Se a ferramenta declarar apenas parâmetros de arquivo escalares, o número de arquivos que o agente passa deverá corresponder ao número declarado. Marque os parâmetros de arquivo opcionais claramente em suas descrições para que o agente não forneça excesso ou excesso de oferta.

Identificar o tráfego do Cowork para o seu servidor

Se o seu servidor MCP tem visibilidade da ferramenta por cliente, ou você deseja atribuir o tráfego que ele recebe, você pode reconhecer as solicitações que vêm do Cowork. O Cowork apresenta uma identidade de software estável em dois canais:

Corresponder no prefixo copilot-cowork

Corresponda ao prefixocopilot-cowork, sem diferenciar maiúsculas de minúsculas, em qualquer canal. Não correspondam à cadeia de caracteres exata copilot-cowork/1.0 ou a um .clientInfo.version A versão rastreia o contrato de identidade do cliente e espera-se que mude; Uma correspondência de prefixo mantém seu portão funcionando em colisões 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 escopos diferentes, portanto, escolha aquele que corresponde à forma como seu servidor impõe seu portão:

• O User-Agent cabeçalho está presente em todas as solicitações, incluindo tools/list e tools/call. Se você bloquear ou atribuir por solicitação, digite esse cabeçalho.
• clientInfo é enviada somente no initialize handshake. Se você fizer o gate por sessão no momento da conexão, poderá lê-lo lá, mas não será repetido em solicitações posteriores.

O que a identidade inclui e o que não inclui

A identidade nomeia apenas o software . É o mesmo para todos os usuários e conexões do Cowork, e nunca carrega a identidade do usuário. A identidade do usuário permanece no fluxo de autorização definido pela configuração de autenticação do conector.

Como não há qualificador por conector, não é possível usar essa identidade no momento para saber qual conector fez uma chamada ou para separar um plug-in publicado da Microsoft de um servidor de sideload apontado para a mesma URL. Se você precisar dessa distinção, aplique-a por meio da configuração de autorização do conector, em vez da identidade do cliente.

Perguntas comuns

Posso usar as habilidades do pacote M365 no Claude Code?

Sim. As pastas de habilidades contêm habilidades padrão do agente. Execute wiqd plugin export --format claude-plugin para produzir o layout do Código Claude ou copie as pastas de habilidades em .claude/skills/ qualquer projeto do Código Claude.

Preciso de um conector remoto?

No. Os pacotes somente de habilidades funcionam bem para fluxos de trabalho baseados em prompt. Os conectores só são necessários quando sua habilidade requer dados dinâmicos de um sistema externo.

Como as habilidades de plug-in são diferentes das habilidades internas?

As habilidades de plug-in são exibidas com a fonte "package" na API. Elas não podem substituir as habilidades internas de mesmo nome. Administração pacotes implantados mostram isAdminDeployed: true.

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

Sim. Os controles de administrador do M365 Standard se aplicam: listas de permissões/bloqueios em nível de locatário, implantações gerenciadas pelo administrador e políticas de conformidade.

O que acontece se um plug-in for revogado?

No próximo ciclo de sincronização, as habilidades e conectores desse pacote são removidos da sessão do usuário. As conversas ativas não são interrompidas, mas as novas sessões não têm os recursos do pacote.

Qual é o número máximo de habilidades por pacote?

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

As habilidades podem fazer referência a ferramentas do conector do mesmo pacote?

Sim, e deveriam. Nomeie as ferramentas explicitamente em seu SKILL.md fluxo de trabalho (por exemplo, "Use a search_case_law ferramenta para..."). O agente os conecta em tempo de execução.

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

Sim. Declare o parâmetro tool com contentEncoding: base64e Cowork resolve o arquivo do espaço de trabalho do usuário para conteúdo base64 antes de chamar o servidor. O modelo passa caminhos de arquivo, não conteúdo de arquivo, para que arquivos grandes não consumam o contexto do modelo. Para detalhes e limites da declaração, saiba mais em Aceitar arquivos do espaço de trabalho do Cowork.

Como fazer gerar um GUID determinístico para meu pacote?

wiqd plugin create gera e fixa a ID do aplicativo para você. O script de conversão usa UUID v5 (baseado em SHA-1) do nome do plug-in, portanto, executar a conversão duas vezes produz o mesmo GUID. Para empacotamento manual, use qualquer gerador de GUID. Certifique-se de mantê-lo estável em todas as versões.

Qual versão de manifesto devo direcionar?

Destino 1,29 se você estiver construindo com wiqd, que o fixa para você. Na versão 1.29, agentConnectors[] as entradas são somente URL e mcpToolDescription são opcionais. Os exemplos criados manualmente neste artigo usam 1.28, onde mcpToolDescription é necessário e o arquivo que ele nomeia deve estar no ZIP. atk import openplugin usa UUID v5 (baseado em SHA-1) do nome do plug-in. Executar a importação duas vezes produz o mesmo GUID. Para definir o seu próprio, passe --app-id. Para empacotamento manual, use qualquer gerador de GUID. Certifique-se de mantê-lo estável em todas as versões.

Conteúdo relacionado

• Visão geral Cowork
• Usar o Cowork
• Gerenciar o Cowork para sua organização
• Gerir plugins para o Cowork
• Referência da CLI do plugin wiqd