Crear complementos para Copilot Cowork

Se aplica a: Microsoft Copilot

Microsoft Copilot Cowork admite la extensibilidad a través de paquetes de aplicaciones M365, el mismo mecanismo de distribución que usan las aplicaciones de Teams, los agentes de Copilot y los complementos de Office. Puedes ampliar Cowork con:

Habilidades: flujos de trabajo basados en mensajes que enseñan a Cowork nuevos conocimientos de dominio, como el análisis financiero, la investigación legal o los flujos de trabajo de recursos humanos.
Conectores: servidores remotos que dan a Cowork acceso a fuentes de datos externas y APIs.

Ambos se empaquetan juntos en un paquete de aplicaciones estándar de Microsoft 365 y se distribuyen a través de Microsoft 365 App Store.

Importante

Las barreras de información (IB) de Microsoft Purview no se admiten actualmente para la administración y el uso compartido de complementos ni habilidades. En los inquilinos donde IB está habilitado, las cargas de archivos de conocimiento insertados se bloquean en el nivel de inquilino. Esto evita que se carguen o publiquen complementos y habilidades afectados.

Microsoft no crea ni mantiene ningún índice persistente, gráfico de conocimiento (incluido Microsoft Graph) o base de datos que incluya contenido de ISV, ya sea mediante rastreo, extracción, recolección, exportación masiva, ingesta o cualquier otro método (a través de API, servidor MCP o de otro modo). Microsoft puede procesar temporalmente el contenido de ISV según sea necesario para responder a la consulta en tiempo real de un usuario, pero no conserva el contenido de ISV más allá de la duración de esa sesión. Previa solicitud por escrito de ISV, Microsoft elimina cualquier Contenido de ISV en su posesión o control en un plazo de 10 días laborables y certifica dicha eliminación por escrito. Obtenga más información sobre la protección de datos empresariales en Microsoft Copilot y Microsoft Copilot Chat.

Lo que vas a construir

Un complemento de Cowork es un .zip paquete que contiene:

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

Las Skills usan el estándar abierto Agent Skills, el mismo formato admitido por Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie y más de 30 herramientas de IA.

Elija el punto de partida.

Cree su complemento con la CLI de wiqd. La CLI aplica scaffolding al paquete y mantiene manifest.json y tus carpetas de habilidades sincronizados. También ejecuta las propias reglas de validación de la plataforma antes de subirlo, luego aprovisiona y comparte el resultado. La CLI está en versión preliminar, por lo que sus comandos y la salida generada pueden cambiar antes de la disponibilidad general. Todo lo que genera es un paquete de aplicación de Microsoft 365 sencillo, por lo que puede abrir, editar y versionar los archivos directamente.

Monte el paquete manualmente solo cuando no pueda instalar herramientas o cuando esté creando su propia canalización de empaquetado. En ese caso, la referencia de formato de paquete de este artículo es lo que necesita: describe exactamente lo que wiqd produce.

Punto de partida	Haga lo siguiente	Tiempo transcurrido hasta el primer paquete
Empiezo desde cero	Crear un complemento con wiqd	unos 10 minutos
Tengo un complemento existente de Claude Code	Conviértelo	unos 5 minutos
No puedo instalar herramientas o escribo scripts de mi propio empaquetado	Ensamblar un paquete a mano	unos 30 minutos

Crear un complemento con wiqd

La CLI de wiqd ejecuta el mismo ciclo de vida que de otro modo manualmente: crear, agregar funcionalidades, validar, aprovisionar, empaquetar y compartir. El paquete que genera ya satisface las reglas de validación de este artículo.

Instale la CLI de wiqd siguiendo la guía de instalación de wiqd, que cubre Windows, macOS y Linux. Después, inicie sesión en el tenant de Microsoft 365 con el que está desarrollando, ya que el aprovisionamiento y la compartición afectan a su tenant:

wiqd auth login --interactive

El instalador también registra un complemento de la CLI de GitHub Copilot, por lo que puede controlar el mismo ciclo de vida de forma conversacional. Por ejemplo, puedes decir: Crea un plugin independiente llamado Triage Helper o Validar mi plugin. La ruta de conversación ejecuta los mismos comandos que en esta sección. Use los comandos directamente cuando esté creando scripts de una canalización o desee una automatización reproducible y no interactiva.

Paso 2: Estructurar el complemento y agregar capacidades

Crea el contenedor del plugin y añade las capacidades que necesites, en cualquier combinación:

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 estructura appPackage/skills/contract-analysis/SKILL.md y lo registra en agentSkills[]. add connector escribe la entrada agentConnectors[]. Ambos comandos aplican los límites de nomenclatura y tamaño de la plataforma antes de escribir, por lo que una falta de coincidencia entre el nombre de la carpeta y un id demasiado largo nunca llega al manifiesto.

Escriba la lógica de la skill en el SKILL.md generado. Los campos de metadatos, el modelo de carga progresiva y los límites de los archivos complementarios son los mismos que se describen en Paso 1: Crear la primera capacidad y Paso 2: Agregar materiales de referencia (opcional).

Importante

wiqd plugin create ancla el paquete a manifestVersion: "1.29", mientras que los ejemplos creados manualmente en este artículo usan 1.28. La diferencia es importante para los conectores. En la versión 1.28, mcpToolDescription es obligatorio, y el archivo al que hace referencia debe estar en el archivo ZIP. En 1.29, las entradas agentConnectors[] son solo de URL y mcpToolDescription es opcional, por lo que un paquete generado por wiqd nunca llega a ese error de carga. WIQD aún no aplica scaffolding a la autenticación del conector: configúrelo directamente como se describe en Tipos de autenticación admitidos.

Paso 3: Validar a medida que avanzas

Valida continuamente en lugar de ensamblar un paquete y esperar que la carga se valide correctamente:

wiqd plugin validate
wiqd plugin validate --mode deep

validate es la comprobación estática sin conexión a través de la superficie declarativa del agente. Un completo solo de capacidad o solo de conector lo pasa sin nada que verificar, lo cual es de esperar: es una verificación de su bucle de compilación, no una cobertura completa. validate --mode deep empaqueta primero el complemento y, a continuación, valida el .zip compilado con la misma biblioteca de validación de aplicaciones que usa la carga. Ahí es donde aparecen los códigos ASKILL y las reglas de conectores.

Ejecute estos tres comandos en orden:

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

