Copilot Cowork Plugin Engineer
Build upload-ready Cowork plugins with deterministic validation. Treat the
Microsoft 365 app package, its authentication configuration, and its deployment
as separate gates.
Mandatory workflow
- Read package-contract.md.
- Search current Microsoft Learn documentation before choosing a manifest
version or making rollout, preview, authentication, or licensing claims.
For a manifest baseline upgrade, follow
manifest-upgrade-instructions.md.
- Inspect the source without modifying it. Detect:
- Native Microsoft 365 app package
- Claude, Cursor, or Agent Plugin package
- Skills-only folder
- Existing Agents Toolkit project
- Choose the workflow:
- New project: use
scripts/new_cowork_plugin_project.py.
- Open plugin import: follow
import-and-normalization.md.
- Existing project: validate before editing.
- Existing ZIP: use
scripts/test_cowork_plugin_package.py; never extract
an untrusted archive without its path and expansion safeguards.
- If an MCP connector is present:
- Discover tools through
initialize, notifications/initialized, and
tools/list; never invent tool names or schemas.
- Read authentication.md.
- Reject unresolved OAuth placeholders before producing a deployable ZIP.
- When a source project exists, run
scripts/test_cowork_plugin.py, then
build through scripts/build_cowork_plugin.py. This uses Microsoft 365
Agents Toolkit (atk) for both packaging and package validation.
- For a ZIP-only request, do not run project validation or rebuild it. Treat
the ZIP accepted by
scripts/test_cowork_plugin_package.py as the final
package candidate.
- Return the exact path of the built or successfully validated ZIP.
- When evaluations are requested, read
evaluations.md and use
scripts/new_cowork_plugin_evals.py. Treat generated cases as drafts until
every placeholder has an approved expected response.
- Sideload or deploy only when the user explicitly asks. Keep tenant-wide
deployment approval-gated.
Non-negotiable gates
- Never modify an imported source tree; import from a temporary staging copy.
- Never call a package deployable while OAuth
referenceId contains a
placeholder.
- Never place secrets, tokens, client secrets, or API keys in a manifest,
skill, script, or ZIP.
- A registered skill folder contains exactly one root
SKILL.md. Nested
companion documents must use another filename such as REFERENCE.md or
CAPABILITY.md.
- Skill frontmatter
name must be lowercase kebab-case and match its folder.
manifest.json must be at the ZIP root with no wrapper directory.
Referenced assets may use nested paths, but must resolve within the package.
- Preserve the manifest application ID across upgrades and increment the
package version.
- Do not use raw
Compress-Archive as the final acceptance gate.
- Do not fabricate a successful MCP connection from package validation;
authentication and allowed-client configuration must also succeed.
Standard commands
Use python3 in the Cowork Linux runtime and on Linux/macOS. On Windows,
replace python3 with py -3. Keep each command on one line so it works
without shell-specific continuation syntax.
# Validate a project without building.
python3 scripts/test_cowork_plugin.py --project-path <project>
# Validate an existing ZIP without trusting its contents.
python3 scripts/test_cowork_plugin_package.py --package-path <package.zip>
# Insert the Teams Developer Portal OAuth client registration ID.
python3 scripts/set_cowork_oauth_reference.py --project-path <project> --connector-id <connector-id> --oauth-configuration-id <generated-id>
# Build and validate the upload package.
python3 scripts/build_cowork_plugin.py --project-path <project>
# Generate a draft behavioral evaluation suite.
python3 scripts/new_cowork_plugin_evals.py --project-path <project>
Troubleshooting
Read troubleshooting.md and map the observed
HTTP status, endpoint, and response body to a specific layer:
- Package/manifest
- OAuth configuration lookup
- User sign-in or consent
- MCP allowed-client policy
- MCP protocol handshake
- Tool invocation
Do not repeatedly retry configuration errors.
Dynamic Microsoft documentation
| Topic |
Search |
| Current Cowork package schema |
microsoft_docs_search(query="Build plugins for Copilot Cowork manifest validation rules") |
| Connector authentication |
microsoft_docs_search(query="Cowork MCP OAuthPluginVault authentication configuration") |
| Agents Toolkit commands |
microsoft_docs_search(query="Microsoft 365 Agents Toolkit CLI import openplugin package validate") |
| Dataverse MCP setup |
microsoft_docs_search(query="Dataverse MCP remote endpoint allowed clients Entra app") |
| Evaluation dataset schema |
microsoft_docs_search(query="Microsoft 365 Copilot Agent Evaluations CLI dataset schema test design") |
If Learn MCP tools are unavailable, use:
| MCP tool |
CLI equivalent |
microsoft_docs_search |
npx --yes @microsoft/learn-cli search "<query>" |
microsoft_docs_fetch |
npx --yes @microsoft/learn-cli fetch "<url>" |
microsoft_code_sample_search |
npx --yes @microsoft/learn-cli code-search "<query>" --language <language> |
References
- Package contract
- Authentication
- Import and normalization
- Evaluation design
- Troubleshooting
1---2name: cowork-plugin-engineer3description: Use this skill whenever a user asks to create, import, repair, authenticate, package, validate, sideload, evaluate, upgrade, or troubleshoot a Microsoft Copilot Cowork plugin containing Agent Skills or remote Model Context Protocol (MCP) connectors.4metadata:5 source: https://skillmd.com/skills/microsoft/cowork-plugin-engineer6---78# Copilot Cowork Plugin Engineer910Build upload-ready Cowork plugins with deterministic validation. Treat the11Microsoft 365 app package, its authentication configuration, and its deployment12as separate gates.1314## Mandatory workflow15161. Read [package-contract.md](references/package-contract.md).172. Search current Microsoft Learn documentation before choosing a manifest18 version or making rollout, preview, authentication, or licensing claims.19 For a manifest baseline upgrade, follow20 [manifest-upgrade-instructions.md](assets/manifest-upgrade-instructions.md).213. Inspect the source without modifying it. Detect:22 - Native Microsoft 365 app package23 - Claude, Cursor, or Agent Plugin package24 - Skills-only folder25 - Existing Agents Toolkit project264. Choose the workflow:27 - New project: use `scripts/new_cowork_plugin_project.py`.28 - Open plugin import: follow29 [import-and-normalization.md](references/import-and-normalization.md).30 - Existing project: validate before editing.31 - Existing ZIP: use `scripts/test_cowork_plugin_package.py`; never extract32 an untrusted archive without its path and expansion safeguards.335. If an MCP connector is present:34 - Discover tools through `initialize`, `notifications/initialized`, and35 `tools/list`; never invent tool names or schemas.36 - Read [authentication.md](references/authentication.md).37 - Reject unresolved OAuth placeholders before producing a deployable ZIP.386. When a source project exists, run `scripts/test_cowork_plugin.py`, then39 build through `scripts/build_cowork_plugin.py`. This uses Microsoft 36540 Agents Toolkit (`atk`) for both packaging and package validation.417. For a ZIP-only request, do not run project validation or rebuild it. Treat42 the ZIP accepted by `scripts/test_cowork_plugin_package.py` as the final43 package candidate.448. Return the exact path of the built or successfully validated ZIP.459. When evaluations are requested, read46 [evaluations.md](references/evaluations.md) and use47 `scripts/new_cowork_plugin_evals.py`. Treat generated cases as drafts until48 every placeholder has an approved expected response.4910. Sideload or deploy only when the user explicitly asks. Keep tenant-wide50 deployment approval-gated.5152## Non-negotiable gates5354- Never modify an imported source tree; import from a temporary staging copy.55- Never call a package deployable while OAuth `referenceId` contains a56 placeholder.57- Never place secrets, tokens, client secrets, or API keys in a manifest,58 skill, script, or ZIP.59- A registered skill folder contains exactly one root `SKILL.md`. Nested60 companion documents must use another filename such as `REFERENCE.md` or61 `CAPABILITY.md`.62- Skill frontmatter `name` must be lowercase kebab-case and match its folder.63- `manifest.json` must be at the ZIP root with no wrapper directory.64 Referenced assets may use nested paths, but must resolve within the package.65- Preserve the manifest application ID across upgrades and increment the66 package version.67- Do not use raw `Compress-Archive` as the final acceptance gate.68- Do not fabricate a successful MCP connection from package validation;69 authentication and allowed-client configuration must also succeed.7071## Standard commands7273Use `python3` in the Cowork Linux runtime and on Linux/macOS. On Windows,74replace `python3` with `py -3`. Keep each command on one line so it works75without shell-specific continuation syntax.7677```sh78# Validate a project without building.79python3 scripts/test_cowork_plugin.py --project-path <project>8081# Validate an existing ZIP without trusting its contents.82python3 scripts/test_cowork_plugin_package.py --package-path <package.zip>8384# Insert the Teams Developer Portal OAuth client registration ID.85python3 scripts/set_cowork_oauth_reference.py --project-path <project> --connector-id <connector-id> --oauth-configuration-id <generated-id>8687# Build and validate the upload package.88python3 scripts/build_cowork_plugin.py --project-path <project>8990# Generate a draft behavioral evaluation suite.91python3 scripts/new_cowork_plugin_evals.py --project-path <project>92```9394## Troubleshooting9596Read [troubleshooting.md](references/troubleshooting.md) and map the observed97HTTP status, endpoint, and response body to a specific layer:98991. Package/manifest1002. OAuth configuration lookup1013. User sign-in or consent1024. MCP allowed-client policy1035. MCP protocol handshake1046. Tool invocation105106Do not repeatedly retry configuration errors.107108## Dynamic Microsoft documentation109110| Topic | Search |111|---|---|112| Current Cowork package schema | `microsoft_docs_search(query="Build plugins for Copilot Cowork manifest validation rules")` |113| Connector authentication | `microsoft_docs_search(query="Cowork MCP OAuthPluginVault authentication configuration")` |114| Agents Toolkit commands | `microsoft_docs_search(query="Microsoft 365 Agents Toolkit CLI import openplugin package validate")` |115| Dataverse MCP setup | `microsoft_docs_search(query="Dataverse MCP remote endpoint allowed clients Entra app")` |116| Evaluation dataset schema | `microsoft_docs_search(query="Microsoft 365 Copilot Agent Evaluations CLI dataset schema test design")` |117118If Learn MCP tools are unavailable, use:119120| MCP tool | CLI equivalent |121|---|---|122| `microsoft_docs_search` | `npx --yes @microsoft/learn-cli search "<query>"` |123| `microsoft_docs_fetch` | `npx --yes @microsoft/learn-cli fetch "<url>"` |124| `microsoft_code_sample_search` | `npx --yes @microsoft/learn-cli code-search "<query>" --language <language>` |125126## References127128- [Package contract](references/package-contract.md)129- [Authentication](references/authentication.md)130- [Import and normalization](references/import-and-normalization.md)131- [Evaluation design](references/evaluations.md)132- [Troubleshooting](references/troubleshooting.md)