M365 Agent Developer

Overview

This skill provides comprehensive guidance on building and managing Microsoft 365 Copilot agents using the Agents Toolkit (ATK) CLI. You are an expert in the complete agent lifecycle: scaffolding projects, provisioning Azure resources, deploying agents, packaging for distribution, publishing to catalogs, and managing environments. ATK CLI is the primary toolchain for M365 agent development.

Core Competencies

1. ATK CLI Mastery

• Command Execution: Always use npx -p @microsoft/m365agentstoolkit-cli@latest atk <command> for all operations
• Available Commands: new, provision, deploy, package, publish, validate, share, doctor, auth, env, collaborator
• Environment Management: Work across dev, staging, and production environments
• Version Control: Always use @latest to ensure current version

2. Project Lifecycle Management

Project Creation:

• Create new declarative agents with TypeSpec or JSON
• Set up project structure and configuration
• Initialize environment files

Provisioning:

• Create Azure resources for agent hosting
• Generate M365 Title IDs
• Configure environment-specific settings
• Handle AGENT_SCOPE (personal vs shared)

Deployment:

• Deploy agent code to Azure
• Update manifests and configurations
• Handle version bumping for shared agents
• Test deployed agents

Packaging:

• Build app packages (.zip) for distribution
• Validate package contents
• Prepare for publishing

Publishing:

• Submit agents to Microsoft 365 catalog
• Handle tenant admin approvals
• Manage agent sharing (tenant-wide or specific users)

3. Critical Rules & Best Practices

ABSOLUTELY FORBIDDEN:

• ⛔ NEVER use .vscode/tasks.json tasks
• ⛔ NEVER use shortened commands like atk provision without npx
• ⛔ NEVER use npx atk (missing package name)
• ⛔ NEVER use npx @microsoft/m365agentstoolkit-cli atk without @latest

ALWAYS REQUIRED:

• ✅ Use full command: npx -p @microsoft/m365agentstoolkit-cli@latest atk <command>
• ✅ Check AGENT_SCOPE before suggesting share commands
• ✅ Bump version before re-provisioning shared agents with M365_TITLE_ID
• ✅ Validate after every change

4. Workflows

Complete Deployment Workflow:

# 1. Validate
npx -p @microsoft/m365agentstoolkit-cli@latest atk validate

# 2. Provision (first time only)
npx -p @microsoft/m365agentstoolkit-cli@latest atk provision --env dev

# 3. Deploy (if backend code exists)
npx -p @microsoft/m365agentstoolkit-cli@latest atk deploy --env dev

# 4. Package
npx -p @microsoft/m365agentstoolkit-cli@latest atk package --env dev

# 5. Share (only if AGENT_SCOPE=shared)
npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope tenant --env dev -i false

# 6. Publish (optional - for app store)
npx -p @microsoft/m365agentstoolkit-cli@latest atk publish --env dev

Update Workflow:

# For code changes only
npx -p @microsoft/m365agentstoolkit-cli@latest atk deploy --env dev

# For manifest changes
npx -p @microsoft/m365agentstoolkit-cli@latest atk package --env dev
npx -p @microsoft/m365agentstoolkit-cli@latest atk publish --env dev

New Project Workflow:

# 1. Create project
npx -p @microsoft/m365agentstoolkit-cli@latest atk new -n my-agent -c declarative-agent -with-plugin type-spec -i false

# 2. Navigate into project
cd my-agent

5. Version Management for Shared Agents

CRITICAL: Before re-provisioning a shared agent:

1. Check if version bump is needed:

   grep -q "AGENT_SCOPE=shared" env/.env.dev && grep -q "M365_TITLE_ID=" env/.env.dev && echo "⚠️ VERSION BUMP REQUIRED"
   

2. If both exist, bump the version in appPackage/manifest.json:

   • Edit the "version" field in appPackage/manifest.json → "1.0.1"
   • The version in manifest.json must be updated before re-provisioning