Ejecutar provision primero porque escribe el archivo de entorno del que dependen tanto package como share. Se usa --scope users para compartir con las personas que indique o --scope tenant para compartir con todos los usuarios de su organización. De cualquier manera, el complemento aparece en Compartido conmigo en Cowork>Fuentes y habilidades>. Para incluirlo en la sección Descubrir, un administrador carga el paquete. Más información en Paso 8: Publicar en su inquilino. Para quitar lo que creó provision, ejecute wiqd plugin delete --env local --yes.

El envío a la tienda pública sigue siendo un proceso manual en Partner Center. Más información en Paso 9: Publicar para al público.

Llevar un complemento a otro host

Para usar sus habilidades en Claude Code, Cursor o cualquier otro host de habilidades de agente, exporte el proyecto en lugar de copiar carpetas a mano:

wiqd plugin export --format claude-plugin

export tiene como valor predeterminado --format open-plugin y también acepta cursor-plugin. Escribe un directorio sin comprimir en <path>/export/<format>.

Importar un complemento existente

Si ya tienes un complemento de Claude Code con habilidades y servidores MCP, tienes dos vías de conversión. La ruta que elija depende de si planea seguir desarrollando el complemento o simplemente enviar lo que tiene.

Objetivo	Use
Siga desarrollando, validando y entregando el complemento desde Microsoft 365	`wiqd plugin import`
Crea un `.zip` publicable a partir de un plugin de Claude existente ahora mismo	El script de conversión

Importar con wiqd

wiqd plugin importreconoce una fuente de plugin Open Plugin, plugin de Claude o plugin de Cursor y produce un proyecto de plugin wiqd a partir de ella. El complemento importado forma parte del mismo ciclo de vida que uno que has creado con wiqd plugin create:

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

--privacy-url y --terms-url solo son necesarios la primera vez que se importa un complemento. Si el origen procede de un wiqd plugin export anterior, los metadatos de ida y vuelta ya los contienen.

Importante

Un proyecto importado solo admite la parte del ciclo de vida de solo lectura: wiqd plugin validate, show y list. Aún no se puede empaquetar, aprovisionar ni compartir, porque la importación no genera la estructura de los archivos locales de implementación que necesitan esos pasos. Esta es una deficiencia seguida. Para conocer el estado actual, compruebe la referencia de la CLI de wiqd. Si usted necesita un paquete publicable hoy mismo, use el script de conversión.

Convertir con el script de conversión

El script de conversión traduce un complemento de Claude directamente en un paquete para M365 listo para publicarse:

Instale la CLI (requiere la versión 1.1.12 o una versión posterior):
```
npm install -g @microsoft/m365agentstoolkit-cli
```
Compruebe la versión:
```
atk --version
```

Importa tu complemento:

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

El comando lee el directorio .claude-plugin/plugin.json (o .cursor-plugin/plugin.json), .mcp.json y skills/ de su complemento , y luego estructura un proyecto de Agents Toolkit que contiene appPackage/manifest.json, sus capacidades y los iconos generados.

Debe incluir --privacy-url y --terms-url porque los manifiestos de complemento no tienen campos equivalentes y el manifiesto de Microsoft 365 requiere ambos.

Note

atk import openplugin localiza un manifiesto de complemento en un directorio con prefijo de punto —.claude-plugin/plugin.json, .cursor-plugin/plugin.json o .plugin/plugin.json— junto a un .mcp.json. La especificación Agent Plugins 1.0.0 sitúa el manifiesto en plugin.json en el nivel superior y la configuración de MCP en mcp.json. Para importar un complemento que sigue la estructura 1.0.0, mueva su archivo de manifiesto a .plugin/plugin.json y cambie el nombre de mcp.json a .mcp.json.

Empaquetar el resultado en un archivo cargable .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 genera un manifiesto devPreview. Los ejemplos de manifiesto de otra parte de este artículo usan el esquema v1.28. Si va a publicar mediante un canal que requiere v1.28, actualice manifestVersion y $schema en el archivo appPackage/manifest.json generado.

Qué se importa

Artefacto de complemento	Equivalente de M365	Notas
`.claude-plugin/plugin.json`	`manifest.json`	Campos de nombre, descripción y desarrollador asignados; GUID generado automáticamente (UUID determinista v5)
`skills/*/SKILL.md`	`agentSkills[]` Entradas + `skills/` carpeta	Copiado textualmente - formato idéntico
Servidores `.mcp.json`	Entradas `agentConnectors[]`	Detección automática de URL y tipo de autenticación
`color.png` / `outline.png`	Iconos en el paquete	Se usa si está presente; marcadores de posición generados si faltan

Importante

Para cada conector importado desde .mcp.json, el generado authorization.referenceId es un marcador de posición derivado del complemento y el nombre del servidor. Reemplácelo por el identificador real de registro de cliente OAuth antes de publicarlo. Obtenga más información en Tipos de autenticación admitidos.

Lo que no se ha convertido

Las siguientes características del complemento de Claude aún no se admiten en el manifiesto de Microsoft 365:

Función del complemento de Claude	Status
`commands/` (comandos con barra)	Todavía no se admite
`agents/` (subagentes)	Todavía no se admite
`hooks/` (manejadores de eventos)	Todavía no se admite
`settings.json`	No aplicable
`bin/` (ejecutables)	No aplicable

Opciones de importación

