Generated banner for Teams App Developer
Generated logo for Teams App Developer

Teams App Developer

MicrosoftOfficialPublished by Microsoft

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Medium risk

From the author

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.
— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The teams-app-developer skill provides a structured framework for managing the lifecycle of Microsoft 365 agents and Teams applications. It leverages the ATK CLI to handle project scaffolding, local testing via the Agents Playground, cloud provisioning on Azure, and troubleshooting. The skill includes specialized guidance for migrating Slack bots to Teams, including converting Block Kit UI to Adaptive Cards, and provides access to an extensive library of micro-expert documentation for cross-platform development.

What it does

  • Scaffolds new Microsoft 365 agents and Teams applications from templates.
  • Facilitates local testing using the Agents Playground or Teams-specific environments.
  • Automates Azure resource provisioning and cloud deployment workflows.
  • Provides diagnostic procedures for common authentication and configuration errors.
  • Supports migration of Slack bots to the Teams platform.
  • Manages project configuration and environment variables for ATK-based projects.

When to use it

  • When starting a new Teams app, bot, or Declarative Agent project.
  • When you need to test an agent locally before deploying to the cloud.
  • When migrating existing Slack bots to the Microsoft Teams ecosystem.
  • When troubleshooting deployment or authentication issues in a Teams project.
  • When you need to provision Azure infrastructure for a Teams application.

Advantages

  • Streamlines the development lifecycle with standardized CLI commands.
  • Reduces development time by offering a local testing playground.
  • Provides expert-level guidance for complex cross-platform migrations.
  • Ensures consistent configuration management across development environments.
  • Includes robust error-handling protocols for common platform-specific pitfalls.

Usage examples

“Create a new Teams bot project using the default template.”
The agent will initialize a new project folder, configure the necessary YAML files, and guide you through the initial setup using the ATK CLI.
“How do I migrate my Slack bot to Microsoft Teams?”
The agent will initiate the slack-to-teams workflow, providing access to cross-platform bridging experts and guidance on converting UI components.
“My Teams bot is returning a 401 error, how do I fix it?”
The agent will trigger the troubleshooting workflow, checking your environment variables, tunnel status, and authentication configuration.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/microsoft/teams-app-developer/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip teams-app-developer.zip -d .agents/skills

Documentation by Microsoft

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

OptionMeaningRecommendation
-iInteractive modeAlways use -i false in automation to avoid hanging
-fProject folderDefault 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.
-hCommand helpUse atk <command> -h for quick syntax checks

Sub-Skills

Sub-SkillWhen to UseReference
create-projectScaffold new project from template, choose template, atk newcreate-project/create-project.md
test-playgroundTest locally with Agents Playground, agentsplayground, quick testingtest-playground/test-playground.md
test-teamsRun on Teams, devtunnel, sideload, Teams testing, test in Copilottest-teams/test-teams.md
provision-deployProvision Azure resources, deploy to cloud, atk provision, atk deployprovision-deploy/provision-deploy.md
troubleshootFix errors, 401, port conflicts, YAML errors, stale botstroubleshoot/troubleshoot.md
slack-to-teamsMigrate Slack bot to Teams, cross-platform bridging, Block Kit to Adaptive Cardsslack-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 IntentWorkflow (read in order)
Build new app from scratchcreate-project → test-playground
Test existing project locallytest-playground (recommended) or test-teams
Deploy to Azureprovision-deploy
Fix broken bottroubleshoot → re-test
Migrate Slack bot to Teamsslack-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.

Files

experts/teams/a2a.server-basics-ts.md

a2a.server-basics-ts

purpose

Exposing a Teams bot as an A2A agent with AgentCard definition, A2APlugin setup, and a2a:message event handling.

