teams-app-developer

---
name: teams-app-developer
description: "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."
---

# Microsoft 365 Agents Toolkit Skill

Build Microsoft 365 agents and Teams apps using the ATK CLI.

## AI Behavior Guidelines

1. **Testing Strategy:** Recommend Agents Playground first (faster, no M365 needed). Use Teams workflow only if user explicitly requests it.

2. **Environment Variables:** NEVER hardcode secrets or make up placeholder values. Always ask users for real values.

3. **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](troubleshoot/troubleshoot.md) for full diagnostic steps

4. **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+)

5. **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

6. **Monitor App Logs:** Periodically check background terminal output for runtime errors. If the app crashes, read the error, fix the root cause, and restart.

7. **Telemetry Tagging:** Before running any `atk` CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:
   ```bash
   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

```bash
atk --version  # Must be > 1.1.5-beta
```

If ATK is not found or version is too old:

```bash
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](create-project/create-project.md)         |
| **test-playground**  | Test locally with Agents Playground, `agentsplayground`, quick testing           | [test-playground/test-playground.md](test-playground/test-playground.md)     |
| **test-teams**       | Run on Teams, devtunnel, sideload, Teams testing, test in Copilot                | [test-teams/test-teams.md](test-teams/test-teams.md)                         |
| **provision-deploy** | Provision Azure resources, deploy to cloud, `atk provision`, `atk deploy`        | [provision-deploy/provision-deploy.md](provision-deploy/provision-deploy.md) |
| **troubleshoot**     | Fix errors, 401, port conflicts, YAML errors, stale bots                         | [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md)                 |
| **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)                           |

> **MANDATORY:** Before executing any workflow, read the corresponding sub-skill document.

## Shared References

- [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) — Project files, YAML config, env vars, .localConfigs flow
- [commands.md](toolkit/commands.md) — ATK CLI commands: package, validate, share, collaborate
- [templates.md](toolkit/templates.md) — Complete template catalog with language support
- [experts/](experts/index.md) — 100+ micro-expert files: Teams SDK, Slack SDK, cross-platform bridging, deploy, AI models, security, language conversion
- [docs/](docs/README.md) — 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](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](toolkit/manifest-and-yaml.md) for full config-file details.