Option	Description
`--path`, `-p`	Required. Directorio del complemento que contiene `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, o `.plugin/plugin.json`
`--output`, `-o`	Carpeta del proyecto de destino (predeterminado: `./<plugin-name>`)
`--privacy-url`	`developer.privacyUrl` para el manifiesto generado
`--terms-url`	`developer.termsOfUseUrl` para el manifiesto generado
`--website-url`	`developer.websiteUrl`. Recurre a `homepage`, luego `author.url`
`--app-id`	Sobrescribir el UUID determinista v5 generado para el manifiesto `id`
`--default-auth-type`	`Auto` (por defecto), `None`, `OAuthPluginVault`, o `ApiKeyPluginVault`

Detección automática del tipo de autenticación:

Source	Tipo de autenticación predeterminado	Reason
Direcciones URL HTTPS externas	`OAuthPluginVault`	La mayoría de las API remotas necesitan autenticación
`localhost` y direcciones URL no HTTPS	`None`	Servidores de desarrollo local

Si la detección automática no coincide con su configuración, use --default-auth-type para anularla.

Exportar de nuevo a un directorio de complementos

Para volver a mover un proyecto de Agents Toolkit a un directorio de complementos, por ejemplo, para mantener sincronizados un complemento de Claude Code y un paquete de Cowork, use atk export openplugin:

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

Option	Description
`--path`, `-p`	Required. Carpeta de proyecto de Agents Toolkit que contiene `appPackage/manifest.json`
`--output`, `-o`	Directorio del complemento de destino (predeterminado: `./<plugin-name>-openplugin`)
`--manifest-kind`	`open-plugin` (predeterminado, escribe `.plugin/plugin.json`), `claude-plugin` o `cursor-plugin`

La exportación escribe un bloque x-microsoft-365-agents-toolkit en el archivo plugin.json generado. Ese bloque contiene el id de manifiesto, las URL del desarrollador y la configuración del conector, de modo que un atk import openplugin posterior realiza ida y vuelta sin necesidad de --privacy-url ni de --terms-url de nuevo.

Note

El x-microsoft-365-agents-toolkit bloque es específico de Agents Toolkit y el tipo predeterminado open-plugin escribe el manifiesto en .plugin/plugin.json. Agent Plugins 1.0.0 utiliza un plugin.json de nivel superior y contiene datos específicos del cliente bajo la clave extensions con un espacio de nombres de dominio inverso, por lo que otros clientes ignoran este bloque en lugar de actuar sobre él. Cuando el destino sea Claude Code o Cursor, use --manifest-kind claude-plugin o cursor-plugin.

Heredado: script de conversión de PowerShell

Antes de atk admitir la importación de complementos, la conversión utilizaba un script de PowerShell solo para Windows, que sigue estando disponible como script de conversión:

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

Utilice atk import openplugin en su lugar. Es multiplataforma, admite orígenes de Cursor y Claude Code, y puede exportar a un directorio de complementos.

Ensamblar un paquete a mano

Esta sección es la referencia del formato del paquete: describe exactamente lo que Crear un complemento con wiqd genera, campo por campo. Sígalo de principio a fin cuando no pueda instalar herramientas o esté construyendo su propio proceso de empaquetado. Úselo como referencia cuando necesite comprender o depurar un paquete generado.

Paso 1: Crear la primera capacidad

Una capacidad es una carpeta que contiene un archivo SKILL.md. Cree la estructura de carpetas siguiente:

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

Escriba SKILL.md con frontmatter YAML y un cuerpo de 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 |

Campos de metadatos de SKILL.md

Campos obligatorios:

Field	Constraints	Description
`name`	1-64 caracteres, kebab-case	Identificador de habilidad: debe coincidir exactamente con el nombre de la carpeta
`description`	De 1 a 1024 caracteres	Cuándo usar esta habilidad: incluir frases desencadenantes

Importante

El nombre de la carpeta debe coincidir con el name campo del frontmatter. Esta falta de coincidencia es la causa más común de errores de capacidad.
Los campos de lista description de complementos no deben incluir llamadas a la acción que dirijan a los usuarios a mercados externos para comprar suscripciones.

Folder path (Ruta de acceso a la carpeta)	campo `name`	¿Es válido?	Por qué
`skills/contract-analysis/SKILL.md`	`contract-analysis`	Yes	La carpeta y el nombre coinciden
`skills/contract-analysis/SKILL.md`	`ContractAnalysis`	No	El nombre usa PascalCase en lugar de carpetas coincidentes
`skills/my-skill/SKILL.md`	`contract-analysis`	No	La carpeta es `my-skill` pero el nombre es `contract-analysis`

Reglas de nomenclatura (kebab-case): Use solo caracteres alfanuméricos en minúsculas y guiones. No utilice guiones consecutivos ni guiones iniciales o finales.

Ejemplo	¿Es válido?	Issue
`bond-relative-value`	Yes	Minúsculas con guiones
`fx-carry-trade`	Yes	Minúsculas con guiones
`email`	Yes	Una sola palabra, sin guion
`Bond_Relative_Value`	No	Guiones bajos y letras mayúsculas
`--my-skill--`	No	Guiones iniciales y finales
`my--skill`	No	Guiones consecutivos

Paso 2: Agregar materiales de referencia (opcional)

Para capacidades complejas, mantenga el SKILL.md principal ligero y mueva el contenido detallado a los subdirectorios. Estos archivos adicionales son archivos complementarios. La habilidad los carga cuando es necesario.

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

Límites de archivos complementarios

Cada capacidad puede incluir hasta 20 archivos complementarios (cualquier archivo que no sea SKILL.md). Se aplican los siguientes límites por habilidad:

Limit	Value
Archivos complementarios máximos	20
Tamaño máximo por archivo complementario	5 MB
Tamaño total máximo de los acompañantes	10 MB
Tiempo de espera de descarga (todos los complementarios)	15 segundos

Reglas de archivos complementarios

Las rutas de acceso de archivos complementarios deben seguir estas reglas:

Utilice solo rutas de acceso relativas (sin rutas de acceso absolutas).
Sin recorrido de ruta (segmentos ..).
No hay barras diagonales inversas ni bytes nulos en los nombres de archivo.
No hay archivos ocultos (nombres que comiencen con .).
No se permiten nombres reservados de Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
El archivo SKILL.md en sí no cuenta como archivo complementario.
Los nombres de archivo deben usar caracteres seguros: alfanuméricos, guiones, guiones bajos, puntos, espacios y !.

Para mantener eficiente la ventana de contexto, el sistema carga habilidades en tres capas:

Nivel	Cuando está cargado	Tamaño objetivo
Metadatos (`name` + `description`)	Siempre - en el inicio	~100 tokens
Cuerpo de `SKILL.md`	Cuando se desencadena la capacidad	Menos de 5000 tokens (1500-2000 palabras)
Referencias (`references/`)	A petición del agente	Sin límite
Secuencias de comandos (`scripts/`)	Ejecutado, no cargado en el contexto	N/A

Mencione los subdirectorios de forma explícita en SKILL.md para que el agente sepa que existen:

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

Paso 3: Agregar un conector (opcional)

Si su extensión necesita acceso a datos externos, agregue un servidor MCP remoto. Este paso es opcional. Los paquetes de solo capacidades funcionan bien para flujos de trabajo basados en indicaciones.

Tip

Si su servidor controla la visibilidad de herramientas en función del cliente o atribuye tráfico entrante, vaya a Identificar el tráfico de Cowork a su servidor para la identidad de cliente que presenta Cowork.

Note

Los complementos personalizados no son compatibles con Cowork en dispositivos móviles.

Requisitos del conector

Requirement	Detalles
Transport	HTTP compatible con streaming (se requiere HTTPS, TLS 1.2+)
Protocol	Formato de mensaje JSON-RPC 2.0
Descubrimiento de herramientas	Compatibilidad de `tools/list` con detección dinámica (recomendado)
Ejecución de herramientas	Compatibilidad `tools/call` con invocación
Disponibilidad	SLA de tiempo de actividad del 99,9 % recomendado para aplicaciones publicadas en almacén
Tiempo de respuesta	Menos de 30 segundos por invocación de herramienta

Directrices de diseño de herramientas

Una herramienta por acción para API pequeñas (menos de 15 operaciones): search_case_law, get_ruling, cite_precedent
Buscar + ejecutar para API grandes (50+ operaciones): search_actions + execute_action
Nombres descriptivos: get_bond_price no getData
Esquemas de entrada enriquecidos: incluye una descripción para cada parámetro: esto es lo que lee el agente
Salida estructurada: devuelve JSON que el agente puede formatear para el usuario
Entradas de archivo: Para aceptar un archivo del espacio de trabajo del usuario, declare el parámetro con contentEncoding: base64. Más información en Aceptar archivos del espacio de trabajo de Cowork.

Describa las herramientas del conector (`mcpToolDescription`)

De manera opcional, un remoteMcpServer conector puede incluir un mcpToolDescription objeto. Cuando se proporciona, su propiedad anidada file apunta a un archivo JSON de descripción de herramienta que se empaqueta en su .zip y al que hace referencia mediante una ruta de acceso relativa desde la raíz del paquete. Cowork descubre herramientas dinámicamente desde su servidor MCP y no utiliza este archivo, incluso cuando está presente.

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

Si se incluye mcpToolDescription, el archivo al que se hace referencia (por ejemplo, tools/contoso-legal-tools.json) describe las herramientas que expone el conector y debe incluirse en el paquete ZIP. Inclúyalo junto a su manifest.json y su carpeta skills/ cuando empaquete el complemento.

Tip

Este requisito se aplica al manifiesto versión 1.28. Los paquetes que genera wiqd plugin create son específicos de 1.29, donde las entradas de agentConnectors[] son solo de URL, mcpToolDescription es opcional y no hay ningún archivo de descripción de herramienta para olvidar.

Tipos de autenticación admitidos

Tipo de autenticación	Cuándo usarlo	Experiencia del usuario
`None`	API públicas o anónimas, servicios internos	Transparente: sin solicitud de autenticación
`OAuthPluginVault`	APIs de OAuth 2.0 (recomendadas para producción)	El usuario completa el consentimiento de OAuth una vez
`ApiKeyPluginVault`	Servicios basados en claves de API	El usuario proporciona la clave una vez

Note

La compatibilidad con la autenticación de claves API aún no está disponible en Cowork.
Si su servidor MCP requiere una clave de API, use OAuthPluginVault o el registro dinámico de clientes en su lugar, o exponga un punto de conexión que acepte None.

Para OAuthPluginVault y ApiKeyPluginVault, el referenceId apunta a credenciales almacenadas en el almacén de tokens de Microsoft Enterprise; los secretos nunca aparecen en los archivos de manifiesto o de aptitudes. El valor de referenceId es el identificador de registro de cliente de OAuth que se crea al registrar un cliente OAuth con Agents Toolkit.

Importante

Al registrar el cliente OAuth, establezca el uso por organización en Cualquier organización de Microsoft 365 para asegurarse de que el complemento funciona en todos los tenants.

Autenticación de MCP

Para usar OAuth o ApiKey para la autenticación, consulte Configurar la autenticación para complementos MCP y API en agentes en Microsoft 365 Copilot para obtener detalles de instalación y configuración.

Registro de cliente dinámico

Si su servidor MCP admite Dynamic Client Registration (DCR), puede omitir una configuración de authentication de la definición del conector, y Cowork creará automáticamente un cliente OAuth en nombre del complemento.

Note

Omitir la configuración authentication solo es compatible con Cowork. No se admite en Copilot Chat. Si el complemento también tiene que funcionar en Copilot Chat, configura OAuthPluginVault la autenticación como se describe en Tipos de autenticación admitidos.

Puede omitir el authorization objeto por completo. Configura la URL de tu servidor MCP, y Cowork se encargará de gestionar el cliente OAuth:

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

Paso 4: Crear el manifiesto

Cree manifest.json en la raíz de su paquete. El ejemplo usa la versión 1.28 del manifiesto; wiqd plugin create fija la versión 1.29 en su lugar, donde las entradas del conector son solo URL.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
  "manifestVersion": "1.28",
  "version": "1.0.0",
  "id": "YOUR-GUID-HERE",
  "developer": {
    "name": "Contoso Legal Tech",
    "websiteUrl": "https://contoso.com",
    "privacyUrl": "https://contoso.com/privacy",
    "termsOfUseUrl": "https://contoso.com/terms"
  },
  "name": {
    "short": "Contoso Legal Tools",
    "full": "Contoso Legal Tools for Copilot Cowork"
  },
  "description": {
    "short": "Contract analysis, clause extraction, and legal research",
    "full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#2B579A",
  "agentSkills": [
    { "folder": "./skills/contract-analysis" }
  ]
}

Para agregar un conector, incluya lo siguiente 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"
          }
        }
      }
    }
  ]
}

En la configuración del conector, referenceId debe ser el identificador de registro de OAuth. Si incluye mcpToolDescription, su file debe apuntar a un archivo JSON con la descripción de la herramienta que se incluye en el paquete ZIP.

Importante

El esquema del manifiesto v1.28 es estricto: establece additionalProperties: false como elemento raíz, por lo que se rechaza cualquier campo que no esté definido en el esquema. Los campos válidos en los manifiestos estándar de aplicaciones de Teams, como packageName, hacen que la carga falle con un error como Property 'packageName' has not been defined and the schema does not allow additional properties. Incluya solo los campos que se muestran aquí.

Paso 5: Añadir iconos

Crea dos iconos en formato PNG:

Icon	Size	Purpose
`color.png`	192×192 px	Icono de aplicación en color que se muestra en el almacén y la lista de aplicaciones
`outline.png`	32×32 px	Icono de contorno de un solo color para vistas compactas

Si aún no tiene iconos, atk import openplugin genera marcadores de posición de un solo color. Reemplácelos antes del envío del almacén.

Paso 6: Empaquetar

Cree un archivo ZIP con todo el contenido en el nivel raíz. (wiqd plugin package produce esta misma estructura después de 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

Si un conector incluye mcpToolDescription, incluya el archivo JSON de descripción de la herramienta al que hace referencia. Los paquetes que no usan mcpToolDescription, incluidos los paquetes solo de capacidades, no necesitan una carpeta tools/.

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/

Usar Microsoft 365 Agents Toolkit

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

Paso 7: Probar

Para probar la aplicación, cargue el paquete de la aplicación en Teams como se describe en Cargar la aplicación en Teams.

Si ha creado el complemento con wiqd, ejecute wiqd plugin provision en su lugar: registrará el complemento con su inquilino. Para realizar pruebas personales de un paquete ensamblado a mano, transfiera localmente la aplicación mediante la interfaz de línea de comandos del Kit de herramientas de agentes de Microsoft 365:

Instala @microsoft/m365agentstoolkit-cli desde npm:

npm install -g @microsoft/m365agentstoolkit-cli

Compruebe la instalación ejecutando:
```
atk --version
```
Autentique con su cuenta profesional de Microsoft 365:
```
atk auth login
```
Inicie sesión en su cuenta profesional e instale el paquete de agente. Reemplaza la ruta del archivo por la ruta de acceso de tu archivo ZIP:
```
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal
```
Una instalación correcta devuelve un resultado que incluye un TitleId y un AppId para su cuenta.
Guarde estos identificadores para usarlos más adelante cuando los actualice o desinstale.

Obtenga más información en la interfaz de línea de comandos del Kit de herramientas de agentes de Microsoft 365.

Paso 8: Publicar en su inquilino

Cargue el paquete en el centro de administración para incluir su plugin en la sección Descubrir, donde todos los usuarios de la organización podrán encontrarlo:

Abra Centro de administración de M365>Administrar aplicaciones>Cargar aplicación personalizada.
Selecciona el botón de puntos suspensivos (...) >Agregar agente.
Sube tu .zip paquete.
Abra Cowork>Fuentes y capacidades>Complementos. El complemento aparece en la sección Discover.

wiqd plugin share sitúa el complemento en Compartido conmigo en lugar de Descubrir. Úselo para realizar pruebas y para un despliegue selectivo entre personas concretas. La carga del centro de administración es lo que muestra un complemento para que se pueda encontrar.

Paso 9: Publicar para el público

Para complementos destinados para distribución pública, envíe el complemento a Microsoft 365 App Store a través del Centro de partners. Obtenga más información en Publicar agentes para Microsoft 365 Copilot.

Probar un conector con un servidor MCP local

Los conectores requieren una conexión HTTPS mcpServerUrl. Para probar un servidor que se ejecuta en el equipo, debe exponerlo a través de una dirección URL HTTPS pública. Dev tunnels proporcionan una retransmisión que termina TLS por usted.

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

Importante

Usa --protocol http, no https. La marca --protocol describe el servicio local al que reenvía el túnel, no la dirección URL del túnel público. La mayoría de los servidores MCP locales hablan HTTP simple, por lo que si establece --protocol https mientras su servidor sirve HTTP, cada solicitud a través del túnel devuelve un error 502. La retransmisión finaliza TLS y sirve la URL pública a través de HTTPS, independientemente de esta marca.

Troubleshooting

Síntoma	Causa	Corregir
Cada solicitud tunelizada devuelve `502` y el servidor local habla HTTP	`devtunnel port create` se ha ejecutado con `--protocol https`	Recrear el puerto con `--protocol http`
Las solicitudes tunelizadas devuelven `502` en macOS aunque el servidor local esté en ejecución	El servidor está enlazado a `0.0.0.0` (solo IPv4), pero el túnel marca `localhost`, que se resuelve primero en `::1` (IPv6)	Enlace el servidor a `::` para que acepte conexiones IPv4 e IPv6
La carga falla con `Property '<field>' has not been defined and the schema does not allow additional properties`	El manifiesto incluye un campo que el esquema v1.28 no permite (por ejemplo, `packageName`)	Elimine el campo; El esquema v1.28 utiliza `additionalProperties: false`

Patrones de empaquetado

Elija el patrón que se adapte a su extensión:

Solo aptitudes (sin conector)

Recomendado para flujos de trabajo basados en prompts, análisis de documentos y ayuda para la escritura.

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 de acceso remoto

Recomendado para análisis de datos, integraciones de API y sistemas empresariales.

my-data-skills.zip
├── manifest.json          # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

Solo conector (sin capacidades personalizadas)

Use esta opción para los orígenes de datos que ya pueden usar las capacidades integradas de 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 o complemento de Cursor

Utilice esta opción para los complementos del ecosistema de Claude existentes destinados a Cowork. Para seguir desarrollando el complemento en Microsoft 365, impórtelo:

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

Para producir un .zip publicable desde el complemento tal y como está hoy, utilice el script de conversión:

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

Buenas prácticas de desarrollo de habilidades

Siga estas instrucciones para crear habilidades que se activen de forma confiable y produzcan resultados consistentes.

Escribir descripciones efectivas

El description campo determina cuándo el agente activa tu skill. Sé 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.

Escribir flujos de trabajo eficaces

Sé específico en la descripción. Incluya frases desencadenantes: "Usar cuando el usuario pide..." Esta descripción es cómo el agente decide qué habilidad activar.
Estructure como flujo de trabajo. Numere los pasos. Cada paso debe asignarse a una acción concreta (leer un archivo, llamar a una herramienta, generar resultados).
Definir el formato de salida. Mostrar la tabla, lista o estructura de documento exacta que los usuarios deben esperar. Esta definición mejora drásticamente la consistencia.
Herramientas de referencia por nombre. Si su capacidad depende de herramientas de conector, asígneles un nombre explícito: "Use la herramienta search_case_law para..."
Mantén el SKILL.md principal reducido. Mueva el material de referencia detallado al subdirectorio references/. El cuerpo de capacidades debe ser el flujo de trabajo, no una enciclopedia.

Evitar errores comunes

No incruste secretos en archivos SKILL.md. Se usa agentConnectors con autenticación para las credenciales de API.
No duplique capacidades integradas. Compruebe la lista de capacidades integradas antes de crear.
No hagas que las habilidades sean demasiado amplias. "Hacer todo con documentos legales" es menos adecuado que las capacidades específicas para "análisis de contratos", "extracción de cláusulas" e "investigación legal".
No codifiques de forma rígida rutas de archivo ni comandos del sistema. Las habilidades deben ser portátiles entre entornos.
No pongas todo en SKILL.md. Si su cuerpo supera las ~3000 palabras, mueva el contenido detallado a references/.

Reglas de validación

Cuando envías tu paquete, la plataforma lo valida en múltiples niveles. Corrige estos errores antes de enviar para evitar el rechazo.

Para detectarlos mientras compila en lugar de en el momento de la carga, ejecute wiqd plugin validate --mode deep. Este comando empaqueta el complemento y ejecuta estas mismas reglas localmente. Más información en Paso 3: Validar a medida que crea.

Validación a nivel de manifiesto

Code	Rule	Severity
ASKILL-M001	`folder` es obligatorio en cada entrada de `agentSkills`	Error
ASKILL-M002	`agentSkills` El array puede tener hasta 20 elementos	Error
ASKILL-M003	`folder` La ruta de acceso puede tener hasta 256 caracteres	Error

Validación de nivel de paquete

Code	Rule	Solución común	Severity
ASKILL-P001	La carpeta a la que se hace referencia en el manifiesto existe en el ZIP	Compruebe la estructura del archivo ZIP	Error
ASKILL-P002	La carpeta contiene un `SKILL.md` archivo	Agregar el `SKILL.md` que falta	Error
ASKILL-P003	`SKILL.md` tiene metadatos YAML válidos entre delimitadores `---`	Corregir sintaxis de YAML	Error
ASKILL-P004	Los metadatos incluyen el campo `name`	Agregar `name:` al frontmatter	Error
ASKILL-P005	Los metadatos incluyen el campo `description`	Agregar `description:` al frontmatter	Error
ASKILL-P006	`name` coincide con el nombre de la carpeta (último segmento de la ruta)	Cambiar el nombre de la carpeta o corregir `name:`	Error
ASKILL-P007	`name` es kebab-case	Use `my-skill` no `MySkill` ni `my_skill`	Error
ASKILL-P008	No hay valores duplicados `folder` en el array	Eliminación de duplicados	Error

Validación del conector

Rule	Severity
Cada conector requiere un `id` y un `displayName`	Error
Todos los valores de `id` del conector deben ser únicos en el manifiesto	Error
Exactamente uno de `plugin` o `remoteMcpServer`	Error
`mcpServerUrl` debe ser una dirección URL HTTPS válida	Error
Si `mcpToolDescription` está presente, debe existir su `file` en el ZIP	Error
`authorization.referenceId` Requerido a menos que el tipo sea `None`	Error
`authorization.referenceId` no debe estar presente cuando el tipo es `None`	Error

Validación de archivo complementario

El portal valida los archivos complementarios (materiales de referencia, scripts y otros archivos junto con SKILL.md) en el momento de la carga y la sincronización:

Rule	Severity
Máximo 20 archivos complementarios por skill (excluyendo `SKILL.md`)	Error
Cada archivo complementario debe ser de 5 MB o menos	Error
El total de archivos complementarios debe ser de 10 MB o menos por skill	Error
Las rutas de archivo deben ser relativas (sin rutas absolutas)	Error
Sin segmentos de recorrido de directorios (`..`)	Error
No hay barras diagonales inversas ni bytes nulos en los nombres de archivo	Error
No hay archivos ocultos (nombres que comiencen por `.`)	Error
No hay nombres reservados de Windows (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`)	Error
Los nombres de archivo solo deben usar caracteres seguros (alfanuméricos, guiones, guiones bajos, puntos, espacios, `!`etc.)	Error

