teams-app-patterns

name	teams-app-patterns
description	Full Teams app development patterns.
tier	standard
user-invokable	false
applyTo	**/*teams*,**/*manifest*,**/*m365*

Teams App Patterns Skill

Full Teams app development patterns.

⚠️ Staleness Warning

Teams platform evolves rapidly. Last validated: February 13, 2026 (M365 Agents Toolkit CLI 3.1.0, Manifest v1.19, DA v1.6)

Check: Teams Docs, M365 Agents Toolkit

💡 Use @m365agents chat participant in VS Code Copilot Chat for scaffolding, schema help, and troubleshooting.

---

Available MCP Tools

The @m365agents chat participant exposes MCP tools. Use these programmatically before falling back to manual docs:

Tool	Purpose	Example Use
mcp_m365agentstoo_get_schema	Get current manifest schemas	Validate app manifest (v1.19), DA manifest (v1.0), API plugin (v2.1), M365 agents YAML
mcp_m365agentstoo_get_code_snippets	Working code samples	Teams AI library, Teams JS SDK, botbuilder patterns
mcp_m365agentstoo_get_knowledge	Development knowledge base	Copilot extensibility, capabilities, best practices
mcp_m365agentstoo_troubleshoot	Diagnose issues	Sideloading, conditional access, schema errors

When to use: Any M365/Teams development task — call the relevant MCP tool first, then supplement with skill knowledge.

---

⚠️ Critical: Declarative Agent v1.6 Schema

declarativeAgent.json for M365 Copilot agents has specific schema requirements:

Field	Wrong (Pre-v1.6)	Correct (v1.6)
disclaimer	"text string"	{ "text": "..." }
behavior_overrides.suggestions	false	{ "disabled": false }
behavior_overrides.special_instructions	"text string"	{ "discourage_model_knowledge": false }
user_overrides	{ "capabilities": [...] }	[ { "path": "$.capabilities[?(@.name=='X')]", "allowed_actions": ["remove"] } ]

CLI Version Matters:

• v2.x: --app-package-file flag, may NOT include declarativeAgent.json in zip (bug)
• v3.x: --package-file flag, correctly includes declarativeAgent.json

Upgrade CLI if packaging fails:

npm install -g @microsoft/teamsapp-cli@latest
teamsapp --version  # Should be 3.x

---

App Package

appPackage/
├── manifest.json        # Teams app manifest (schema v1.19+)
├── outline.png          # 32x32, transparent bg, white only
├── color.png            # 192x192, no transparency
└── declarativeAgent.json # Required for M365 Copilot agents (DA v1.6)

Icon Requirements (CRITICAL)

Icon	Size	Background	Content
color.png	192×192	Any	Full color logo
outline.png	32×32	Transparent (Alpha=0)	White only (255,255,255)

❌ Common failures: Wrong dimensions, outline has gray background, outline uses colors

Icon Generation from SVG (Brand Consistency)

When syncing icons from VS Code assets to M365:

# Install sharp if needed
npm install sharp

# Generate color.png (192x192) from logo.svg
node -e "const sharp = require('sharp'); sharp('vscode-extension/assets/logo.svg').resize(192, 192).png().toFile('appPackage/color.png')"

# Generate outline.png (32x32) from monochrome SVG
node -e "const sharp = require('sharp'); sharp('vscode-extension/assets/logo-mono.svg').resize(32, 32).png().toFile('appPackage/outline.png')"

Source of truth: assets/logo.svg and logo-mono.svg

---

Manifest Required Fields

• $schema, manifestVersion, version, id
• name.short, name.full
• description.short, description.full
• icons.outline, icons.color
• developer.*, validDomains

Bot Handler

class MyBot extends TeamsActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => { ... });
    }
}

Adaptive Card Structure

{ "type": "AdaptiveCard", "version": "1.5", "body": [...], "actions": [...] }

Teams SDK

await microsoftTeams.app.initialize();
const context = await microsoftTeams.app.getContext();

SSO

const token = await microsoftTeams.authentication.getAuthToken();

Toolkit Commands

The M365 Agents Toolkit (formerly Teams Toolkit) provides:

CLI commands:

npx teamsapp package --env local
npx teamsapp validate --package-file ...
npx teamsapp preview --env local

MCP tools (available when M365 Agents Toolkit extension is installed):

mcp_m365agentstoo_get_schema("app_manifest")       # Get Teams app manifest schema
mcp_m365agentstoo_get_schema("declarative_agent_manifest")  # Get DA schema
mcp_m365agentstoo_get_code_snippets("adaptive cards")       # Find code samples
mcp_m365agentstoo_troubleshoot("sideloading fails")         # Diagnose issues

@m365agents chat participant — ask in VS Code Copilot Chat:

• "I want to create a declarative agent"
• "How to add SSO?"
• "My Teams app doesn't sideload"
• "Generate a manifest for my scenario"

Common Issues

Issue	Solution	MCP Tool
Manifest fails	Check schema version	mcp_m365agentstoo_get_schema
Bot not responding	Verify endpoint/tunnel	mcp_m365agentstoo_troubleshoot
Sideload fails	Enable custom apps in admin	mcp_m365agentstoo_troubleshoot
Need code samples	Find working patterns	mcp_m365agentstoo_get_code_snippets
Conditional access blocks CLI	@m365agents for guidance or manual Developer Portal upload	mcp_m365agentstoo_troubleshoot

Conditional Access Workaround

Microsoft orgs with strict conditional access policies may block teamsapp auth login m365. Error: AADSTS530084.

Fallback: Manual Developer Portal Upload

1. Build package: npm run package:dev
2. Validate: npx teamsapp validate --package-file ./appPackage/build/appPackage.dev.zip
3. Open: https://dev.teams.microsoft.com/apps
4. Import app package → Upload zip
5. Publish to org catalog

---

Store Description Strategy

Key insight: Same product, different audiences require different messaging.

Platform	Audience	Focus
VS Code Marketplace	Developers	Code acceleration, syntax, debugging
M365/Teams	Knowledge workers	Research, analysis, productivity

M365 Positioning Example:

• ❌ "Accelerate your Python development"
• ✅ "Your AI research partner. Remembers context, grows with you."