Teams App Patterns

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, EXTERNAL-API-REGISTRY.md

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

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:

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)

❌ 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

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.

M365 Positioning Example:

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