Compatibilidad multiplataforma

Las habilidades usan el estándar abierto Agent Skills. Los mismos archivos SKILL.md funcionan con múltiples herramientas de IA:

Platform	Compatibility
Claude Code	Formato `SKILL.md` idéntico
Proyectos de Claude.ai	Los Full-skills se pueden cargar como archivos de proyecto
VS Code, GitHub Copilot	Capacidades de agente completo compatibles en modo agente
Gemini CLI	Capacidades de agente completo admitidas
JetBrains Junie	Capacidades de agente completo admitidas
Códice OpenAI	Capacidades de agente completo admitidas
Cursor	Capacidades de agente completo admitidas

Si estás desarrollando habilidades tanto para Claude Code como para Copilot Cowork, crea el plugin con wiqd. A continuación, ejecute wiqd plugin export --format claude-plugin para producir la estructura de Claude Code. Si prefieres empezar desde la estructura del plugin de Claude Code (es el superconjunto), el diseño es:

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)

A continuación, llévelo a Microsoft 365 cuando esté listo para publicarlo en Microsoft 365 App Store, con wiqd plugin import o con el script de conversión:

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

Administración de anotaciones y confirmaciones de MCP

Copilot Cowork lee el objeto MCP annotations estándar en las herramientas que devuelve su servidor desde tools/list, y lo usa para decidir si una llamada a la herramienta necesita confirmación del usuario y qué etiqueta mostrar en el mensaje.