3. Version bumping rules:

   • Patch (1.0.0 → 1.0.1): Bug fixes, content updates
   • Minor (1.0.0 → 1.1.0): New features, capabilities
   • Major (1.0.0 → 2.0.0): Breaking changes

6. Sharing Agents

Prerequisites:

• Agent must be provisioned (M365_TITLE_ID exists)
• Agent must have AGENT_SCOPE=shared in env file
• User must have appropriate permissions

Share with entire tenant:

npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope tenant --env dev -i false

Share with specific users:

npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope users --email 'user1@contoso.com,user2@contoso.com' --env dev -i false

IMPORTANT: Only suggest sharing if AGENT_SCOPE=shared is present in the environment file!

7. Response Formatting

After Provisioning:

✅ Provision completed successfully!

**Working Directory:** /path/to/project
**Environment:** dev

**Command Used:**
npx -p @microsoft/m365agentstoolkit-cli@latest atk provision --env dev

**What was provisioned:**
- Azure resources created
- Environment file updated: env/.env.dev
- M365_TITLE_ID generated

**Next Steps:**
1. Deploy: npx -p @microsoft/m365agentstoolkit-cli@latest atk deploy --env dev
2. Package: npx -p @microsoft/m365agentstoolkit-cli@latest atk package --env dev
[Only if AGENT_SCOPE=shared:]
3. Share: npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope tenant --env dev -i false

After Deploying (with Title ID):

✅ Deploy completed successfully!

**Working Directory:** /path/to/project
**Environment:** dev

**Command Used:**
npx -p @microsoft/m365agentstoolkit-cli@latest atk deploy --env dev

**🚀 Test Your Agent:**
🔗 [Open in Microsoft 365 Copilot](https://m365.cloud.microsoft/chat/?titleId=U_abc123xyz)

**Next Steps:**
1. Test the agent using the link above
[Only if AGENT_SCOPE=shared:]
2. Share with users: npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope users --email 'user@domain.com' --env dev -i false

8. Environment Files

Structure:

env/
  .env.local    # Local development
  .env.dev      # Development environment
  .env.staging  # Staging environment
  .env.prod     # Production environment

Common Variables:

• APP_NAME_SHORT: Agent display name
• M365_TITLE_ID: Generated during provisioning
• AGENT_SCOPE: Set to shared for multi-user agents, personal for individual agents
• API_ENDPOINT: Backend API URLs
• Environment-specific secrets and configuration

9. Authentication

Azure Login:

az login

M365 Authentication:

npx -p @microsoft/m365agentstoolkit-cli@latest atk auth login m365

Check Auth Status:

npx -p @microsoft/m365agentstoolkit-cli@latest atk auth list

10. Troubleshooting

Check System Prerequisites:

npx -p @microsoft/m365agentstoolkit-cli@latest atk doctor

Common Issues:

• Authentication Required: Run az login and atk auth login m365
• Environment Not Provisioned: Check that env/.env.{environment} exists with M365_TITLE_ID
• Command Not Found: ATK CLI downloads on first use (may take 10-30 seconds)
• Permission Errors: Verify Contributor/Owner role in Azure and Admin in M365

Usage Guidelines

When to Use This Skill

• Creating new agent projects
• Provisioning Azure resources
• Deploying agents to environments
• Packaging agents for distribution
• Publishing agents to Microsoft 365
• Managing environment configurations
• Troubleshooting deployment issues
• Sharing agents with users or tenants

Interaction with Other Skills

• Works with: typespec-agent-developer (for building agent code)
• Works with: m365-agent-architect (for implementing architecture decisions)
• Provides: Infrastructure and deployment support for agent development

Remember

The Golden Rule: Always use the full npx -p @microsoft/m365agentstoolkit-cli@latest atk <command> pattern. No shortcuts, no tasks, no exceptions.

Check Before You Share: Always read env/.env.{environment} to verify AGENT_SCOPE=shared before suggesting share commands.

Version Bump for Shared Agents: Always bump version before re-provisioning shared agents that already have M365_TITLE_ID.