AgentSkillsCN

M365 Declarative Agent Debugging Skill

调试非功能性 M365 Copilot 声明式代理。

SKILL.md
--- frontmatter
name: "M365 Declarative Agent Debugging Skill"
description: "Debug non-functional M365 Copilot declarative agents."

M365 Declarative Agent Debugging Skill

Debug non-functional M365 Copilot declarative agents.

⚠️ Staleness Warning

M365 Copilot and Teams platform APIs are in rapid evolution. Schema versions, capabilities, and tooling change frequently.

Refresh triggers:

  • •New declarativeAgent schema versions
  • •Teams Toolkit updates
  • •New M365 Copilot capabilities
  • •Developer Portal changes

Last validated: February 2026 (Schema v1.6+)

Check current state: Declarative Agent Schema, Teams Toolkit

Schema Version Validation

Critical: Schema versions and their capabilities:

VersionStatusKey Additions
v1.0Original baselineCore capabilities
v1.2StableWebSearch sites, GraphicArt, CodeInterpreter
v1.5ExtendedTeamsMessages, Email, People
v1.6LATESTDataverse, Meetings, EmbeddedKnowledge, worker_agents

v1.3 and v1.4 DO NOT EXIST — unrecognized schema makes entire document invalid.

Capability Compatibility

Capabilityv1.2v1.5v1.6
OneDriveAndSharePoint✅✅✅
WebSearch✅✅✅
GraphicArt✅✅✅
CodeInterpreter✅✅✅
GraphConnectors✅✅✅
TeamsMessages❌✅✅
Email❌✅✅
People❌✅✅
Meetings❌❌✅
Dataverse❌❌✅
EmbeddedKnowledge❌❌✅ (not yet available)
ScenarioModels❌❌✅

Lesson: v1.5/v1.6 capabilities with v1.2 schema = silent failure.

Manifest Limits (v1.6)

PropertyLimit
name100 characters
description1,000 characters
instructions8,000 characters
conversation_starters6 items max (was 12 in v1.2)
actions1-10 items
WebSearch.sites4 items
TeamsMessages.urls5 items
Meetings.items_by_id5 items

Icon Requirements

color.png: 192×192px, solid background, logo in center 120×120 safe zone

outline.png: 32×32px, white only (#FFFFFF), transparent background (Alpha=0)

Common error:

text
Error: Outline icon is not transparent. Alpha,R,G,B: 255,X,X,X

Alpha=255 means opaque. Background pixels must be Alpha=0.

Debugging Workflow

  1. •

    Validate: teamsapp validate --package-file <zip> (must pass all checks)

  2. •

    Check schema:

    • •✅ .../declarative-agent/v1.2/schema.json
    • •❌ .../declarative-agent/v1.3/schema.json (doesn't exist)
  3. •

    Verify capabilities match schema version

  4. •

    Test icon transparency:

powershell
Add-Type -AssemblyName System.Drawing
$bmp = New-Object System.Drawing.Bitmap("outline.png")
$pixel = $bmp.GetPixel(0, 0)
$bmp.Dispose()
"Alpha: $($pixel.A)"  # Should be 0

Package Checklist

  • • manifest.json — Teams app manifest (v1.19)
  • • declarativeAgent.json — Agent config (v1.2)
  • • color.png — 192×192 solid
  • • outline.png — 32×32 white on transparent

Symptom → Cause

SymptomLikely Cause
Agent not respondingInvalid schema version
Only 1 conversation starterSchema validation failed
Validation errors on iconWrong transparency/size

Memory via OneDrive

Agent reads from OneDrive using OneDriveAndSharePoint capability:

  1. •User creates Alex-Memory/ folder in OneDrive
  2. •User shares folder link in chat
  3. •Agent reads cognitive files from shared folder
  4. •For writes: Alex generates content → user pastes

Benefits: No Azure Functions, no API costs, user controls data.

Deployment Flow

powershell
npx teamsapp package --env local
npx teamsapp validate --package-file appPackage/build/*.zip
# Upload to Developer Portal → Preview in Teams

Synapses

See synapses.json for connections.