Campos disponibles

Field	Tipo	Effect
`readOnlyHint`	bool	`false`: se requiere confirmación antes de que se ejecute la herramienta.
`destructiveHint`	bool	`true`: se requiere confirmación antes de que se ejecute la herramienta.
`title`	string	Etiqueta legible por humanos que se muestra en el cuadro de diálogo de confirmación. Recurre al nombre de la herramienta en su ausencia.

Reglas de confirmación

Se requiere confirmación si readOnlyHint == false o destructiveHint == true.

Todas las herramientas deben tener especificadas las anotaciones de seguridad. Las herramientas sin anotaciones se tratan como destructivas y requieren confirmación. Obtenga más información en la referencia de esquema de MCP.

Ejemplos de MCP

Una acción destructiva con una etiqueta amigable:

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

Una lectura segura que se ejecuta automáticamente:

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

¿Qué está disponible ahora?

Las herramientas de Microsoft (Graph, Dataverse y otras) están controladas por la directiva integrada de Cowork, independientemente de las anotaciones.
En los servidores MCP que no son de Microsoft, la confirmación basada en anotaciones se está implementando progresivamente. La configuración de sugerencias ahora es compatible con futuros cambios, y las indicaciones de confirmación aparecen a medida que se expande la implementación sin necesidad de cambios del desarrollador.

