Teams App Developer
MicrosoftOfficialPublished by Microsoft
- Skill
- Tool integration
- Software development
- MIT
- Medium risk
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
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/teams-app-developer/downloadUnzip 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
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, andatk auth list. Common pitfalls:AADSTS7000229→aadApp/createmissinggenerateServicePrincipal: truein YAML — add it and re-provisionMissing
TENANT_IDin.localConfigs→ SDK uses wrong token authority → 401 from Bot Connector401 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 deploycan take several minutesAlways 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 indefinitelyALWAYS run as a background process (
isBackground=true) — NEVER useisBackground=falsefor these commandsDo 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
atkCLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:export ATK_CLI_SKILL=trueRun this once at the start of the session. All subsequent
atkcommands in the same terminal will inherit it.
ATK CLI Setup
atk --version # Must be > 1.1.5-betaIf ATK is not found or version is too old:
npm i -g @microsoft/m365agentstoolkit-cli@betaCLI 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.
Files
- ATTRIBUTION.mdAdded by AutoGineer906 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md7.6 KiB
- create-project/create-project.md8.1 KiB
- docs/README.md2.8 KiB
- docs/advanced-features.md7.0 KiB
- docs/feature-gaps.md46.3 KiB
- docs/files-and-links.md4.2 KiB
- docs/identity-and-auth.md4.3 KiB
- docs/infrastructure.md6.7 KiB
- docs/interactive-responses.md4.4 KiB
- docs/messaging-and-commands.md4.5 KiB
- docs/middleware-and-handlers.md4.4 KiB
- docs/ui-components.md6.9 KiB
- docs/workflows.md14.4 KiB
- experts/README.md8.6 KiB
- experts/_expert-ts.md2.2 KiB
- experts/analyzer.md14.0 KiB
- experts/bridge/app-distribution-packaging-ts.md14.2 KiB
- experts/bridge/channel-ops-graph-ts.md15.4 KiB
- experts/bridge/commands-slash-text-ts.md18.5 KiB
- experts/bridge/cross-platform-advisor-ts.md36.4 KiB
- experts/bridge/cross-platform-architecture-ts.md8.3 KiB
- experts/bridge/events-activities-ts.md22.4 KiB
- experts/bridge/files-upload-download-ts.md17.2 KiB
- experts/bridge/identity-oauth-bridge-ts.md19.8 KiB
- experts/bridge/index.md13.0 KiB
- experts/bridge/infra-compute-ts.md14.6 KiB
- experts/bridge/infra-observability-ts.md14.0 KiB
- experts/bridge/infra-secrets-config-ts.md13.2 KiB
- experts/bridge/infra-storage-ts.md14.3 KiB
- experts/bridge/interactive-responses-ts.md19.6 KiB
- experts/bridge/link-unfurl-preview-ts.md17.1 KiB
- experts/bridge/middleware-handlers-ts.md15.4 KiB
- experts/bridge/python-cross-platform.md9.3 KiB
- experts/bridge/rate-limiting-resilience-ts.md17.6 KiB
- experts/bridge/rest-only-integration-ts.md8.4 KiB
- experts/bridge/scheduling-deferred-send-ts.md17.8 KiB
- experts/bridge/shortcuts-extensions-ts.md17.5 KiB
- experts/bridge/transport-socketmode-https-ts.md14.3 KiB
- experts/bridge/ui-app-home-personal-tab-ts.md14.5 KiB
- experts/bridge/ui-block-kit-adaptive-cards-ts.md21.5 KiB
- experts/bridge/ui-legacy-attachments-cards-ts.md11.2 KiB
- experts/bridge/ui-modals-dialogs-ts.md21.4 KiB
- experts/bridge/workflow.composable-platform-ts.md13.7 KiB
- experts/bridge/workflows-automation-ts.md14.3 KiB
- experts/builder.md11.1 KiB
- experts/convert/bulk-conversion-strategy-ts.md12.8 KiB
- experts/convert/dependency-mapping-ts.md8.3 KiB
- experts/convert/index.md3.5 KiB
- experts/convert/java-to-ts-ts.md20.6 KiB
- experts/convert/js-to-ts-ts.md6.2 KiB
- experts/convert/json-serialization-ts.md11.0 KiB
- experts/convert/kotlin-to-ts-ts.md11.2 KiB
- experts/convert/ruby-to-ts-ts.md9.7 KiB
- experts/convert/type-mapping-ts.md10.1 KiB
- experts/deploy/aws-bot-deploy-ts.md14.6 KiB
- experts/deploy/aws-cli-reference-ts.md52.4 KiB
- experts/deploy/azure-bot-deploy-ts.md15.4 KiB
- experts/deploy/azure-cli-reference-ts.md16.9 KiB
- experts/deploy/index.md4.6 KiB
- experts/fallback.md2.1 KiB
- experts/index.md18.9 KiB
- experts/models/anthropic-ts.md7.8 KiB
- experts/models/bedrock-ts.md9.9 KiB
- experts/models/foundry-cloud-ts.md8.1 KiB
- experts/models/foundry-local-ts.md10.6 KiB
- experts/models/index.md5.8 KiB
- experts/models/openai-azure-openai-ts.md8.3 KiB
- experts/models/oss-openai-compatible-ts.md10.7 KiB
- experts/models/transformers-js-ts.md11.6 KiB
- experts/prompt-engineer.md14.7 KiB
- experts/researcher.md2.8 KiB
- experts/security/index.md1.2 KiB
- experts/security/input-validation-ts.md13.8 KiB
- experts/security/secrets-ts.md13.9 KiB
- experts/slack/bolt-assistant-ts.md9.9 KiB
- experts/slack/bolt-events-ts.md9.3 KiB
- experts/slack/bolt-java.md8.9 KiB
- experts/slack/bolt-oauth-distribution-ts.md10.9 KiB
- experts/slack/bolt-python.md9.5 KiB
- experts/slack/cli.app-management.md7.9 KiB
- experts/slack/cli.datastore-env.md8.6 KiB
- experts/slack/cli.getting-started.md8.0 KiB
- experts/slack/cli.local-dev-deploy.md8.4 KiB
- experts/slack/cli.manifest-triggers.md9.9 KiB
- experts/slack/index.md8.9 KiB
- experts/slack/runtime.ack-rules-ts.md9.8 KiB
- experts/slack/runtime.bolt-foundations-ts.md10.7 KiB
- experts/slack/runtime.shortcuts-ts.md11.0 KiB
- experts/slack/runtime.slash-commands-ts.md11.6 KiB
- experts/slack/runtime.socket-mode-ts.md9.5 KiB
- experts/slack/ui.block-kit-ts.md11.5 KiB
- experts/slack/ui.modals-lifecycle-ts.md13.3 KiB
- experts/slack/web-api-proactive-ts.md11.0 KiB
- experts/slack/workflow.slack-automations-ts.md10.2 KiB
- experts/teams/a2a.client-basics-ts.md9.7 KiB
- experts/teams/a2a.orchestrator-patterns-ts.md12.7 KiB
- experts/teams/a2a.server-basics-ts.md11.4 KiB
- experts/teams/ai.chatprompt-basics-ts.md8.1 KiB
- experts/teams/ai.citations-feedback-ts.md6.9 KiB
- experts/teams/ai.conversational-query-ts.md14.2 KiB
- experts/teams/ai.function-calling-design-ts.md9.0 KiB
- experts/teams/ai.function-calling-implementation-ts.md7.7 KiB
- experts/teams/ai.memory-localmemory-ts.md7.3 KiB
- experts/teams/ai.model-setup-ts.md6.6 KiB
- experts/teams/ai.rag-retrieval-ts.md7.4 KiB
- experts/teams/ai.rag-vectorstores-ts.md8.5 KiB
- experts/teams/ai.streaming-ts.md6.9 KiB
- experts/teams/auth.oauth-sso-ts.md10.1 KiB
- experts/teams/compat.botbuilder-interop-ts.md14.6 KiB
- experts/teams/dev.debug-test-ts.md14.1 KiB
- experts/teams/graph.usergraph-appgraph-ts.md9.0 KiB
- experts/teams/index.md9.8 KiB
- experts/teams/mcp.client-basics-ts.md9.5 KiB
- experts/teams/mcp.expose-chatprompt-tools-ts.md9.5 KiB
- experts/teams/mcp.security-ts.md10.4 KiB
- experts/teams/mcp.server-basics-ts.md9.9 KiB
- experts/teams/project.scaffold-files-ts.md12.2 KiB
- experts/teams/runtime.app-init-ts.md10.9 KiB
- experts/teams/runtime.manifest-ts.md12.3 KiB
- experts/teams/runtime.proactive-messaging-ts.md12.6 KiB
- experts/teams/runtime.routing-handlers-ts.md12.3 KiB
- experts/teams/state.storage-patterns-ts.md9.4 KiB
- experts/teams/teams-dotnet.md8.2 KiB
- experts/teams/teams-python.md8.3 KiB
- experts/teams/ui.adaptive-cards-ts.md12.9 KiB
- experts/teams/ui.dialogs-task-modules-ts.md15.1 KiB
- experts/teams/ui.message-extensions-ts.md15.6 KiB
- experts/teams/workflow.approvals-inline-ts.md12.4 KiB
- experts/teams/workflow.message-native-records-ts.md10.6 KiB
- experts/teams/workflow.sharepoint-lists-ts.md9.0 KiB
- experts/teams/workflow.state-driven-events-ts.md12.2 KiB
- experts/teams/workflow.triggers-compose-ts.md10.3 KiB
- experts/update-experts.md10.0 KiB
- provision-deploy/provision-deploy.md4.3 KiB
- test-playground/playground-cli.md4.6 KiB
- test-playground/playground.md4.5 KiB
- test-playground/test-playground.md1.1 KiB
- test-teams/test-teams.md4.9 KiB
- toolkit/README.md4.2 KiB
- toolkit/commands.md2.6 KiB
- toolkit/environments.md12.6 KiB
- toolkit/lifecycle-cli.md17.6 KiB
- toolkit/manifest-and-yaml.md6.0 KiB
- toolkit/playground.md7.6 KiB
- toolkit/publish.md9.3 KiB
- toolkit/templates.md6.7 KiB
- troubleshoot/troubleshoot.md20.2 KiB
experts/teams/ui.message-extensions-ts.md
ui.message-extensions-ts
purpose
Search-based and action-based message extensions (compose extensions) for Teams bots using the Teams AI Library v2.
rules
Configure message extensions in
appPackage/manifest.jsonunder thecomposeExtensionsarray. Each extension has abotId,commandsarray, and each command specifiestype(queryfor search,actionfor task module). learn.microsoft.com -- Message extensionsHandle search queries with
app.on('message.ext.query', handler). The handler receives the query text inactivity.value.parameters[0].valueand must return a response withcomposeExtension.type: 'result'containing an attachments array. learn.microsoft.com -- Search extensionsSet
attachmentLayoutto'list'for vertical result layout or'grid'for a tile grid. Use'list'for text-heavy results and'grid'for image-heavy results. learn.microsoft.com -- Respond to searchEach attachment in the results array needs both a
content(the full Adaptive Card inserted into the compose box) and apreview(a smaller Thumbnail Card shown in the search results list). The preview usescontentType: 'application/vnd.microsoft.card.thumbnail'. learn.microsoft.com -- Respond to searchHandle action-based extensions with two routes:
app.on('message.ext.open', handler)for displaying the task module form (composeExtension/fetchTask) andapp.on('message.ext.submit', handler)for processing the submitted data (composeExtension/submitAction). learn.microsoft.com -- Action extensionsThe
message.ext.openhandler returns a task module response identical todialog.open:{ status: 200, body: { task: { type: 'continue', value: { title, card } } } }. learn.microsoft.com -- Action extensionsThe
message.ext.submithandler receives form data inactivity.value.dataand can return a card to insert into the compose box or perform a server-side action. learn.microsoft.com -- Action extensionsManifest command parameters define the search fields displayed in the Teams UI. Each parameter has
name,title, and optionallydescriptionandinputType. The first parameter is the default search field. learn.microsoft.com -- Define search commandSearch result counts should be limited (10-15 items) because Teams truncates long result lists. Always handle empty query strings gracefully by returning popular or recent results. learn.microsoft.com -- Search extensions
Handle link unfurling with
app.on('message.ext.query-link', handler). This fires when a user pastes a URL matching a domain in the manifest'smessageHandlers. Return a card attachment to preview the link. learn.microsoft.com -- Link unfurling
patterns
Search-based message extension
import { App } from '@microsoft/teams.apps';
import { ConsoleLogger } from '@microsoft/teams.common';
import { DevtoolsPlugin } from '@microsoft/teams.dev';
// Manifest excerpt (appPackage/manifest.json):
// {
// "composeExtensions": [{
// "botId": "${{BOT_ID}}",
// "commands": [{
// "id": "searchCmd",
// "type": "query",
// "title": "Search Products",
// "parameters": [{ "name": "query", "title": "Search query" }]
// }]
// }]
// }
interface Product {
id: string;
title: string;
description: string;
price: number;
imageUrl: string;
}
async function searchProducts(query: string): Promise<Product[]> {
// Replace with your actual search logic
const products: Product[] = [
{ id: '1', title: 'Widget Pro', description: 'A premium widget', price: 29.99, imageUrl: 'https://example.com/widget.png' },
{ id: '2', title: 'Gadget Plus', description: 'An advanced gadget', price: 49.99, imageUrl: 'https://example.com/gadget.png' },
];
return products.filter(p =>
p.title.toLowerCase().includes(query.toLowerCase())
);
}
const app = new App({
logger: new ConsoleLogger('ext-bot'),
plugins: [new DevtoolsPlugin()],
});
app.on('message.ext.query', async ({ activity }) => {
const query = activity.value.parameters?.[0]?.value || '';
const results = await searchProducts(query);
return {
status: 200,
body: {
composeExtension: {
type: 'result',
attachmentLayout: 'list',
attachments: results.map(item => ({
// Full card inserted into compose box when selected
contentType: 'application/vnd.microsoft.card.adaptive',
content: {
type: 'AdaptiveCard',
version: '1.5',
body: [
{ type: 'TextBlock', text: item.title, weight: 'Bolder', size: 'Large' },
{ type: 'TextBlock', text: item.description, wrap: true },
{ type: 'TextBlock', text: `Price: $${item.price}`, weight: 'Bolder' },
],
},
// Preview card shown in search results list
preview: {
contentType: 'application/vnd.microsoft.card.thumbnail',
content: {
title: item.title,
text: `$${item.price} - ${item.description}`,
images: [{ url: item.imageUrl }],
},
},
})),
},
},
};
});
app.start(3978);Action-based message extension with task module
import { App } from '@microsoft/teams.apps';
import { ConsoleLogger } from '@microsoft/teams.common';
import { DevtoolsPlugin } from '@microsoft/teams.dev';
// Manifest excerpt (appPackage/manifest.json):
// {
// "composeExtensions": [{
// "botId": "${{BOT_ID}}",
// "commands": [{
// "id": "createItem",
// "type": "action",
// "title": "Create Item",
// "fetchTask": true
// }]
// }]
// }
const app = new App({
logger: new ConsoleLogger('action-ext-bot'),
plugins: [new DevtoolsPlugin()],
});
// Open a task module form when the action is triggered
app.on('message.ext.open', async () => {
return {
status: 200,
body: {
task: {
type: 'continue',
value: {
title: 'Create New Item',
width: 'medium',
height: 'medium',
card: {
contentType: 'application/vnd.microsoft.card.adaptive',
content: {
type: 'AdaptiveCard',
version: '1.5',
body: [
{
type: 'TextBlock',
text: 'Create a new item',
weight: 'Bolder',
size: 'Large',
},
{
type: 'Input.Text',
id: 'title',
label: 'Title',
isRequired: true,
errorMessage: 'Title is required',
},
{
type: 'Input.Text',
id: 'description',
label: 'Description',
isMultiline: true,
},
{
type: 'Input.ChoiceSet',
id: 'priority',
label: 'Priority',
value: 'medium',
choices: [
{ title: 'Low', value: 'low' },
{ title: 'Medium', value: 'medium' },
{ title: 'High', value: 'high' },
],
},
],
actions: [
{ type: 'Action.Submit', title: 'Create' },
],
},
},
},
},
},
};
});
// Process the submitted form data
app.on('message.ext.submit', async ({ activity, send }) => {
const data = activity.value.data;
const { title, description, priority } = data;
// Create the item in your backend
const itemId = `ITEM-${Date.now()}`;
await send(`Created item "${title}" (${priority} priority) - ID: ${itemId}`);
});
app.start(3978);Combined search and action extensions
import { App } from '@microsoft/teams.apps';
// Manifest excerpt (appPackage/manifest.json):
// {
// "composeExtensions": [{
// "botId": "${{BOT_ID}}",
// "commands": [
// {
// "id": "searchItems",
// "type": "query",
// "title": "Search Items",
// "parameters": [{ "name": "query", "title": "Search" }]
// },
// {
// "id": "createItem",
// "type": "action",
// "title": "Create Item",
// "fetchTask": true
// }
// ]
// }]
// }
const app = new App();
// Search extension handler
app.on('message.ext.query', async ({ activity }) => {
const query = activity.value.parameters?.[0]?.value || '';
const commandId = activity.value.commandId;
// You can route by commandId if multiple search commands exist
const items = [
{ id: '1', title: 'Task Alpha', status: 'open' },
{ id: '2', title: 'Task Beta', status: 'closed' },
].filter(i => i.title.toLowerCase().includes(query.toLowerCase()));
return {
status: 200,
body: {
composeExtension: {
type: 'result',
attachmentLayout: 'list',
attachments: items.map(item => ({
contentType: 'application/vnd.microsoft.card.adaptive',
content: {
type: 'AdaptiveCard',
version: '1.5',
body: [
{ type: 'TextBlock', text: item.title, weight: 'Bolder' },
{ type: 'TextBlock', text: `Status: ${item.status}` },
],
},
preview: {
contentType: 'application/vnd.microsoft.card.thumbnail',
content: {
title: item.title,
text: `Status: ${item.status}`,
},
},
})),
},
},
};
});
// Action extension: open form
app.on('message.ext.open', async () => {
return {
status: 200,
body: {
task: {
type: 'continue',
value: {
title: 'Create Item',
card: {
contentType: 'application/vnd.microsoft.card.adaptive',
content: {
type: 'AdaptiveCard',
version: '1.5',
body: [
{ type: 'Input.Text', id: 'title', label: 'Title', isRequired: true },
{ type: 'Input.Text', id: 'notes', label: 'Notes', isMultiline: true },
],
actions: [
{ type: 'Action.Submit', title: 'Create' },
],
},
},
},
},
},
};
});
// Action extension: process submission
app.on('message.ext.submit', async ({ activity, send }) => {
const { title, notes } = activity.value.data;
await send(`Created: ${title}${notes ? ` - ${notes}` : ''}`);
});
app.start(3978);pitfalls
Missing manifest
composeExtensions: Message extensions require thecomposeExtensionsarray in the manifest. Without it, the extension does not appear in the Teams compose box. Update the manifest and re-sideload after changes.Empty query handling: Users often open the search extension without typing. Handle empty or blank
querystrings by returning popular/recent results instead of an empty list.Missing preview card: Each search result attachment must include a
previewwithcontentType: 'application/vnd.microsoft.card.thumbnail'. Without it, the result appears blank in the search results list.Wrong route handler: Search uses
message.ext.query(notmessage.ext.open). Action usesmessage.ext.open+message.ext.submit. Mixing them up results in handlers never firing.Too many results: Teams limits the number of displayed results. Return 10-15 items maximum. Longer lists are silently truncated.
Attachment layout mismatch: Using
'grid'layout requires images in the preview. Using'grid'with text-only thumbnails produces a poor visual experience. Match layout to content type.Not setting
fetchTask: truefor action commands: In the manifest, action commands must have"fetchTask": truefor themessage.ext.openhandler to fire. Without it, Teams does not invoke the task module.Preview vs content confusion: The
previewis what users see in the results dropdown. Thecontentis what gets inserted when they select it. A missing or incorrectcontentcard means the wrong card (or nothing) is inserted.
references
instructions
This expert covers search-based and action-based message extensions (compose extensions) in Microsoft Teams bots built with the Teams AI Library v2 (@microsoft/teams.ts) in TypeScript. Use it when you need to:
Configure
composeExtensionsin the manifest with search (query) or action commandsHandle search queries with
app.on('message.ext.query', ...)and return result attachments with previewsHandle action extensions with
app.on('message.ext.open', ...)for task modules andapp.on('message.ext.submit', ...)for processingBuild thumbnail preview cards for search results
Choose between
'list'and'grid'attachment layoutsCombine search and action commands in a single extension
Pair with ui.adaptive-cards-ts.md for card construction and ui.dialogs-task-modules-ts.md for task module patterns used in action extensions. Pair with runtime.manifest-ts.md for composeExtensions manifest configuration, and ui.adaptive-cards-ts.md for building card attachments returned by extensions.
research
Deep Research prompt:
"Write a micro expert on Message Extensions in Teams (TypeScript). Cover manifest composeExtensions configuration, search-based query flow (message.ext.query handler, parameters, result attachments with preview), action-based flow (message.ext.open for task module, message.ext.submit for processing), attachment layouts (list/grid), thumbnail preview cards, link unfurling, 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