Index of every page on this site: llms.txt
All skills
microsoft avatar

/teams-app-developer

@0d60658
by microsoftmicrosoft/skills3.2k stars
373
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/microsoft/skills/teams-app-developer

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈140 tokens for metadata: the name and description. ≈1.8k when used: this file. ≈426k more on demand in 147 files.

Description uses 7.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈562 characters, or 7.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 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:

    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: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    This skill provides a comprehensive developer guide for building Microsoft 365 agents and Teams applications. It includes several security considerations such as handling untrusted user input, using dynamic execution in examples, and reading sensitive local files for protocol requirements. These patterns are presented with appropriate security warnings and architectural mitigations. See detailed analysis for more context.

  • Socket1mo

    2 alerts: gptAnomaly

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 0d60658. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago

README badge

README badge for microsoft/skills/teams-app-developer