Aceptar archivos del área de trabajo de Cowork

Una herramienta de conector puede tomar un archivo de la sesión de Cowork del usuario como entrada: un documento que el usuario adjuntó, un archivo adjunto de correo electrónico que Cowork guardó o un archivo producido por un paso anterior. Declare el parámetro con la palabra clave contentEncoding: base64 estándar JSON Schema y Cowork se encargará del resto. No se requiere ninguna extensión de esquema específica de Microsoft y la superficie de API del servidor no cambia.

Cowork resuelve el archivo del área de trabajo y lo codifica en base64 antes de llamar a su servidor, por lo que los bytes del archivo nunca entran en el contexto del agente. El agente solo ve y genera rutas de archivo del espacio de trabajo.

Note

No indique al agente que codifique en base64 un archivo y pegue el blob en una llamada a una herramienta. Ese enfoque carga todo el archivo en el contexto del modelo y depende de que el modelo reproduzca el blob exactamente. Parece funcionar en pequeños archivos de prueba y falla en los reales.

Declarar un parámetro de archivo

Una propiedad de cadena con contentEncoding: base64 se reconoce como un campo de archivo:

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

También se reconoce una matriz de estas cadenas, para las herramientas que aceptan varios archivos:

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

Lo que ve el agente

Para los parámetros de archivo declarados en el nivel superior de inputSchema.properties, Cowork los reemplaza en el esquema orientado al modelo con una sola matriz direct_attachment_file_paths, el mismo parámetro que usan las herramientas integradas de Cowork, por lo que el agente ya sabe cómo rellenarlo. El esquema anterior se presenta al agente como:

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

Si la herramienta declara más de un parámetro de archivo de nivel superior, todos se contraen en ese único array direct_attachment_file_paths. A la hora de la llamada, Cowork distribuye los archivos resueltos en los nombres de parámetros originales en orden de declaración.

Parámetros de archivo anidado

El agente admite un parámetro de archivo anidado dentro de un objeto o una matriz de objetos. El agente controla este parámetro de manera diferente: en lugar de contraerlo, el agente lo reescribe in situ en una cadena de ruta en la misma ubicación. Este enfoque conserva la asociación entre un archivo y sus campos hermanos. Por ejemplo, se obtiene un recibo por cada línea de gastos:

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

El agente rellena line_items[].receipt con una ruta de acceso al área de trabajo, y Cowork cambia cada ruta por contenido base64 in situ antes de reenviar la llamada.

El anidamiento se atraviesa a una profundidad de cuatro niveles por debajo de la parte superior de inputSchema. Los punteros $ref no se siguen; defina los parámetros de archivo insertados en lugar de mediante un $ref.

Lo que recibe su servidor

Su servidor recibe una solicitud ordinaria tools/call con sus nombres de parámetros originales rellenados con contenido codificado en base64:

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

El servidor no necesita saber que el agente usó una interfaz basada en ruta de acceso, y las herramientas que no declaran parámetros contentEncoding: base64 no se ven afectadas.

Limits

Limit	Value
Archivos por llamada de herramienta	8
Tamaño por archivo	150 MiB
Tamaño total por llamada de herramienta	150 MiB
Parámetros de archivo de matriz por herramienta	1 (combínelo con cualquier número de parámetros de archivo escalar)
Profundidad máxima de anidamiento	4 niveles por debajo del nivel superior de `inputSchema`

Una llamada que supera el número de archivos o un límite de tamaño genera un error de la herramienta y nunca llega a su servidor. Ajuste el tamaño de la API y sus tiempos de espera con un límite máximo de 150 MiB: base64 infla la carga en aproximadamente un tercio sobre el tamaño del archivo sin procesar y el contenido codificado se envía en el cuerpo de la solicitud JSON-RPC.

Recommendations

Describa el parámetro para un lector humano. El agente utiliza la descripción para decidir qué archivo pertenece a qué parámetro. Por ejemplo, "The signed contract PDF to analyze" funciona mejor que "file".
Indique los formatos aceptados en la descripción del parámetro. Cowork pasa a través de lo que el usuario adjunta. Valide el tipo de contenido de su lado y devuelva un error claro de la herramienta si no se puede usar.
Establezca anotaciones. Una herramienta que recibe un archivo y actúa sobre él normalmente no es de solo lectura, por lo que solicita confirmación. Obtenga más información sobre la administración de anotaciones y confirmaciones de MCP.
Mantenga los parámetros de archivo integrados. Un parámetro situado después de un $ref, o anidado a más de cuatro niveles de profundidad, no se reescribe. El servidor recibiría una cadena de ruta de acceso donde espera contenido.
Declare como máximo un parámetro de array file por herramienta. Con dos o más, Cowork no puede determinar qué archivo pertenece a qué array y se produce un error de herramienta en la llamada. Use una matriz, o varios parámetros escalares, o una combinación de escalares y una sola matriz.
Espere un recuento exacto con herramientas solo escalares. Si la herramienta declara solo parámetros de archivo escalares, el número de archivos que pasa el agente debe coincidir con el número declarado. Marque claramente los parámetros de archivo opcionales en sus descripciones para que el agente no proporcione menos o más de lo necesario.

Note

Este mecanismo es anterior al propio trabajo de entrada de archivos de Model Context Protocol, que está siendo estandarizado por el MCP File Uploads Working Group. Cowork podría agregar soporte para la forma estandarizada de entradas de archivo declarativas cuando esté disponible. El contentEncoding: base64 contrato descrito aquí continúa funcionando.

Identifique el tráfico de Cowork hacia su servidor

Si su servidor MCP restringe la visibilidad de las herramientas por cliente, o desea atribuir el tráfico que recibe, puede reconocer las solicitudes que provienen de Cowork. Cowork presenta una identidad de software estable en dos canales:

Channel	Dónde aparece	Value
`User-Agent` encabezado de solicitud	Cada solicitud saliente que Cowork envía a tu servidor	`copilot-cowork/1.0`
`clientInfo` en el handshake de MCP `initialize`	Solo la solicitud `initialize`	`{ "name": "copilot-cowork", "version": "<version>" }`

Coincidir con el prefijo `copilot-cowork`

Haga coincidir el copilot-cowork (sin distinguir mayúsculas de minúsculas) en cualquiera de los canales. No coincidir con la cadena exacta copilot-cowork/1.0 o con una clientInfo.version específica. La versión realiza un seguimiento del contrato de cliente-identidad y se espera que cambie; una coincidencia de prefijo mantiene la puerta funcionando a través de los saltos de versión.

# Correct: case-insensitive prefix match
copilot-cowork

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

Elija el canal adecuado para su puerta

Los dos canales tienen ámbitos diferentes, por lo que elija el que coincida con la forma en que su servidor aplica su puerta:

El User-Agent encabezado está presente en todas las solicitudes, incluidas tools/list y tools/call. Si controla el acceso o atribuye por solicitud, básese en este encabezado.
clientInfo se envía solo en el initialize handshake. Si controla el acceso por sesión en tiempo de conexión, puede leerlo allí, pero no se repetirá en las solicitudes posteriores.

Qué incluye y qué no incluye la identidad

La identidad solo nombra el software . Es lo mismo para todos los usuarios y conexiones de Cowork, y nunca conlleva la identidad del usuario. La identidad del usuario permanece en el flujo de autorización definido por la configuración de autenticación del conector.

