Package and Publish Copilot Cowork Skills

This is part of the Microsoft 365 Copilot Skills series. For the end-user Skills page and built-in Cowork Skills, use the existing Cowork Skills and plugins guide. This spoke focuses on developer packaging and distribution.

A Cowork plugin is a Microsoft 365 app package that can contain Skills, connectors, or both. The ZIP gives your reusable instructions a package identity, icons, validation rules, a test path, and an admin deployment path.

The short version

• A Skill teaches Cowork how to perform a repeatable task.
• A connector gives Cowork live access to an external service, usually through remote MCP.
• Both live in a Microsoft 365 app package.
• Start with a Skills-only package.
• Put manifest.json, color.png, outline.png, and skills/ at the ZIP root.
• Use a separate folder and SKILL.md for each Skill.
• A package can contain up to 20 Skills and 10 connectors.
• Test personally before tenant deployment.
• Tenant-uploaded packages do not go through Microsoft 365 App Store validation.
• Public distribution uses Partner Center and the Microsoft 365 App Store.
• Validate the current manifest schema instead of copying an old MCP example.

What a Cowork plugin contains

The smallest useful Skills package looks like this:

contoso-reporting.zip
├── manifest.json
├── color.png
├── outline.png
└── skills/
    └── weekly-status-report/
        └── SKILL.md

For a larger Skill:

contoso-reporting.zip
├── manifest.json
├── color.png
├── outline.png
└── skills/
    └── weekly-status-report/
        ├── SKILL.md
        ├── references/
        │   └── reporting-rules.md
        └── scripts/
            └── validate-input.py

The ZIP contents go at the root. Do not zip a parent folder and leave manifest.json one level too deep.

Skills, connectors, and the three package patterns

Skills

A Skill is a folder containing SKILL.md.

---
name: weekly-status-report
description: >
  Creates a weekly project status report from the sources provided by
  the user. Use when asked for a weekly update, Friday report, project
  status, or leadership summary.
---

# Weekly status report

1. Gather the named sources.
2. Separate confirmed progress from open questions.
3. List risks, decisions, and next actions.
4. Do not invent an owner or due date.

The folder and name must match:

skills/weekly-status-report/SKILL.md
name: weekly-status-report

Connectors

A connector links Cowork to live tools or data outside Microsoft 365.

For Cowork, Microsoft documents remote MCP connectors using:

• Streamable HTTP over HTTPS;
• TLS 1.2 or later;
• JSON-RPC 2.0;
• initialize;
• notifications/initialized;
• tools/list;
• tools/call.

Microsoft recommends:

• 99.9% availability for a store-published app;
• tool responses in under 30 seconds;
• clear tool and parameter descriptions;
• structured output.

Build a Skills-only manifest first

Microsoft’s Cowork build guide shows a Unified Manifest v1.28 pattern for a Skills-only package:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
  "manifestVersion": "1.28",
  "version": "1.0.0",
  "id": "11111111-1111-1111-1111-111111111111",
  "developer": {
    "name": "Contoso",
    "websiteUrl": "https://contoso.example",
    "privacyUrl": "https://contoso.example/privacy",
    "termsOfUseUrl": "https://contoso.example/terms"
  },
  "name": {
    "short": "Contoso Skills",
    "full": "Contoso Skills for Copilot Cowork"
  },
  "description": {
    "short": "Repeatable reporting workflows.",
    "full": "Skills that help Contoso teams create consistent project reports."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#2B579A",
  "agentSkills": [
    {
      "folder": "./skills/weekly-status-report"
    }
  ]
}

Keep these limits in mind:

Use placeholder GUIDs and Contoso URLs in screenshots. Never show a real tenant secret, auth configuration ID, or customer endpoint.

The manifest-version drift

Microsoft’s current public material does not show one perfectly aligned MCP example.

For remote MCP connectors, the current Cowork build guide requires mcpToolDescription:

• the manifest points to a packaged tool-description JSON file;
• that file must exist in the ZIP;
• Cowork can still call tools/list at runtime for discovery.

