Claude-skill-registry-data 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.