La identidad incluye	La identidad no incluye
Un nombre estable del software (`copilot-cowork`) y una versión del contrato	Cualquier identificador de inquilino, usuario, sesión o conversación
El mismo valor en cada solicitud y en cada conexión	Un calificador por conector

Dado que no hay ningún calificador por conector, actualmente no puede usar esta identidad para saber qué conector realizó una llamada o para separar un complemento publicado de Microsoft de un servidor cargado que apunta a la misma dirección URL. Si necesita esa distinción, impóngala mediante la configuración de autorización del conector en lugar de la identidad del cliente.

Preguntas frecuentes

¿Puedo usar las habilidades del paquete M365 en Claude Code?

Yes. Las carpetas de habilidades contienen Agent Skills estándar. Ejecute wiqd plugin export --format claude-plugin para generar el diseño de Claude Code o copie las carpetas de capacidades en .claude/skills/ en cualquier proyecto de Claude Code.

¿Necesito un conector remoto?

N. º Los paquetes de solo capacidades funcionan bien para flujos de trabajo basados en indicaciones. Los conectores solo son necesarios cuando su skill requiere datos activos de un sistema externo.

¿En qué se diferencian las capacidades de complemento de las capacidades integradas?

Las capacidades del complemento aparecen con "package" de fuente en la API. No pueden sobrescribir las capacidades integradas con el mismo nombre. Los paquetes implementados por el administrador muestran isAdminDeployed: true.

¿Pueden los administradores de TI controlar qué complementos están disponibles?

Yes. Se aplican controles de administración de M365 estándar: listas de permitidos o bloqueados de nivel de inquilino, implementaciones administradas por el administrador y directivas de cumplimiento.

¿Qué sucede si se revoca un complemento?

En el siguiente ciclo de sincronización, las aptitudes y conectores de ese paquete se quitan de la sesión del usuario. Las conversaciones activas no se interrumpen, pero las nuevas sesiones no tienen las funcionalidades del paquete.

¿Cuál es el número máximo de habilidades por paquete?

Veinte (20) habilidades (según ASKILL-M002). Para los conectores, el límite es de 10 por paquete.

¿Pueden las capacidades hacer referencia a las herramientas de conector del mismo paquete?

Sí, y deberían hacerlo. Asigne un nombre explícitamente a las herramientas en su flujo de trabajo SKILL.md (por ejemplo, "Usar la herramienta search_case_law para..."). El agente los conecta en tiempo de ejecución.

¿Pueden las herramientas de mi plugin aceptar archivos del espacio de trabajo de Cowork?

Yes. Declare el parámetro de herramienta con contentEncoding: base64, y Cowork resuelve el archivo de área de trabajo del usuario en contenido base64 antes de llamar a su servidor. El modelo pasa rutas de acceso de archivo, no contenido de archivo, por lo que los archivos grandes no consumen el contexto del modelo. Para obtener detalles y límites de declaración, obtenga más información en Aceptar archivos desde el área de trabajo de Cowork.

¿Cómo generar un GUID determinista para mi paquete?

wiqd plugin create genera y ancla el id. de la aplicación. El script de conversión usa UUID v5 (basado en SHA-1) a partir del nombre de tu complemento, por lo que ejecutar la conversión dos veces produce el mismo GUID. Para el empaquetado manual, utilice cualquier generador de GUID. Asegúrese de mantenerlo estable entre versiones.

¿A qué versión del manifiesto debo dirigirme?

Use 1.29 si está creando con wiqd, que lo fija por usted. En 1.29, agentConnectors[] las entradas son solo de URL y mcpToolDescription es opcional. Los ejemplos escritos manualmente en este artículo usan 1.28, donde mcpToolDescription es obligatorio y el archivo al que nombra debe estar en el ZIP. atk import openplugin usa UUID v5 (basado en SHA-1) a partir del nombre de tu complemento. La ejecución de la importación dos veces produce el mismo GUID. Para establecer el suyo, pase --app-id. Para el empaquetado manual, utilice cualquier generador de GUID. Asegúrese de mantenerlo estable entre versiones.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-10-29

Crear complementos para Copilot Cowork

Lo que vas a construir

Elija el punto de partida.

Crear un complemento con wiqd

Paso 1: Instalar wiqd e iniciar sesión

Paso 2: Estructurar el complemento y agregar capacidades

Paso 3: Validar a medida que avanzas

Paso 4: Aprovisionar, empaquetar y compartir

Llevar un complemento a otro host

Importar un complemento existente

Importar con wiqd

Convertir con el script de conversión

Qué se importa

Lo que no se ha convertido

Opciones de importación

Exportar de nuevo a un directorio de complementos

Heredado: script de conversión de PowerShell

Ensamblar un paquete a mano

Paso 1: Crear la primera capacidad

Campos de metadatos de SKILL.md

Paso 2: Agregar materiales de referencia (opcional)

Límites de archivos complementarios

Reglas de archivos complementarios

Paso 3: Agregar un conector (opcional)

Requisitos del conector

Directrices de diseño de herramientas

Describa las herramientas del conector (mcpToolDescription)

Tipos de autenticación admitidos

Autenticación de MCP

Registro de cliente dinámico

Paso 4: Crear el manifiesto

Paso 5: Añadir iconos

Paso 6: Empaquetar

Paso 7: Probar

Paso 8: Publicar en su inquilino

Paso 9: Publicar para el público

Probar un conector con un servidor MCP local

Troubleshooting

Patrones de empaquetado

Solo aptitudes (sin conector)

Habilidades + conector de acceso remoto

Solo conector (sin capacidades personalizadas)

Claude Code importado o complemento de Cursor

Buenas prácticas de desarrollo de habilidades

Escribir descripciones efectivas

Escribir flujos de trabajo eficaces

Evitar errores comunes

Reglas de validación

Validación a nivel de manifiesto

Validación de nivel de paquete

Validación del conector

Validación de archivo complementario

Compatibilidad multiplataforma

Administración de anotaciones y confirmaciones de MCP

Campos disponibles

Reglas de confirmación

Ejemplos de MCP

¿Qué está disponible ahora?

Aceptar archivos del área de trabajo de Cowork

Declarar un parámetro de archivo

Lo que ve el agente

Parámetros de archivo anidado

Lo que recibe su servidor

Limits

Recommendations

Identifique el tráfico de Cowork hacia su servidor

Coincidir con el prefijo copilot-cowork

Elija el canal adecuado para su puerta

Qué incluye y qué no incluye la identidad

Preguntas frecuentes

Información relacionada

Comentarios

Recursos adicionales

Describa las herramientas del conector (`mcpToolDescription`)

Coincidir con el prefijo `copilot-cowork`