Compilar complementos para Copilot Cowork

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 indicaciones que enseñan a Cowork experiencia en nuevos dominios, como análisis financiero, investigación legal o 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.

Qué compilará

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 habilidades utilizan el estándar abierto de habilidades de agente, el mismo formato compatible con Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie y otras 30+ herramientas de IA.

Elige tu punto de partida

Importar un complemento existente

Si ya tiene un complemento de código o cursor de Claude con aptitudes y servidores MCP, la CLIatk () del Kit de herramientas de agentes de Microsoft 365 lo importa directamente. La CLI se ejecuta en Windows, macOS y Linux.

1. Instale la CLI (requiere la versión 1.1.12 o posterior):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Compruebe la versión:

   atk --version
   

3. 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 de su complemento (o.cursor-plugin/plugin.json), .mcp.jsony skills/ luego aplica andamiaje .claude-plugin/plugin.json a un proyecto de Agents Toolkit que contiene appPackage/manifest.json, sus habilidades e íconos 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.

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

Qué se importa

Qué no se ha convertido

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

Opciones de importación

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

Si la detección automática no coincide con su configuración, utilícela --default-auth-type para invalidarla.

Volver a exportar 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

La exportación escribe un x-microsoft-365-agents-toolkit bloque en el plugin.jsonarchivo . Ese bloque lleva el manifiesto id, las direcciones URL del desarrollador y la configuración del conector, por lo que se realizan viajes de ida y vuelta posteriores atk import openplugin sin necesidad --privacy-url de otra --terms-url vez.

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

Úselo atk import openplugin en su lugar. Es multiplataforma, admite fuentes de Cursor y Claude Code, y puede exportar a un directorio de complementos.

Crear un complemento desde cero

Sigue estos pasos para crear un paquete de complementos desde cero, comenzando con tu primera habilidad y construyendo hasta un paquete completo que se pueda publicar.

Paso 1: Crear la primera aptitud

Una aptitud es una carpeta que contiene un SKILL.md archivo. 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 |

SKILL.md campos de frontmatter

Campos obligatorios:

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

Paso 2: Agregar materiales de referencia (opcional)

Para las aptitudes complejas, mantenga la estructura principal SKILL.md 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 habilidad puede incluir hasta 20 archivos complementarios (cualquier archivo que no SKILL.mdsea ). Se aplican los siguientes límites por habilidad:

Reglas de archivos complementarios

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

• Usar 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 por .)
• No hay nombres reservados de Windows (CON, PRN, AUX, NULCOM1, -COM9, -LPT9) LPT1
• 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 la ventana de contexto eficiente, el sistema carga habilidades en tres capas:

Haga referencia a los subdirectorios explícitamente 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 aptitudes funcionan bien para flujos de trabajo basados en indicaciones.

Requisitos del conector

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. Obtenga más información en Aceptar archivos del área de trabajo de Cowork.

Describa las herramientas del conector (mcpToolDescription)

Cada remoteMcpServer conector debe incluir un mcpToolDescription objeto. Su propiedad anidada file apunta a un archivo JSON de descripción de herramienta que empaquetas dentro de tu .zip y al que hace referencia mediante una ruta de acceso relativa desde la raíz del paquete. Si omites mcpToolDescription, el servicio de paquetes rechaza la carga con un error HTTP 400:

Faltan las propiedades necesarias en el objeto: mcpToolDescription.

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

El archivo al que se hace referencia (por ejemplo, tools/contoso-legal-tools.json) describe las herramientas que expone el conector y debe estar presente en el paquete ZIP. Inclúyelo junto a tu manifest.json carpeta and skills/ cuando empaquetes el plugin.

Tipos de autenticación admitidos

Para OAuthPluginVault y ApiKeyPluginVault, los puntos a las referenceId credenciales almacenadas en el almacén de tokens de Microsoft Enterprise - secretos nunca aparecen en los archivos de manifiesto o de aptitudes. El referenceId valor es el identificador de registro del cliente OAuth que se crea al registrar un cliente OAuth con el Kit de herramientas de agentes.

Autenticación 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 dinámico de clientes

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

Puede omitir el authorization objeto, pero aún debe incluir mcpToolDescription. Configure la URL del servidor MCP y la descripción de la herramienta, y Cowork se encargará del cliente OAuth:

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

Paso 4: Crear el manifiesto

Cree manifest.json en la raíz del paquete:

