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/bridge/shortcuts-extensions-ts.md
shortcuts-extensions-ts
purpose
Bridges Slack shortcuts (global and message) and Teams message extensions / compose extensions for cross-platform bots targeting Slack, Teams, or both.
rules
Slack global shortcuts → Teams action-based compose extensions with
context: ['compose', 'commandBox']. Slack global shortcuts appear in the lightning bolt menu and don't reference a specific message. In Teams, the equivalent is a compose extension withfetchTask: trueand action context targeting the compose box and command bar. learn.microsoft.com -- Action-based extensionsSlack message shortcuts → Teams action-based extensions with
context: ['message']. Slack message shortcuts appear in the message context menu (⋮ → More actions). In Teams, action-based extensions withcontext: ['message']appear in the message overflow menu (... → More actions). The target message content is available in the invoke payload. learn.microsoft.com -- Message contextSlack
trigger_id+views.open()→ TeamsfetchTask: true+ task module. Slack shortcuts use thetrigger_idto open a modal. Teams action-based extensions usefetchTask: truein the manifest, which causes Teams to invoke the bot'smessage.ext.openhandler to fetch the task module (dialog) content. No trigger_id needed. learn.microsoft.com -- Task module from extensionSlack
shortcut.message(target message in message shortcuts) → Teamsactivity.value.messagePayload. When a message shortcut is invoked in Slack, the message object is inshortcut.message. In Teams, the message that was acted upon is inactivity.value.messagePayloadwithid,body.content,from,createdDateTime, andattachments. learn.microsoft.com -- Message payloadManifest
composeExtensions[].commands[]withtype: "action"is required. Unlike Slack where shortcuts are configured in the app dashboard, Teams requires each action command to be declared in the manifest JSON with its title, description, parameters, and context array. Without this, the extension never appears. learn.microsoft.com -- Manifest schemaSlack
app.shortcut('callback_id')→ Teams handler routing viaactivity.value.commandId. Slack routes shortcuts bycallback_id. Teams invokes the samemessage.ext.openhandler for all action commands — differentiate by checkingactivity.value.commandIdagainst the commandidin the manifest. learn.microsoft.com -- Handle actionTask module response replaces Slack modal view return. Slack's
views.open()returns a view object with blocks. Teams'message.ext.openhandler returns a task module response containing either an Adaptive Card or an iframe URL. The Adaptive Card path is closest to Slack's modal behavior. learn.microsoft.com -- Task modulesSlack
view_submission→ Teamsmessage.ext.submit. When the user submits the task module form, Teams invokes themessage.ext.submithandler (orcomposeExtension/submitActionactivity). The form data is inactivity.value.data. The handler can return a card to insert into the compose box, send a message, or show another task module. learn.microsoft.com -- Handle submitNo "fire and forget" shortcuts in Teams. Slack global shortcuts can trigger background actions without showing a modal (just
ack()+ do work). Teams action-based extensions always show a task module iffetchTask: true. To mimic fire-and-forget, return a minimal confirmation card from the task module and process in the background. learn.microsoft.com -- Action commandsTeams action extensions can insert cards into the compose box. Slack shortcuts post messages via
say()orrespond(). Teams action extensions can return a card that gets inserted into the user's compose box for them to review and send. This is a UX improvement — the user controls when the message is posted. Return{ composeExtension: { type: 'result', attachments: [...] } }from the submit handler. learn.microsoft.com -- Respond to submitReverse direction (Teams → Slack): For Teams → Slack, map compose extensions to
app.shortcutwithglobal_shortcutormessage_shortcuttype. Action-based extensions withcontext: ['compose', 'commandBox']map to Slack global shortcuts; extensions withcontext: ['message']map to Slack message shortcuts. Task module forms become Slack modals opened viaviews.open()with atrigger_id. Themessage.ext.submithandler maps to a Slackview_submissionhandler.
patterns
Message shortcut → action-based message extension
Slack (before):
import { App } from "@slack/bolt";
const app = new App({
token: process.env.SLACK_BOT_TOKEN!,
signingSecret: process.env.SLACK_SIGNING_SECRET!,
});
// Message shortcut — appears in message context menu
app.shortcut("create_ticket_from_message", async ({ ack, shortcut, client }) => {
await ack();
const message = (shortcut as any).message;
await client.views.open({
trigger_id: shortcut.trigger_id,
view: {
type: "modal",
callback_id: "ticket_from_message",
title: { type: "plain_text", text: "Create Ticket" },
submit: { type: "plain_text", text: "Create" },
blocks: [
{
type: "input",
block_id: "title_block",
label: { type: "plain_text", text: "Ticket Title" },
element: {
type: "plain_text_input",
action_id: "title_input",
initial_value: message.text?.substring(0, 100) ?? "",
},
},
{
type: "input",
block_id: "priority_block",
label: { type: "plain_text", text: "Priority" },
element: {
type: "static_select",
action_id: "priority_select",
options: [
{ text: { type: "plain_text", text: "High" }, value: "high" },
{ text: { type: "plain_text", text: "Medium" }, value: "medium" },
{ text: { type: "plain_text", text: "Low" }, value: "low" },
],
},
},
],
private_metadata: JSON.stringify({
channel: message.channel,
messageTs: message.ts,
}),
},
});
});
app.view("ticket_from_message", async ({ ack, view, client }) => {
await ack();
const title = view.state.values.title_block.title_input.value!;
const priority = view.state.values.priority_block.priority_select.selected_option?.value;
const meta = JSON.parse(view.private_metadata);
await client.chat.postMessage({
channel: meta.channel,
text: `Ticket created: *${title}* [${priority}]`,
thread_ts: meta.messageTs,
});
});Teams (after):
import { App } from "@microsoft/teams.apps";
import { ConsoleLogger } from "@microsoft/teams.common";
const app = new App({
logger: new ConsoleLogger("my-bot", { level: "info" }),
});
// message.ext.open — returns task module (replaces views.open with trigger_id)
app.on("message.ext.open" as any, async ({ activity }) => {
const commandId = activity.value?.commandId;
if (commandId === "createTicketFromMessage") {
// Target message content (replaces shortcut.message)
const messagePayload = activity.value?.messagePayload;
const messageText = messagePayload?.body?.content ?? "";
return {
status: 200,
body: {
task: {
type: "continue",
value: {
title: "Create Ticket",
card: {
contentType: "application/vnd.microsoft.card.adaptive",
content: {
type: "AdaptiveCard",
version: "1.5",
body: [
{
type: "Input.Text",
id: "ticketTitle",
label: "Ticket Title",
value: messageText.substring(0, 100),
isRequired: true,
},
{
type: "Input.ChoiceSet",
id: "priority",
label: "Priority",
value: "medium",
choices: [
{ title: "High", value: "high" },
{ title: "Medium", value: "medium" },
{ title: "Low", value: "low" },
],
},
],
actions: [{
type: "Action.Submit",
title: "Create",
}],
},
},
},
},
},
};
}
});
// message.ext.submit — handle form submission (replaces app.view handler)
app.on("message.ext.submit" as any, async ({ activity, send }) => {
const data = activity.value?.data;
if (data) {
const title = data.ticketTitle;
const priority = data.priority;
// Send confirmation to the conversation
await send(`Ticket created: **${title}** [${priority}]`);
}
return { status: 200, body: {} };
});
app.start(3978);Manifest for the message action extension:
{
"composeExtensions": [
{
"botId": "${{BOT_ID}}",
"commands": [
{
"id": "createTicketFromMessage",
"type": "action",
"title": "Create Ticket",
"description": "Create a ticket from this message",
"context": ["message"],
"fetchTask": true
}
]
}
]
}Global shortcut → compose extension
Slack (before):
import { App } from "@slack/bolt";
const app = new App({
token: process.env.SLACK_BOT_TOKEN!,
signingSecret: process.env.SLACK_SIGNING_SECRET!,
});
// Global shortcut — appears in the ⚡ menu
app.shortcut("quick_note", async ({ ack, shortcut, client }) => {
await ack();
await client.views.open({
trigger_id: shortcut.trigger_id,
view: {
type: "modal",
callback_id: "quick_note_modal",
title: { type: "plain_text", text: "Quick Note" },
submit: { type: "plain_text", text: "Save" },
blocks: [
{
type: "input",
block_id: "note_block",
label: { type: "plain_text", text: "Note" },
element: {
type: "plain_text_input",
action_id: "note_input",
multiline: true,
},
},
],
},
});
});
app.view("quick_note_modal", async ({ ack, view }) => {
const note = view.state.values.note_block.note_input.value!;
await ack();
await saveNote(note);
});Teams (after):
import { App } from "@microsoft/teams.apps";
import { ConsoleLogger } from "@microsoft/teams.common";
const app = new App({
logger: new ConsoleLogger("my-bot", { level: "info" }),
});
app.on("message.ext.open" as any, async ({ activity }) => {
if (activity.value?.commandId === "quickNote") {
return {
status: 200,
body: {
task: {
type: "continue",
value: {
title: "Quick Note",
card: {
contentType: "application/vnd.microsoft.card.adaptive",
content: {
type: "AdaptiveCard",
version: "1.5",
body: [{
type: "Input.Text",
id: "noteText",
label: "Note",
isMultiline: true,
isRequired: true,
}],
actions: [{ type: "Action.Submit", title: "Save" }],
},
},
},
},
},
};
}
});
app.on("message.ext.submit" as any, async ({ activity }) => {
const note = activity.value?.data?.noteText;
if (note) {
await saveNote(note);
}
// Return empty to close the task module
return { status: 200, body: {} };
});
async function saveNote(note: string) { /* persist note */ }
app.start(3978);Manifest for compose/commandBox action:
{
"composeExtensions": [
{
"botId": "${{BOT_ID}}",
"commands": [
{
"id": "quickNote",
"type": "action",
"title": "Quick Note",
"description": "Save a quick note",
"context": ["compose", "commandBox"],
"fetchTask": true
}
]
}
]
}Shortcut mapping table
| Slack Pattern | Teams Equivalent | Notes |
|---|---|---|
app.shortcut('callback_id') (global) | message.ext.open + commandId check | Compose extension action |
app.shortcut('callback_id') (message) | message.ext.open + commandId check | context: ['message'] in manifest |
shortcut.trigger_id + views.open() | fetchTask: true → return task module | No trigger_id needed |
shortcut.message | activity.value.messagePayload | Target message content |
callback_id routing | activity.value.commandId routing | Different field name |
view_submission handler | message.ext.submit handler | Form data in activity.value.data |
ack() + background work | Return minimal card + async work | No fire-and-forget |
say() / respond() after shortcut | send() or return compose card | Can insert into compose box |
pitfalls
Missing
composeExtensionscommands in manifest: Each shortcut must have a corresponding command entry in the manifest withtype: "action". Without it, the action never appears in Teams' UI.Forgetting
fetchTask: true: Without this flag, Teams won't invoke themessage.ext.openhandler. Instead, it expects parameters defined in the manifest and skips the task module entirely.contextarray determines placement: Omitting thecontextarray or using wrong values means the action appears in unexpected places or not at all. Use['message']for message shortcuts,['compose', 'commandBox']for global shortcuts.messagePayloadHTML content: The target message body inactivity.value.messagePayload.body.contentmay be HTML-formatted (not plain text). Parse or strip HTML before using as form default values.No background-only shortcuts: Slack allows shortcuts that just
ack()and do work silently. Teams action extensions always present a task module. Wrap background actions in a minimal "Processing..." → "Done" card flow.Submit handler must return within 3 seconds: Like all invoke activities, the
message.ext.submithandler must respond quickly. Long-running operations should return immediately and process asynchronously.
references
https://api.slack.com/interactivity/shortcuts — Slack shortcuts
https://api.slack.com/reference/interaction-payloads/shortcuts — Slack shortcut payloads
instructions
Use this expert when adding cross-platform support in either direction for shortcuts and message/compose extensions. It covers: Slack global shortcuts bridged to Teams compose extensions, Slack message shortcuts bridged to Teams action-based extensions with context: ['message'], trigger_id vs fetchTask: true, target message access via messagePayload, task module form flows bridged to Slack modals, and reverse mapping from Teams extensions to Slack shortcuts. Pair with ../teams/ui.message-extensions-ts.md for general message extension patterns, ../teams/ui.dialogs-task-modules-ts.md for task module details, and ui-modals-dialogs-ts.md for modal-to-dialog conversion.
research
Deep Research prompt:
"Write a micro expert for bridging Slack shortcuts (global shortcuts and message shortcuts) and Microsoft Teams action-based message extensions in either direction. Cover: manifest composeExtensions command config with context arrays, fetchTask: true for task module invocation, trigger_id elimination, message payload access for message shortcuts, view_submission to message.ext.submit, the lack of fire-and-forget shortcuts in Teams, compose box card insertion, and reverse mapping from Teams compose/action extensions back to Slack shortcuts. Include TypeScript code examples and a mapping table."
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