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

Non-negotiable gates

Standard commands

Troubleshooting

Dynamic Microsoft documentation

References

cowork-plugin-engineer

Copilot Cowork Plugin Engineer

Mandatory workflow