• SKILL.md 8 KB
• create-project/create-project.md 8 KB
• docs/README.md 3 KB
• docs/advanced-features.md 7 KB
• docs/feature-gaps.md 46 KB
• docs/files-and-links.md 4 KB
• docs/identity-and-auth.md 4 KB
• docs/infrastructure.md 7 KB
• docs/interactive-responses.md 4 KB
• docs/messaging-and-commands.md 5 KB
• docs/middleware-and-handlers.md 4 KB
• docs/ui-components.md 7 KB
• docs/workflows.md 14 KB
• experts/README.md 9 KB
• experts/_expert-ts.md 2 KB
• experts/analyzer.md 14 KB
• experts/builder.md 11 KB
• experts/fallback.md 2 KB
• experts/index.md 19 KB
• experts/prompt-engineer.md 15 KB
• experts/researcher.md 3 KB
• experts/update-experts.md 10 KB
• experts/bridge/app-distribution-packaging-ts.md 14 KB
• experts/bridge/channel-ops-graph-ts.md 15 KB
• experts/bridge/commands-slash-text-ts.md 19 KB
• experts/bridge/cross-platform-advisor-ts.md 36 KB
• experts/bridge/cross-platform-architecture-ts.md 8 KB
• experts/bridge/events-activities-ts.md 22 KB
• experts/bridge/files-upload-download-ts.md 17 KB
• experts/bridge/identity-oauth-bridge-ts.md 20 KB
• experts/bridge/index.md 13 KB
• experts/bridge/infra-compute-ts.md 15 KB
• experts/bridge/infra-observability-ts.md 14 KB
• experts/bridge/infra-secrets-config-ts.md 13 KB
• experts/bridge/infra-storage-ts.md 14 KB
• experts/bridge/interactive-responses-ts.md 20 KB
• experts/bridge/link-unfurl-preview-ts.md 17 KB
• experts/bridge/middleware-handlers-ts.md 15 KB
• experts/bridge/python-cross-platform.md 9 KB
• experts/bridge/rate-limiting-resilience-ts.md 18 KB
• experts/bridge/rest-only-integration-ts.md 8 KB
• experts/bridge/scheduling-deferred-send-ts.md 18 KB
• experts/bridge/shortcuts-extensions-ts.md 18 KB
• experts/bridge/transport-socketmode-https-ts.md 14 KB
• experts/bridge/ui-app-home-personal-tab-ts.md 15 KB
• experts/bridge/ui-block-kit-adaptive-cards-ts.md 22 KB
• experts/bridge/ui-legacy-attachments-cards-ts.md 11 KB
• experts/bridge/ui-modals-dialogs-ts.md 21 KB
• experts/bridge/workflow.composable-platform-ts.md 14 KB
• experts/bridge/workflows-automation-ts.md 14 KB
• experts/convert/bulk-conversion-strategy-ts.md 13 KB
• experts/convert/dependency-mapping-ts.md 8 KB
• experts/convert/index.md 3 KB
• experts/convert/java-to-ts-ts.md 21 KB
• experts/convert/js-to-ts-ts.md 6 KB
• experts/convert/json-serialization-ts.md 11 KB
• experts/convert/kotlin-to-ts-ts.md 11 KB
• experts/convert/ruby-to-ts-ts.md 10 KB
• experts/convert/type-mapping-ts.md 10 KB
• experts/deploy/aws-bot-deploy-ts.md 15 KB
• experts/deploy/aws-cli-reference-ts.md 52 KB
• experts/deploy/azure-bot-deploy-ts.md 15 KB
• experts/deploy/azure-cli-reference-ts.md 17 KB
• experts/deploy/index.md 5 KB
• experts/models/anthropic-ts.md 8 KB
• experts/models/bedrock-ts.md 10 KB
• experts/models/foundry-cloud-ts.md 8 KB
• experts/models/foundry-local-ts.md 11 KB
• experts/models/index.md 6 KB
• experts/models/openai-azure-openai-ts.md 8 KB
• experts/models/oss-openai-compatible-ts.md 11 KB
• experts/models/transformers-js-ts.md 12 KB
• experts/security/index.md 1 KB
• experts/security/input-validation-ts.md 14 KB
• experts/security/secrets-ts.md 14 KB
• experts/slack/bolt-assistant-ts.md 10 KB
• experts/slack/bolt-events-ts.md 9 KB
• experts/slack/bolt-java.md 9 KB
• experts/slack/bolt-oauth-distribution-ts.md 11 KB
• experts/slack/bolt-python.md 10 KB
• experts/slack/cli.app-management.md 8 KB
• experts/slack/cli.datastore-env.md 9 KB
• experts/slack/cli.getting-started.md 8 KB
• experts/slack/cli.local-dev-deploy.md 8 KB
• experts/slack/cli.manifest-triggers.md 10 KB
• experts/slack/index.md 9 KB
• experts/slack/runtime.ack-rules-ts.md 10 KB
• experts/slack/runtime.bolt-foundations-ts.md 11 KB
• experts/slack/runtime.shortcuts-ts.md 11 KB
• experts/slack/runtime.slash-commands-ts.md 12 KB
• experts/slack/runtime.socket-mode-ts.md 9 KB
• experts/slack/ui.block-kit-ts.md 11 KB
• experts/slack/ui.modals-lifecycle-ts.md 13 KB
• experts/slack/web-api-proactive-ts.md 11 KB
• experts/slack/workflow.slack-automations-ts.md 10 KB
• experts/teams/a2a.client-basics-ts.md 10 KB
• experts/teams/a2a.orchestrator-patterns-ts.md 13 KB
• experts/teams/a2a.server-basics-ts.md 11 KB
• experts/teams/ai.chatprompt-basics-ts.md 8 KB
• experts/teams/ai.citations-feedback-ts.md 7 KB
• experts/teams/ai.conversational-query-ts.md 14 KB
• experts/teams/ai.function-calling-design-ts.md 9 KB
• experts/teams/ai.function-calling-implementation-ts.md 8 KB
• experts/teams/ai.memory-localmemory-ts.md 7 KB
• experts/teams/ai.model-setup-ts.md 7 KB
• experts/teams/ai.rag-retrieval-ts.md 7 KB
• experts/teams/ai.rag-vectorstores-ts.md 9 KB
• experts/teams/ai.streaming-ts.md 7 KB
• experts/teams/auth.oauth-sso-ts.md 10 KB
• experts/teams/compat.botbuilder-interop-ts.md 15 KB
• experts/teams/dev.debug-test-ts.md 14 KB
• experts/teams/graph.usergraph-appgraph-ts.md 9 KB
• experts/teams/index.md 10 KB
• experts/teams/mcp.client-basics-ts.md 9 KB
• experts/teams/mcp.expose-chatprompt-tools-ts.md 10 KB
• experts/teams/mcp.security-ts.md 10 KB
• experts/teams/mcp.server-basics-ts.md 10 KB
• experts/teams/project.scaffold-files-ts.md 12 KB
• experts/teams/runtime.app-init-ts.md 11 KB
• experts/teams/runtime.manifest-ts.md 12 KB
• experts/teams/runtime.proactive-messaging-ts.md 13 KB
• experts/teams/runtime.routing-handlers-ts.md 12 KB
• experts/teams/state.storage-patterns-ts.md 9 KB
• experts/teams/teams-dotnet.md 8 KB
• experts/teams/teams-python.md 8 KB
• experts/teams/ui.adaptive-cards-ts.md 13 KB
• experts/teams/ui.dialogs-task-modules-ts.md 15 KB
• experts/teams/ui.message-extensions-ts.md 16 KB
• experts/teams/workflow.approvals-inline-ts.md 12 KB
• experts/teams/workflow.message-native-records-ts.md 11 KB
• experts/teams/workflow.sharepoint-lists-ts.md 9 KB
• experts/teams/workflow.state-driven-events-ts.md 12 KB
• experts/teams/workflow.triggers-compose-ts.md 10 KB
• provision-deploy/provision-deploy.md 4 KB
• slack-to-teams/SKILL.md 9 KB
• test-playground/playground-cli.md 5 KB
• test-playground/playground.md 5 KB
• test-playground/test-playground.md 1 KB
• test-teams/test-teams.md 5 KB
• toolkit/README.md 4 KB
• toolkit/commands.md 3 KB
• toolkit/environments.md 13 KB
• toolkit/lifecycle-cli.md 18 KB
• toolkit/manifest-and-yaml.md 6 KB
• toolkit/playground.md 8 KB
• toolkit/publish.md 9 KB
• toolkit/templates.md 7 KB
• troubleshoot/troubleshoot.md 20 KB