Add extendToM365 lifecycle guidance to m365-agent-developer skill

sebastienlevert · Copilot · sebastienlevert · commit f4d6f5bc6c1f · 2026-03-09T20:24:27.000Z
- Add 'Scaffold the Agent Project First' section to mcp-plugin.md with
  the 5 required lifecycle steps (especially teamsApp/extendToM365)
- Add Step 0 to the MCP plugin workflow checklist
- Add M365_TITLE_ID / extendToM365 warning to deployment.md

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/plugins/m365-agents-toolkit/skills/m365-agent-developer/references/deployment.md b/plugins/m365-agents-toolkit/skills/m365-agent-developer/references/deployment.md
@@ -66,6 +66,8 @@ atk provision --env custom
 - Generates `M365_TITLE_ID` and adds to env file
 - Sets up authentication and permissions
 
+> **&#9888;&#65039; `M365_TITLE_ID` requires `teamsApp/extendToM365`:** The `M365_TITLE_ID` environment variable is generated by the `teamsApp/extendToM365` lifecycle step during provisioning. Without this step, the Teams app registers but the agent will **not** appear in Copilot Chat. If you scaffolded the project with `atk new`, this step is included automatically. If you set up the project manually, verify that your `m365agents.yml` includes the `teamsApp/extendToM365` lifecycle action &mdash; see the [mcp-plugin.md scaffold section](mcp-plugin.md#scaffold-the-agent-project-first) for the required lifecycle steps.
+
 **&#9888;&#65039; CRITICAL: ALWAYS RENDER THIS AFTER ANY PROVISION OPERATION &#9888;&#65039;**
 
 After EVERY provisioning command (regardless of environment or whether it's first-time or re-provisioning), you MUST render this output:
diff --git a/plugins/m365-agents-toolkit/skills/m365-agent-developer/references/mcp-plugin.md b/plugins/m365-agents-toolkit/skills/m365-agent-developer/references/mcp-plugin.md
@@ -17,6 +17,33 @@ MCP servers expose tools that can be consumed by your agent. Unlike OpenAPI-base
 
 ---
 
+## Scaffold the Agent Project First
+
+Before adding an MCP plugin, you **must** have a scaffolded agent project. Run `atk new` if you haven't already:
+
+```bash
+npx -p @microsoft/m365agentstoolkit-cli@latest atk new \
+  -n my-agent \
+  -c declarative-agent \
+  -i false
+```
+
+This creates `m365agents.yml` (and `m365agents.local.yml`) with the **5 required lifecycle steps**:
+
+| Step | Lifecycle Action | What it does |
+|------|-----------------|--------------|
+| 1 | `teamsApp/create` | Registers the Teams app |
+| 2 | `teamsApp/zipAppPackage` | Packages manifest + icons into a zip |
+| 3 | `teamsApp/validateAppPackage` | Validates the package (icons, schema, etc.) |
+| 4 | `teamsApp/update` | Uploads the package to Teams |
+| 5 | `teamsApp/extendToM365` | **Extends the app to M365 Copilot** &mdash; generates `M365_TITLE_ID` |
+
+**What breaks without `extendToM365`:** If this step is missing, `atk provision` will register the Teams app and generate `TEAMS_APP_ID`, but the agent will **never appear in Copilot Chat** because no `M365_TITLE_ID` is generated. This is the most common reason for "provision succeeded but agent not found" failures.
+
+> **If you already have a project** but are missing `teamsApp/extendToM365`, add it to the `provision` lifecycle in `m365agents.yml` after `teamsApp/update`. See [deployment.md](deployment.md) for the full provisioning reference.
+
+---
+
 ## Step-by-Step Integration
 
 ### Step 1: Get MCP Server URL
@@ -193,6 +220,7 @@ Add the plugin to your `declarative-agent.json`:
 ## Complete Workflow Checklist
 
 ```
+&#9633; Step 0: Scaffold agent project with `atk new` (if not already scaffolded)  &larr; MANDATORY
 &#9633; Step 1: Get MCP server URL from user
 &#9633; Step 2: Run MCP Inspector to discover tools                    &larr; MANDATORY
 &#9633; Step 3: Create {name}-plugin.json with basic structure

-Original file line number
+Diff line change
 - Generates `M365_TITLE_ID` and adds to env file
 - Sets up authentication and permissions
 +> **⚠️ `M365_TITLE_ID` requires `teamsApp/extendToM365`:** The `M365_TITLE_ID` environment variable is generated by the `teamsApp/extendToM365` lifecycle step during provisioning. Without this step, the Teams app registers but the agent will **not** appear in Copilot Chat. If you scaffolded the project with `atk new`, this step is included automatically. If you set up the project manually, verify that your `m365agents.yml` includes the `teamsApp/extendToM365` lifecycle action — see the [mcp-plugin.md scaffold section](mcp-plugin.md#scaffold-the-agent-project-first) for the required lifecycle steps.
++
 **⚠️ CRITICAL: ALWAYS RENDER THIS AFTER ANY PROVISION OPERATION ⚠️**
 After EVERY provisioning command (regardless of environment or whether it's first-time or re-provisioning), you MUST render this output: