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.

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

1. 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

1. 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+)

1. 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

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

1. 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 | | 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.