Things to know

Validate MCP packages against the current schema and live tenant upload. The build guide uses v1.28, while other Microsoft examples and the conversion script still show devPreview.

Safe wording for a customer or developer:

Cowork plugins use the Microsoft 365 app package format. Start from the current Cowork build guide, then validate MCP connector fields with Agents Toolkit and a test-tenant upload before calling the package production-ready.

Add a remote MCP connector

The connector lives in agentConnectors.

A simplified shape is:

{
  "agentConnectors": [
    {
      "id": "contoso-reporting",
      "displayName": "Contoso Reporting",
      "description": "Reads approved reporting data from Contoso.",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://api.contoso.example/mcp",
          "mcpToolDescription": {
            "file": "./tools/contoso-reporting-tools.json"
          },
          "authorization": {
            "type": "OAuthPluginVault",
            "referenceId": "AUTH-CONFIG-ID"
          }
        }
      }
    }
  ]
}

Package the referenced file at:

tools/contoso-reporting-tools.json

Treat the example as a current starting shape, then validate the exact schema and auth configuration in your tenant.

Design the tools for an agent

Bad tool name:

getData

Better:

get_project_status

Each parameter needs a useful description because the agent reads the schema to decide what to send.

For a small API, one tool per action can work:

• search_projects
• get_project_status
• list_project_risks

For a large API, use a discovery pattern:

• search_actions
• execute_action

Use MCP annotations for safety

Cowork reads standard MCP tool annotations.

{
  "name": "delete_project",
  "description": "Deletes a project after confirmation.",
  "annotations": {
    "title": "Delete project",
    "destructiveHint": true
  },
  "inputSchema": {}
}

The public rules are:

• readOnlyHint: false requires confirmation;
• destructiveHint: true requires confirmation;
• tools without safety annotations are treated as destructive;
• title provides the human-readable action label.

For non-Microsoft MCP servers, Microsoft says annotation-driven confirmation is rolling out progressively. Add the hints now, but verify the confirmation experience in your tenant.

For a read-only tool:

{
  "name": "search_projects",
  "annotations": {
    "title": "Search projects",
    "readOnlyHint": true
  }
}

Authentication

Microsoft’s Cowork and plugin schema examples include:

For authenticated configurations, the manifest stores a referenceId for the registered auth configuration or OAuth client. The credential itself lives in Microsoft’s Enterprise Token Store rather than in manifest.json or SKILL.md.

An admin cannot complete connector sign-in for users. Each user completes the sign-in or consent flow the first time the connector is used.

Dynamic Client Registration

If the MCP server supports Dynamic Client Registration, Cowork can create a client through the server’s discovery and registration endpoints.

Microsoft documents requirements including:

• protected-resource metadata;
• authorisation-server metadata;
• RFC 7591 client registration;
• a client secret;
• PKCE enabled by default.

With DCR, the authorisation block can be omitted, but the package still needs mcpToolDescription.

ApiKeyPluginVault support is not described consistently across every public Cowork/auth page. Test the actual connector and do not infer support from one schema example.

Package limits

Packaged Cowork plugin limits:

Personal Cowork Skill upload has a different set:

Do not mix the two tables. A personal upload archive accepting 100 files does not mean a packaged Skill can have 100 companion files.

Convert a Claude plugin

Microsoft publishes Convert-ClaudePluginToMOS3.ps1.

The short documentation example omits parameters the current script requires. A safer command is:

.\Convert-ClaudePluginToMOS3.ps1 `
  -PluginPath .\my-claude-plugin `
  -OutputPath .\output `
  -PrivacyUrl https://contoso.example/privacy `
  -TermsOfUseUrl https://contoso.example/terms `
  -DetailedOutput

The script also needs a website URL. It can resolve that from:

1. -WebsiteUrl;
2. plugin.json homepage;
3. author.url.

If none exists, it stops.

What the script reads

