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.
Source: microsoft/skills → .github/plugins/microsoft-365-agents-toolkit/skills/teams-app-developer/SKILL.md
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---567# Microsoft 365 Agents Toolkit Skill89Build Microsoft 365 agents and Teams apps using the ATK CLI.1011## AI Behavior Guidelines12131. **Testing Strategy:** Recommend Agents Playground first (faster, no M365 needed). Use Teams workflow only if user explicitly requests it.14152. **Environment Variables:** NEVER hardcode secrets or make up placeholder values. Always ask users for real values.16173. **Error Handling:** Read error messages carefully. Check `env/.env.local`, `.localConfigs`, and `atk auth list`. Common pitfalls:18 - **`AADSTS7000229`** → `aadApp/create` missing `generateServicePrincipal: true` in YAML — add it and re-provision19 - **Missing `TENANT_ID`** in `.localConfigs` → SDK uses wrong token authority → 401 from Bot Connector20 - **401 persists after auth fix** → devtunnel URL may be blacklisted — create a fresh tunnel21 - See [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md) for full diagnostic steps22234. **Long-Running Commands — WAIT for completion:**24 - `atk new`, `atk provision`, `atk deploy` can take several minutes25 - Always wait for completion before running the next step (timeout 120000ms+)26275. **Local Service Startup — Hangs terminal (expected):**28 - `npm run dev`, `npm start`, `python app.py`, `devtunnel host`, etc. will hang — the process keeps running indefinitely29 - ALWAYS run as a background process (`isBackground=true`) — NEVER use `isBackground=false` for these commands30 - Do NOT wait for it to "finish" — verify startup by checking output for "listening on port" or tunnel URL31 - If errors appear, read logs, diagnose, fix, restart32 - Use a **NEW terminal** to launch Agents Playground or open Teams sideloading URL33346. **Monitor App Logs:** Periodically check background terminal output for runtime errors. If the app crashes, read the error, fix the root cause, and restart.35367. **Telemetry Tagging:** Before running any `atk` CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:37 ```bash38 export ATK_CLI_SKILL=true39 ```40 Run this once at the start of the session. All subsequent `atk` commands in the same terminal will inherit it.4142## ATK CLI Setup4344```bash45atk --version # Must be > 1.1.5-beta46```4748If ATK is not found or version is too old:4950```bash51npm i -g @microsoft/m365agentstoolkit-cli@beta52```5354## CLI Global Options5556| Option | Meaning | Recommendation |57| ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |58| `-i` | Interactive mode | Always use `-i false` in automation to avoid hanging |59| `-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. |60| `-h` | Command help | Use `atk <command> -h` for quick syntax checks |6162## Sub-Skills6364| Sub-Skill | When to Use | Reference |65| -------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |66| **create-project** | Scaffold new project from template, choose template, `atk new` | [create-project/create-project.md](create-project/create-project.md) |67| **test-playground** | Test locally with Agents Playground, `agentsplayground`, quick testing | [test-playground/test-playground.md](test-playground/test-playground.md) |68| **test-teams** | Run on Teams, devtunnel, sideload, Teams testing, test in Copilot | [test-teams/test-teams.md](test-teams/test-teams.md) |69| **provision-deploy** | Provision Azure resources, deploy to cloud, `atk provision`, `atk deploy` | [provision-deploy/provision-deploy.md](provision-deploy/provision-deploy.md) |70| **troubleshoot** | Fix errors, 401, port conflicts, YAML errors, stale bots | [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md) |71| **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) |7273> **MANDATORY:** Before executing any workflow, read the corresponding sub-skill document.7475## Shared References7677- [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) — Project files, YAML config, env vars, .localConfigs flow78- [commands.md](toolkit/commands.md) — ATK CLI commands: package, validate, share, collaborate79- [templates.md](toolkit/templates.md) — Complete template catalog with language support80- [experts/](experts/index.md) — 100+ micro-expert files: Teams SDK, Slack SDK, cross-platform bridging, deploy, AI models, security, language conversion81- [docs/](docs/README.md) — Platform comparison guides: UI, messaging, identity, infrastructure, feature gaps8283## Workflow Chains8485Match user intent to the smallest valid workflow.8687| User Intent | Workflow (read in order) |88| ----------------------------- | ------------------------------------------- |89| Build new app from scratch | create-project → test-playground |90| Test existing project locally | test-playground (recommended) or test-teams |91| Deploy to Azure | provision-deploy |92| Fix broken bot | troubleshoot → re-test |93| Migrate Slack bot to Teams | slack-to-teams |9495> **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.9697## ATK Project Context Resolution9899Resolve config values only when missing. If a value is already known in the session, reuse it.100101### Step 1: Detect ATK Project102103If `m365agentstoolkit*.yml` exists in the current folder, treat it as an ATK project and parse configuration.104105### Step 2: Resolve Common Configuration106107Resolve variables referenced in `m365agentstoolkit*.yml`. Common variables:108AZURE_OPENAI_API_KEY109AZURE_OPENAI_ENDPOINT110AZURE_OPENAI_DEPLOYMENT_NAME111112### Step 3: Collect Missing Values113114If required values are missing, ask the user for only the missing ones.115116Refer to [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) for full config-file details.117118---119120**Source:** [`microsoft/skills`](https://github.com/microsoft/skills) → `.github/plugins/microsoft-365-agents-toolkit/skills/teams-app-developer/SKILL.md`
thedixitjain