rules

  1. Create an A2APlugin with new A2APlugin({ agentCard }) where agentCard is an AgentCard object describing your agent's identity and capabilities. The plugin registers the A2A HTTP endpoint automatically. github.com/microsoft/teams.ts

  2. The AgentCard must include these required fields: name, description, url, version, protocolVersion, capabilities, and skills. The url must match the A2A endpoint (e.g., http://localhost:3978/a2a). google.github.io/A2A -- Agent Card

  3. Set protocolVersion to '0.3.0' to match the current A2A protocol version. Client agents use this to verify compatibility before sending messages. google.github.io/A2A -- Protocol

  4. Define skills as an array of objects with id, name, description, and optionally tags and examples. Skills describe what your agent can do. Client agents and LLMs use skill descriptions to decide when to delegate to your agent. google.github.io/A2A -- Skills

  5. Handle incoming A2A messages with app.event('a2a:message', handler). The handler receives { respond, requestContext } where requestContext.userMessage.parts contains the message parts sent by the calling agent. github.com/microsoft/teams.ts

  6. Extract text input from message parts by filtering for kind === 'text': requestContext.userMessage.parts.filter((p) => p.kind === 'text').at(0)?.text. Always check for the text part before processing. github.com/microsoft/teams.ts

  7. Send responses using the respond(text) helper function. This sends a text response back to the calling agent through the A2A protocol. github.com/microsoft/teams.ts

  8. Add the A2APlugin to the App's plugins array. The plugin registers two HTTP routes: the A2A message endpoint at /a2a and the agent card at /a2a/.well-known/agent-card.json. github.com/microsoft/teams.ts

  9. Install @microsoft/teams.a2a as a dependency. If the agent uses AI to process messages, also install @microsoft/teams.ai and @microsoft/teams.openai. github.com/microsoft/teams.ts

  10. Keep skill descriptions specific and actionable. Vague descriptions like "general assistant" cause LLM orchestrators to delegate inappropriately. Include example queries in the examples array to guide delegation decisions. google.github.io/A2A -- Best practices

patterns

Basic A2A server with AI processing
import { App } from '@microsoft/teams.apps';
import { A2APlugin } from '@microsoft/teams.a2a';
import { ChatPrompt } from '@microsoft/teams.ai';
import { OpenAIChatModel } from '@microsoft/teams.openai';
import { ConsoleLogger } from '@microsoft/teams.common';
import { DevtoolsPlugin } from '@microsoft/teams.dev';

const model = new OpenAIChatModel({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o',
});

const prompt = new ChatPrompt({
  model,
  instructions: 'You are a weather expert. Provide weather information for requested locations.',
});

const agentCard = {
  name: 'Weather Agent',
  description: 'An agent that provides weather information',
  url: 'http://localhost:3978/a2a',
  version: '0.0.1',
  protocolVersion: '0.3.0',
  capabilities: {},
  skills: [
    {
      id: 'get_weather',
      name: 'Get Weather',
      description: 'Get current weather conditions for a location',
      tags: ['weather', 'forecast'],
      examples: ['What is the weather in London?', 'Temperature in Tokyo'],
    },
  ],
};

const app = new App({
  logger: new ConsoleLogger('weather-agent', { level: 'debug' }),
  plugins: [new DevtoolsPlugin(), new A2APlugin({ agentCard })],
});

// Handle incoming A2A messages from other agents
app.event('a2a:message', async ({ respond, requestContext }) => {
  const textInput = requestContext.userMessage.parts
    .filter((p: any) => p.kind === 'text')
    .at(0)?.text;

  if (!textInput) {
    await respond('I only support text input.');
    return;
  }

  // Process with AI and respond
  const result = await prompt.send(textInput);
  await respond(result.content || 'No response available.');
});

// Also handle direct Teams messages
app.on('message', async ({ send, activity }) => {
  const result = await prompt.send(activity.text);
  if (result.content) await send(result.content);
});

app.start(3978);
// A2A endpoint: http://localhost:3978/a2a
// Agent card: http://localhost:3978/a2a/.well-known/agent-card.json
Multi-skill agent card
import { A2APlugin } from '@microsoft/teams.a2a';

const agentCard = {
  name: 'IT Help Desk Agent',
  description: 'An agent that handles IT support requests, password resets, and ticket creation',
  url: 'http://localhost:3978/a2a',
  version: '1.0.0',
  protocolVersion: '0.3.0',
  capabilities: {},
  skills: [
    {
      id: 'password_reset',
      name: 'Password Reset',
      description: 'Initiate a password reset for a user account',
      tags: ['password', 'account', 'reset'],
      examples: [
        'Reset password for user [email protected]',
        'I forgot my password',
      ],
    },
    {
      id: 'create_ticket',
      name: 'Create Support Ticket',
      description: 'Create a new IT support ticket with priority and description',
      tags: ['ticket', 'support', 'helpdesk'],
      examples: [
        'Create a high priority ticket for laptop replacement',
        'Submit a ticket about VPN issues',
      ],
    },
    {
      id: 'check_status',
      name: 'Check Ticket Status',
      description: 'Check the status of an existing support ticket by ID',
      tags: ['ticket', 'status'],
      examples: [
        'What is the status of ticket IT-1234?',
        'Check my open tickets',
      ],
    },
  ],
};

const a2aPlugin = new A2APlugin({ agentCard });
A2A message handler with routing
import { App } from '@microsoft/teams.apps';
import { A2APlugin } from '@microsoft/teams.a2a';
import { ChatPrompt } from '@microsoft/teams.ai';
import { OpenAIChatModel } from '@microsoft/teams.openai';

const model = new OpenAIChatModel({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o',
});

const prompt = new ChatPrompt({
  model,
  instructions: `You are an IT help desk agent. You can:
- Reset passwords (ask for the user email)
- Create support tickets (ask for priority and description)
- Check ticket status (ask for ticket ID)
Be concise and helpful.`,
})
  .function('resetPassword', 'Reset a user password', {
    type: 'object',
    properties: {
      email: { type: 'string', description: 'User email address' },
    },
    required: ['email'],
  }, async ({ email }: { email: string }) => {
    return { success: true, message: `Password reset initiated for ${email}` };
  })
  .function('createTicket', 'Create a support ticket', {
    type: 'object',
    properties: {
      priority: { type: 'string', description: 'high, medium, or low' },
      description: { type: 'string', description: 'Issue description' },
    },
    required: ['priority', 'description'],
  }, async ({ priority, description }: { priority: string; description: string }) => {
    const ticketId = `IT-${Date.now()}`;
    return { ticketId, priority, description, status: 'open' };
  });

const agentCard = {
  name: 'IT Help Desk Agent',
  description: 'Handles IT support requests',
  url: 'http://localhost:3978/a2a',
  version: '1.0.0',
  protocolVersion: '0.3.0',
  capabilities: {},
  skills: [
    {
      id: 'it_support',
      name: 'IT Support',
      description: 'Password resets, ticket creation, and status checks',
      tags: ['it', 'support'],
      examples: ['Reset my password', 'Create a ticket for VPN issues'],
    },
  ],
};

const app = new App({
  plugins: [new A2APlugin({ agentCard })],
});

app.event('a2a:message', async ({ respond, requestContext }) => {
  const textInput = requestContext.userMessage.parts
    .filter((p: any) => p.kind === 'text')
    .at(0)?.text;

  if (!textInput) {
    await respond('Please send a text message describing your IT issue.');
    return;
  }

  const result = await prompt.send(textInput);
  await respond(result.content || 'I was unable to process your request.');
});

app.start(3978);

pitfalls

  • Missing required AgentCard fields: Omitting name, url, version, or protocolVersion causes client agents to reject the agent card during discovery. Include all required fields.

  • URL mismatch in AgentCard: The url field must match the actual A2A endpoint URL. If your bot runs on port 3978, the URL is http://localhost:3978/a2a. A mismatch causes clients to connect to the wrong endpoint.

  • Not handling non-text message parts: A2A messages can contain parts of different kinds (text, file, data). Always filter for the expected kind and handle unexpected types gracefully.

  • Forgetting to add A2APlugin to App plugins: Creating the plugin without adding it to new App({ plugins: [...] }) means the A2A endpoints are never registered.

  • Vague skill descriptions: Skills with descriptions like "general helper" provide no guidance to orchestrator agents. Be specific about what the agent can do and include example queries.

  • No error handling in message handler: If prompt.send() throws (e.g., model error), the A2A client receives no response. Wrap processing in try/catch and use respond() to send error messages.

  • Missing protocolVersion: Without this field, client agents cannot verify protocol compatibility. Always set it to the current version ('0.3.0').

references

instructions

This expert covers exposing a Teams bot as an A2A (Agent-to-Agent) server using A2APlugin from @microsoft/teams.a2a in TypeScript. Use it when you need to:

  • Define an AgentCard with name, description, URL, version, capabilities, and skills

  • Create an A2APlugin and add it to the App's plugins array

  • Handle incoming A2A messages via app.event('a2a:message', handler)

  • Extract text from requestContext.userMessage.parts

  • Send responses using the respond() helper

  • Understand the A2A endpoint URL (/a2a) and agent card URL (/a2a/.well-known/agent-card.json)

Pair with a2a.client-basics-ts.md for calling other A2A agents and a2a.orchestrator-patterns-ts.md for multi-agent coordination. Pair with runtime.app-init-ts.md for adding A2APlugin to the App, and ai.chatprompt-basics-ts.md for processing A2A messages with AI.

research

Deep Research prompt:

"Write a micro expert on implementing an A2A server in a Teams bot using @microsoft/teams.a2a (TypeScript). Cover AgentCard structure (name, description, url, version, protocolVersion, capabilities, skills), A2APlugin constructor, handling a2a:message events, extracting text from requestContext.userMessage.parts, respond() helper, endpoint URLs, and common pitfalls. Include 2-3 canonical TypeScript code examples."

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Python, Needs Node.js

Security

What our scanner noticed· Medium risk

  • Possible data-exfiltration endpoints
  • Instructions that use the network
  • Downloads piped into a shell

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Microsoft
Publisher
Microsoft (Official)
Source
microsoft/skills · .github/plugins/microsoft-365-agents-toolkit/skills/teams-app-developer · commit 0696600
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download teams-app-developer.zip