{
  "$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 id. de registro de OAuth y mcpToolDescription.file debe apuntar a un archivo JSON de descripción de herramienta que se incluye en el paquete ZIP.

Paso 5: Agregar iconos

Crea dos iconos PNG:

Si aún no tiene iconos, atk import openplugin genera marcadores de posición de color sólido. Reemplácelos antes del envío de la tienda.

Paso 6: Empaquetar

Cree un archivo ZIP con todo el contenido en el nivel raíz:

contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│   └── contoso-legal-tools.json   # Referenced by mcpToolDescription (connectors only)
└── skills/
    └── contract-analysis/
        ├── SKILL.md
        └── references/
            └── clause-taxonomy.md

Si el paquete incluye una agentConnectors entrada, incluye el archivo JSON tool-description al que hace referencia .mcpToolDescription.file Los paquetes de solo aptitudes no necesitan una tools/ carpeta.

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/

Uso del Kit de herramientas de agentes de Microsoft 365

 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.

Para realizar pruebas personales, transfiera localmente la aplicación mediante la interfaz de línea de comandos del Kit de herramientas de agentes de Microsoft 365:

1. Instalar @microsoft/m365agentstoolkit-cli desde npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Compruebe la instalación ejecutando:

   atk --version
   

3. Autentique con su cuenta profesional de Microsoft 365:

   atk auth login
   

4. Inicie sesión en su cuenta profesional e instale el paquete de agente. Reemplaza la ruta del archivo por la ubicación del paquete zip:

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

   Una instalación correcta devuelve un resultado que incluye un TitleId y AppId para su cuenta.

5. 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 el inquilino

1. Abrir el centro de administración de M365Administrar aplicaciones>Cargar aplicación personalizada.>
2. Selecciona el botón de puntos suspensivos (...) >Agregar agente.
3. Carga el .zip paquete.
4. Open Cowork Sources &>>Skills Plugins. El complemento aparece en la sección Descubrir .

Paso 9: Publicar para el público

Para complementos destinados a la distribución pública, envía 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 un HTTPS mcpServerUrl, por lo que para probar un servidor que se ejecuta en su máquina, debe exponerlo a través de una dirección URL HTTPS pública. Los túneles de desarrollo proporcionan una retransmisión que termina TLS por usted.

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

Solución de problemas

Patrones de empaque

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

Solo aptitudes (sin conector)

Recomendado para flujos de trabajo basados en indicaciones, 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 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
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

Solo conector (sin aptitudes personalizadas)

Use esta opción para las fuentes de datos que ya pueden usar las aptitudes integradas de Cowork.

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

Código de Claude importado o complemento de cursor

Usa esta opción para los complementos existentes de otras herramientas de IA destinados a Cowork.

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

Procedimientos recomendados de creación de aptitudes

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 habilidad. 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 efectivos

• 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.
• La estructura como un 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 coherencia.
• Haga referencia a las herramientas por su nombre. Si su habilidad depende de herramientas de conectores, asígneles un nombre explícito: "Use la search_case_law herramienta para..."
• Mantén el SKILL.md principal reducido. Mueva el references/ material de referencia detallado al subdirectorio. El cuerpo de habilidades debe ser el flujo de trabajo, no una enciclopedia.

Evitar errores comunes

• No incruste secretos en SKILL.md archivos. Usar agentConnectors con autenticación para credenciales de API.
• No duplique las aptitudes integradas. Compruebe la lista de aptitudes integradas antes de crear.
• No hagas que las habilidades sean demasiado amplias. "Hacer todo con documentos legales" es peor que las habilidades específicas para el "análisis de contratos", la "extracción de cláusulas" y la "investigación legal".
• No codifiques de forma rígida rutas de archivo ni comandos del sistema. Las aptitudes 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 del envío para evitar el rechazo.

Validación de nivel de manifiesto

Validación a nivel de paquete

Validación del conector

Validación de archivos complementarios

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

Compatibilidad entre plataformas

Las habilidades utilizan el estándar abierto de habilidades de agente. Los mismos SKILL.md archivos funcionan en varias herramientas de IA:

Si está desarrollando habilidades tanto para Claude Code como para Cowork, comience con la estructura del complemento Claude Code: es el superconjunto:

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, impórtelo en un proyecto de M365 cuando esté listo para publicarlo en Microsoft 365 App Store:

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

Administración de anotaciones y confirmaciones MCP

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

Campos disponibles

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 las sugerencias ahora es compatible con versiones posteriores y las solicitudes de confirmación aparecen a medida que se expande el lanzamiento sin necesidad de cambios por parte 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 al servidor, por lo que los bytes de archivo nunca entran en el contexto del agente. El agente solo ve y emite rutas de acceso de archivos del área de trabajo.

Declare a file parameter

Una propiedad de cadena con contentEncoding: base64 se reconoce como una entrada 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 direct_attachment_file_paths matriz, 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 esa única direct_attachment_file_paths matriz. A la hora de la llamada, Cowork ventila los archivos resueltos en los nombres de parámetros originales en orden de declaración.

Parámetros de archivo anidado

También se admite un parámetro de archivo anidado dentro de un objeto o una matriz de objetos, y se controla de forma diferente: en lugar de contraerse, se reescribe en su lugar en una cadena de ruta de acceso en su propia ubicación. Esto conserva la asociación entre un archivo y sus campos relacionados, por ejemplo, un recibo por línea de gastos:

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

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

El anidamiento se atraviesa a una profundidad de cuatro niveles por debajo de la parte superior de inputSchema. $ref No se siguen los punteros: defina los parámetros de archivo en línea en lugar de detrás de un $refarchivo

Lo que recibe su servidor

Su servidor recibe un ordinario 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 contentEncoding: base64 parámetros no se ven afectadas.

Límites

Una llamada que excede el número de archivos o un límite de tamaño falla con un error de herramienta y nunca llega a su servidor. Ajuste el tamaño de la API y sus tiempos de espera teniendo en cuenta el 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.

Recomendaciones

• 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 de herramienta Borrar si no se puede usar.
• Establecer anotaciones. Una herramienta que recibe un archivo y actúa sobre él normalmente no es de solo lectura, por lo que solicita confirmación. Consulte Gestión de anotaciones y confirmaciones de MCP.
• Mantener los parámetros de archivo en línea. Un parámetro detrás de un $ref, o anidado por una profundidad superior a cuatro niveles, no se vuelve a escribir. El servidor recibirá una cadena de ruta de acceso donde espera contenido.
• Declare como máximo un parámetro de archivo de matriz por herramienta. Con dos o más, Cowork no puede determinar qué archivo pertenece a qué matriz 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 de 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 parámetros de archivo opcionales claramente en sus descripciones para que el agente no proporcione un suministro insuficiente o excesivo.

Identificar el tráfico de Cowork a su servidor

Si su servidor MCP cancela la visibilidad de la herramienta 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:

Coincidir con el copilot-cowork prefijo

Haga coincidir el prefijo (sin distinguir mayúsculas de minúsculas) en cualquiera de los copilot-cowork canales. No coincidan con la cadena exacta copilot-cowork/1.0 o con un clientInfo.versionarchivo . La versión realiza un seguimiento del contrato cliente-identidad y se espera que cambie; Una coincidencia de prefijo mantiene su puerta funcionando a través de los baches 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 se atribuye la puerta o el atributo por solicitud, escriba en este encabezado.
• clientInfo solo se envía en el protocolo de initialize enlace. Si establece la puerta por sesión en el momento de la conexión, puede leerlo allí, pero no se repetirá en 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 que define la configuración de autenticación del 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 de Microsoft publicado de un servidor de instalación de prueba que apunta a la misma dirección URL. Si necesita esa distinción, aplicársela mediante la configuración de autorización del conector en lugar de la identidad del cliente.

Preguntas comunes

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

Sí. Las carpetas de habilidades contienen habilidades de agente estándar. Cópielos en .claude/skills/ cualquier proyecto de Claude Code, o ejecútelos atk export openplugin para convertir todo el proyecto en un complemento de Claude Code.

¿Necesito un conector remoto?

No. Los paquetes de solo aptitudes funcionan bien para flujos de trabajo basados en indicaciones. Los conectores solo son necesarios cuando su habilidad requiere datos activos de un sistema externo.

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

Las aptitudes de complemento aparecen con el origen "package" en la API. No pueden invalidar las aptitudes 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?

Sí. Se aplican los controles de administración de M365 Standard: listas de permitidos o bloqueados a 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 habilidades hacer referencia a las herramientas del conector del mismo paquete?

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

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

Sí. Declare el parámetro de herramienta con contentEncoding: base64, y Cowork resolverá el archivo de área de trabajo del usuario a 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?

atk import openplugin usa UUID v5 (basado en SHA-1) del nombre del complemento. La ejecución de la importación dos veces produce el mismo GUID. Para establecer el tuyo, pasa --app-id. Para el empaquetado manual, use cualquier generador GUID. Asegúrese de mantenerlo estable entre versiones.

Contenido relacionado

• Información general sobre Cowork
• Usar Cowork
• Administrar Cowork para su organización
• Administrar complementos para Cowork