• .claude-plugin/plugin.json
• optional .mcp.json
• skills/*/SKILL.md
• optional color.png
• optional outline.png

What it produces

• a deterministic app GUID unless you provide one;
• a devPreview Microsoft 365 manifest;
• agentSkills entries for valid Skill folders;
• agentConnectors for URL-based MCP servers;
• generated placeholder icons when icons are missing;
• a ZIP named from the plugin and version.

What does not carry over

The commands/ detail matters. The docs say slash commands are not supported; the script still copies the folder. Treat those files as inert package content unless the validator says otherwise.

For a converted connector, also add and reference the required mcpToolDescription file. The current conversion script does not generate that field.

Things to know

The conversion script is a starting point, not a store-readiness certificate. Replace placeholder auth references, verify privacy/terms fields, check the manifest version, and validate every connector.

Validate the package

Cowork publishes named validation rules.

Manifest-level

Package-level

Connector checks include:

• required, unique id;
• required displayName;
• one valid tool source;
• HTTPS MCP URL;
• mcpToolDescription present with a file that exists in the ZIP;
• referenceId present for authenticated vault types;
• no referenceId for None.

Test personally

Two public paths:

Cowork UI

1. Open Customize.
2. Select Plugins.
3. Select Upload plugin.
4. Choose the ZIP.
5. Keep sharing set to Only you.
6. Start a new Cowork conversation.
7. Check which Skill or connector activates.

Official UI reference: Microsoft Learn — Customize Copilot Cowork.

Agents Toolkit CLI

npm install -g @microsoft/m365agentstoolkit-cli
atk auth login
atk install --file-path "C:\packages\contoso-reporting.zip" --scope Personal

Use a test account and test tenant. Do not show real auth IDs in a public screenshot.

Deploy inside the organisation

Admins can upload a custom app package and target:

• specific users;
• security groups;
• the whole organisation.

Tenant-distributed packages do not go through Microsoft 365 App Store validation. That makes this path useful for:

• development;
• pilot testing;
• internal-only plugins.

It also means your organisation owns the review.

Control custom-app upload rights with the existing Teams custom app policies.

Publish publicly

Public distribution uses Partner Center and the Microsoft 365 App Store.

Store validation covers:

• manifest integrity;
• Skill and connector validation;
• Microsoft 365 app security requirements;
• marketplace certification;
• Copilot/Cowork experience evidence.

Check whether Partner Center accepts the manifest version used by the current test package before promising a public route for a devPreview connector.

Information Barriers caveat

Microsoft says Information Barriers are not currently supported for Cowork plugin or Skill management and sharing.

In an IB-enabled tenant, embedded knowledge-file uploads are blocked at the tenant level. That prevents affected plugins and Skills from being uploaded or published.

Recheck this time-bound limitation before every rollout.

Shipping checklist

• ZIP has manifest.json and icons at root
• Every Skill folder contains SKILL.md
• Folder and name match
• Descriptions contain real trigger phrases
• No secrets in files
• Auth referenceId points to a real configuration
• MCP URL uses HTTPS
• MCP tools have safety annotations
• Destructive tools require confirmation
• Privacy and terms URLs work
• Package validates
• Personal test passes
• Admin pilot uses a small group
• Store submission uses the current schema

Continue the Copilot Skills series

• Microsoft 365 Copilot Skills, explained — the hub.
• Skills in PowerPoint — picker, upload, and management.
• Skills in Excel — end-user Skills and Office.js Preview.
• Skills in Word — the honest current state.
• Write your first SKILL.md — the authoring walkthrough.
• Admin and governance for Copilot Skills — controls, permissions, Purview, and pilot decisions.

Official public sources

• Microsoft Learn — build plugins for Copilot Cowork
• Microsoft Learn — manage Cowork plugins
• Microsoft Learn — use Cowork plugins
• Microsoft Learn — Customize Copilot Cowork
• Microsoft Learn — publish agents and apps for Microsoft 365 Copilot
• Microsoft Learn — plugin authentication
• Microsoft Learn — Agent Skills schema
• Microsoft conversion script — Convert-ClaudePluginToMOS3.ps1
• Agent Skills specification