Microsoft 365 Agents Toolkit Skill
Build Microsoft 365 agents and Teams apps using the ATK CLI.
AI Behavior Guidelines
Testing Strategy: Recommend Agents Playground first (faster, no M365 needed). Use Teams workflow only if user explicitly requests it.
Environment Variables: NEVER hardcode secrets or make up placeholder values. Always ask users for real values.
Error Handling: Read error messages carefully. Check env/.env.local, .localConfigs, and atk auth list. Common pitfalls:
AADSTS7000229 → aadApp/create missing generateServicePrincipal: true in YAML — add it and re-provision- Missing
TENANT_ID in .localConfigs → SDK uses wrong token authority → 401 from Bot Connector
- 401 persists after auth fix → devtunnel URL may be blacklisted — create a fresh tunnel
- See troubleshoot/troubleshoot.md for full diagnostic steps
Long-Running Commands — WAIT for completion:
atk new, atk provision, atk deploy can take several minutes- Always wait for completion before running the next step (timeout 120000ms+)
Local Service Startup — Hangs terminal (expected):
npm run dev, npm start, python app.py, devtunnel host, etc. will hang — the process keeps running indefinitely- ALWAYS run as a background process (
isBackground=true) — NEVER use isBackground=false for these commands
- Do NOT wait for it to "finish" — verify startup by checking output for "listening on port" or tunnel URL
- If errors appear, read logs, diagnose, fix, restart
- Use a NEW terminal to launch Agents Playground or open Teams sideloading URL
Monitor App Logs: Periodically check background terminal output for runtime errors. If the app crashes, read the error, fix the root cause, and restart.
Telemetry Tagging: Before running any atk CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:
export ATK_CLI_SKILL=true
Run this once at the start of the session. All subsequent atk commands in the same terminal will inherit it.
ATK CLI Setup
atk --version # Must be > 1.1.5-beta
If ATK is not found or version is too old:
npm i -g @microsoft/m365agentstoolkit-cli@beta
CLI Global Options
| Option |
Meaning |
Recommendation |
-i |
Interactive mode |
Always use -i false in automation to avoid hanging |
-f |
Project folder |
Default to be current directory, used when specifying a custom folder. When scaffolding a new project, this is the parent folder where the project folder will be created under. |
-h |
Command help |
Use atk <command> -h for quick syntax checks |
Sub-Skills
| Sub-Skill |
When to Use |
Reference |
| create-project |
Scaffold new project from template, choose template, atk new |
create-project/create-project.md |
| test-playground |
Test locally with Agents Playground, agentsplayground, quick testing |
test-playground/test-playground.md |
| test-teams |
Run on Teams, devtunnel, sideload, Teams testing, test in Copilot |
test-teams/test-teams.md |
| provision-deploy |
Provision Azure resources, deploy to cloud, atk provision, atk deploy |
provision-deploy/provision-deploy.md |
| troubleshoot |
Fix errors, 401, port conflicts, YAML errors, stale bots |
troubleshoot/troubleshoot.md |
| slack-to-teams |
Migrate Slack bot to Teams, cross-platform bridging, Block Kit to Adaptive Cards |
slack-to-teams/SKILL.md |
MANDATORY: Before executing any workflow, read the corresponding sub-skill document.
Shared References
- manifest-and-yaml.md — Project files, YAML config, env vars, .localConfigs flow
- commands.md — ATK CLI commands: package, validate, share, collaborate
- templates.md — Complete template catalog with language support
- experts/ — 100+ micro-expert files: Teams SDK, Slack SDK, cross-platform bridging, deploy, AI models, security, language conversion
- docs/ — Platform comparison guides: UI, messaging, identity, infrastructure, feature gaps
Workflow Chains
Match user intent to the smallest valid workflow.
| User Intent |
Workflow (read in order) |
| Build new app from scratch |
create-project → test-playground |
| Test existing project locally |
test-playground (recommended) or test-teams |
| Deploy to Azure |
provision-deploy |
| Fix broken bot |
troubleshoot → re-test |
| Migrate Slack bot to Teams |
slack-to-teams |
MANDATORY: Before executing any slack-to-teams workflow, read slack-to-teams/SKILL.md first. The sub-skill contains a routed expert system with 100+ micro-expert files for cross-platform bot development.
ATK Project Context Resolution
Resolve config values only when missing. If a value is already known in the session, reuse it.
Step 1: Detect ATK Project
If m365agentstoolkit*.yml exists in the current folder, treat it as an ATK project and parse configuration.
Step 2: Resolve Common Configuration
Resolve variables referenced in m365agentstoolkit*.yml. Common variables:
AZURE_OPENAI_API_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_DEPLOYMENT_NAME
Step 3: Collect Missing Values
If required values are missing, ask the user for only the missing ones.
Refer to manifest-and-yaml.md for full config-file details.
1---2name: teams-app-developer3description: Builds, tests, and deploys Microsoft 365 apps and agents for Teams and Copilot. Includes sub-skills for project creation, local testing, cloud deployment, troubleshooting, and Slack-to-Teams migration. USE FOR: Teams agent, bot, tab, message extension, Declarative Agents, Custom Engine Agents, local testing, Agents Playground, Azure resource provision, remote deployment, Slack to Teams migration, cross-platform bot development, Block Kit to Adaptive Cards conversion. DO NOT USE FOR: general web development, non-bot/non-Teams projects.4---56# Microsoft 365 Agents Toolkit Skill78Build Microsoft 365 agents and Teams apps using the ATK CLI.910## AI Behavior Guidelines11121. **Testing Strategy:** Recommend Agents Playground first (faster, no M365 needed). Use Teams workflow only if user explicitly requests it.13142. **Environment Variables:** NEVER hardcode secrets or make up placeholder values. Always ask users for real values.15163. **Error Handling:** Read error messages carefully. Check `env/.env.local`, `.localConfigs`, and `atk auth list`. Common pitfalls:17 - **`AADSTS7000229`** → `aadApp/create` missing `generateServicePrincipal: true` in YAML — add it and re-provision18 - **Missing `TENANT_ID`** in `.localConfigs` → SDK uses wrong token authority → 401 from Bot Connector19 - **401 persists after auth fix** → devtunnel URL may be blacklisted — create a fresh tunnel20 - See [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md) for full diagnostic steps21224. **Long-Running Commands — WAIT for completion:**23 - `atk new`, `atk provision`, `atk deploy` can take several minutes24 - Always wait for completion before running the next step (timeout 120000ms+)25265. **Local Service Startup — Hangs terminal (expected):**27 - `npm run dev`, `npm start`, `python app.py`, `devtunnel host`, etc. will hang — the process keeps running indefinitely28 - ALWAYS run as a background process (`isBackground=true`) — NEVER use `isBackground=false` for these commands29 - Do NOT wait for it to "finish" — verify startup by checking output for "listening on port" or tunnel URL30 - If errors appear, read logs, diagnose, fix, restart31 - Use a **NEW terminal** to launch Agents Playground or open Teams sideloading URL32336. **Monitor App Logs:** Periodically check background terminal output for runtime errors. If the app crashes, read the error, fix the root cause, and restart.34357. **Telemetry Tagging:** Before running any `atk` CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:36 ```bash37 export ATK_CLI_SKILL=true38 ```39 Run this once at the start of the session. All subsequent `atk` commands in the same terminal will inherit it.4041## ATK CLI Setup4243```bash44atk --version # Must be > 1.1.5-beta45```4647If ATK is not found or version is too old:4849```bash50npm i -g @microsoft/m365agentstoolkit-cli@beta51```5253## CLI Global Options5455| Option | Meaning | Recommendation |56| ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |57| `-i` | Interactive mode | Always use `-i false` in automation to avoid hanging |58| `-f` | Project folder | Default to be current directory, used when specifying a custom folder. When scaffolding a new project, this is the parent folder where the project folder will be created under. |59| `-h` | Command help | Use `atk <command> -h` for quick syntax checks |6061## Sub-Skills6263| Sub-Skill | When to Use | Reference |64| -------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |65| **create-project** | Scaffold new project from template, choose template, `atk new` | [create-project/create-project.md](create-project/create-project.md) |66| **test-playground** | Test locally with Agents Playground, `agentsplayground`, quick testing | [test-playground/test-playground.md](test-playground/test-playground.md) |67| **test-teams** | Run on Teams, devtunnel, sideload, Teams testing, test in Copilot | [test-teams/test-teams.md](test-teams/test-teams.md) |68| **provision-deploy** | Provision Azure resources, deploy to cloud, `atk provision`, `atk deploy` | [provision-deploy/provision-deploy.md](provision-deploy/provision-deploy.md) |69| **troubleshoot** | Fix errors, 401, port conflicts, YAML errors, stale bots | [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md) |70| **slack-to-teams** | Migrate Slack bot to Teams, cross-platform bridging, Block Kit to Adaptive Cards | [slack-to-teams/SKILL.md](slack-to-teams/SKILL.md) |7172> **MANDATORY:** Before executing any workflow, read the corresponding sub-skill document.7374## Shared References7576- [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) — Project files, YAML config, env vars, .localConfigs flow77- [commands.md](toolkit/commands.md) — ATK CLI commands: package, validate, share, collaborate78- [templates.md](toolkit/templates.md) — Complete template catalog with language support79- [experts/](experts/index.md) — 100+ micro-expert files: Teams SDK, Slack SDK, cross-platform bridging, deploy, AI models, security, language conversion80- [docs/](docs/README.md) — Platform comparison guides: UI, messaging, identity, infrastructure, feature gaps8182## Workflow Chains8384Match user intent to the smallest valid workflow.8586| User Intent | Workflow (read in order) |87| ----------------------------- | ------------------------------------------- |88| Build new app from scratch | create-project → test-playground |89| Test existing project locally | test-playground (recommended) or test-teams |90| Deploy to Azure | provision-deploy |91| Fix broken bot | troubleshoot → re-test |92| Migrate Slack bot to Teams | slack-to-teams |9394> **MANDATORY:** Before executing any slack-to-teams workflow, read [slack-to-teams/SKILL.md](slack-to-teams/SKILL.md) first. The sub-skill contains a routed expert system with 100+ micro-expert files for cross-platform bot development.9596## ATK Project Context Resolution9798Resolve config values only when missing. If a value is already known in the session, reuse it.99100### Step 1: Detect ATK Project101102If `m365agentstoolkit*.yml` exists in the current folder, treat it as an ATK project and parse configuration.103104### Step 2: Resolve Common Configuration105106Resolve variables referenced in `m365agentstoolkit*.yml`. Common variables:107AZURE_OPENAI_API_KEY108AZURE_OPENAI_ENDPOINT109AZURE_OPENAI_DEPLOYMENT_NAME110111### Step 3: Collect Missing Values112113If required values are missing, ask the user for only the missing ones.114115Refer to [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) for full config-file details.
gabrielmoreira