AutoGineer
Generated banner for Declarative Agent Developer
Generated logo for Declarative Agent Developer

Declarative Agent Developer

MicrosoftOfficialPublished by Microsoft

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
Download ZIP

From the author

Create, build, deploy, and localize declarative agents for M365 Copilot and Teams. USE THIS SKILL for ANY task involving a declarative agent — including localization, scaffolding, editing manifests, adding capabilities, and deploying. Localization requires tokenized manifests and language files that only this skill knows how to produce. Triggers: "create agent", "create a declarative agent", "new declarative agent", "scaffold an agent", "new agent project", "add a capability", "add a plugin", "configure my agent", "deploy my agent", "fix my agent manifest", "edit my agent", "localize my agent", "add localization", "translate my agent", "multi-language agent", "add an API plugin", "add an MCP plugin", "add OAuth to my plugin", "review instructions", "improve instructions", "fix my instructions"
— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The declarative-agent-developer skill provides a structured workflow for managing the lifecycle of M365 Copilot and Teams declarative agents. It utilizes the M365 Agent Toolkit (ATK) CLI to handle project scaffolding, manifest management, API plugin integration, and deployment. The skill enforces strict workspace validation, requiring specific project structures before allowing modifications, and provides standardized protocols for error handling, localization, and authentication configuration.

What it does

  • Scaffolds new declarative agent projects using the ATK CLI.
  • Manages and validates declarativeAgent.json manifests.
  • Integrates API plugins and MCP servers into existing agent projects.
  • Configures OAuth authentication for secure plugin communication.
  • Handles localization of agent manifests and language files.
  • Deploys agents to local environments for testing and validation.

When to use it

  • When creating a new declarative agent project for M365 Copilot or Teams.
  • When adding new capabilities, API plugins, or MCP servers to an existing agent.
  • When updating agent instructions or conversation starters.
  • When localizing an agent for multiple languages.
  • When troubleshooting or fixing errors in an agent manifest.

Advantages

  • Ensures consistent project structure through mandatory workspace checks.
  • Automates complex tasks like API plugin registration and OAuth setup.
  • Provides a clear, step-by-step protocol for error detection and resolution.
  • Facilitates standardized deployment and testing workflows.
  • Maintains schema compatibility by checking version requirements before feature implementation.

Usage examples

“Create a new declarative agent project.”
The agent will initialize a new project structure, including the necessary manifest files, provided the workspace is empty and valid for agent development.
“Add an API plugin to my agent using this OpenAPI spec URL.”
The agent will use the ATK CLI to integrate the specified API, map the requested operations, and prompt for necessary metadata updates.
“Localize my agent into French.”
The agent will generate the required tokenized manifests and language files to support French localization.
“Deploy my agent to the local environment.”
The agent will run the provisioning command and provide the M365 test link for the deployed agent.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/microsoft/declarative-agent-developer/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip declarative-agent-developer.zip -d .agents/skills

Documentation by Microsoft

M365 Agent Developer

Telemetry Tagging

Before running any atk CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:

export ATK_CLI_SKILL=true

Run this once at the start of the session. All subsequent atk commands in the same terminal will inherit it.

⛔ Workspace Check — MANDATORY FIRST STEP

Before doing ANYTHING, check the workspace files to fingerprint the project:

  1. Run npx -y --package @microsoft/m365agentstoolkit-cli atk --version to confirm ATK CLI is installed. If not found → Stop. Tell the user to install ATK.

  2. Check for m365agents.yml or teamsApp.yml at the project root.

  3. Check for appPackage/declarativeAgent.json.

  4. Check for non-agent indicators (package.json with express/react/next, src/index.js, app.py, etc.)

Then follow the decision gate:

ConditionGateAction
Non-agent project files, no appPackage/RejectText-only response. No files, no commands.
No manifest, user wants to edit/deployRejectText-only response. Explain manifest is missing.
No manifest, user wants new projectScaffold→ Scaffolding Workflow
Manifest exists with errorsFixDetect → Inform → Ask (see below). Do NOT deploy.
Valid project, user reports behavior issuesReview→ Instruction Review — run the full 5-phase review workflow
Valid agent projectEdit→ Editing Workflow

Detailed gate rules, examples, and anti-patterns: Workspace Gates

🚫 HARD REJECTION RULES — No Exceptions

These rules override ALL other instructions. If any of these apply, you MUST stop immediately.

  1. NEVER create declarativeAgent.json yourself. If the manifest is missing and the user asked to edit/modify/deploy, respond with text only: explain the manifest is missing, suggest npx -y --package @microsoft/m365agentstoolkit-cli atk new or starting from scratch. Do NOT create the file, do NOT create appPackage/, do NOT "help" by scaffolding implicitly.

  2. NEVER create files in a non-agent project. If the workspace is an Express/React/Django/etc. app without appPackage/, your response must be text-only. Do NOT create any files, do NOT run any commands.

  3. NEVER deploy when errors exist. If the agent manifest has errors, STOP. Do NOT run npx -y --package @microsoft/m365agentstoolkit-cli atk provision — not "to test", not "to demonstrate the error", not "to see what happens". Report the errors and ask the user how to proceed.

🔍 Detect → Inform → Ask (Error-Handling Protocol)

When you encounter ANY problem (missing files, malformed JSON, validation errors, incompatible features), you MUST follow this sequence in order:

  1. Detect — Identify the specific problem. For JSON issues, attempt to parse the file and report syntax errors. For missing fields, check the manifest against the Schema.

  2. Inform — Tell the user BEFORE taking any action. Describe exactly what is wrong ("declarativeAgent.json has malformed JSON: missing comma on line 12, unclosed array on line 18").

  3. Ask — Wait for the user's response before making changes. Do NOT silently fix, auto-correct, or work around the problem.

This protocol applies to:

  • Missing declarativeAgent.json → Detect (file not found) → Inform ("no manifest found") → Ask ("would you like to create a new agent?")

  • Malformed JSON → Detect (parse errors) → Inform (list specific syntax issues) → Ask ("should I fix these syntax errors?")

  • Validation errors → Detect (parse and check manifest) → Inform (list all errors) → Ask ("how would you like to fix these?")

  • Version incompatibility → Detect (feature requires newer version) → Inform ("this feature requires v1.6, your agent is v1.4") → Ask ("should I upgrade?")

Phase Routing

ScenarioWorkflow Reference
Creating a NEW project from scratchScaffolding Workflow
Working with existing .json manifestsEditing Workflow
Adding an API pluginAPI Plugins
Adding an MCP serverMCP Plugin
Adding OAuth to an MCP or API pluginAuthentication
Reviewing or improving existing agent instructionsInstruction Review
User reports agent gives generic/wrong answersInstruction Review
Localizing an agent into multiple languagesLocalization
Adding a new language to an already-localized agentLocalization
Writing agent instructionsConversation Design

ATK CLI Setup

Before running any ATK commands, check if the ATK CLI is available by running npx -y --package @microsoft/m365agentstoolkit-cli atk --version. If not found, STOP and tell the user — do NOT attempt to install it yourself.

All commands use the npx -y --package @microsoft/m365agentstoolkit-cli atk prefix (e.g., npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local).

Critical Rules

1. Deploy After EVERY Edit

After ANY change to files in appPackage/, you MUST deploy and show the test link before responding:

npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false

Then read M365_TITLE_ID from env/.env.local and ALWAYS present the review UX:

✅ Agent deployed successfully!

🚀 Test Your Agent in M365 Copilot:
🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID}

⛔ Never respond without this link. If you deployed, the test link MUST appear in your response. This is not optional — it is how the user tests their agent.

  • If the manifest has errors → STOP. Fix errors. Do NOT deploy.

  • Exception: user explicitly asks you not to deploy

2. Never Invent Content or Create Missing Files

  • Do NOT invent placeholder names, descriptions, or instructions

  • Do NOT create declarativeAgent.json or appPackage/ if they don't exist — this is a REJECT scenario, not a "help by creating" scenario

  • If required fields are missing, report the gaps, and ASK the user

  • If JSON is malformed, follow Detect → Inform → Ask: parse the file first, tell the user what's broken, then ask before fixing. Use surgical edits (not rewrites)

  • ⛔ NEVER set placeholder values for environment variables that are populated by automation (e.g., <PREFIX>_MCP_AUTH_ID, TEAMS_APP_ID). Leave them empty (VAR_NAME=). Placeholders will be treated as real values and will NOT be overwritten by provisioning.

3. Schema Version Compatibility

Before adding ANY feature, read the version field in declarativeAgent.json and check the Schema feature matrix. If the feature isn't supported in that version, refuse and offer to upgrade.

Key version gates:

  • sensitivity_label, worker_agents, EmbeddedKnowledge → v1.6 only

  • Meetings → v1.5+

  • ScenarioModels, behavior_overrides, disclaimer → v1.4+

  • Dataverse, TeamsMessages, Email, People → v1.3+

4. Use npx -y --package @microsoft/m365agentstoolkit-cli atk add action for API Plugins — NEVER Create Plugin Files Manually

You are forbidden from manually creating ai-plugin.json, OpenAPI specs, adaptive cards, or editing the actions array. Use the CLI:

# ⛔ Always list ALL operations in a single call — NEVER run separate calls per operation
npx -y --package @microsoft/m365agentstoolkit-cli atk add action --api-plugin-type api-spec --openapi-spec-location URL --api-operation "GET /path,POST /path,PATCH /path/{id},DELETE /path/{id}" -i false

Run a single npx -y --package @microsoft/m365agentstoolkit-cli atk add action call per OpenAPI spec, listing all operations as a comma-separated list in --api-operation. Never run separate npx -y --package @microsoft/m365agentstoolkit-cli atk add action calls for different operations from the same spec — this creates multiple plugins instead of one. If npx -y --package @microsoft/m365agentstoolkit-cli atk add action fails, report the error; do NOT fall back to manual creation.

Exception: MCP servers are not supported by npx -y --package @microsoft/m365agentstoolkit-cli atk add action. Use the MCP Plugin workflow instead.

5. MCP Server Integration

When the user mentions an MCP server URL, follow the MCP Plugin workflow. You MUST discover tools via the MCP protocol handshake (initialize → notifications/initialized → tools/list) — NEVER fabricate tool names/descriptions. For authenticated MCP servers, follow the authentication guide to configure OAuth.

6. Always Update Instructions & Starters After Changes

Adding a capability or plugin without updating instructions is incomplete. After ANY change:

  1. Update instructions to describe the new/changed functionality — every data source should have clear intent coverage (WHEN and WHY to use it) per the Instruction Review quality bar. Built-in capabilities don't need exact names; actions/plugins should be named.

  2. Do NOT list tool names, descriptions, or parameters in instructions — these are already in the plugin metadata (ai-plugin.json, MCP manifests, capability config). Instructions should contain decision logic only: WHEN to use each tool, chaining rules, and failure handling.

  3. Stay within the 8,000-character instruction limit — if close to the limit, cut tool descriptions first

  4. Add at least 1 conversation starter per added capability/plugin

  5. Remove starters that reference removed capabilities

  6. Run the Diagnostic Checklist against the updated instructions to verify quality

7. App Name Requirement

Always update the app name and description to something meaningful. Never leave defaults like "My Agent".

References

Shared

  • Authentication — OAuth discovery, credentials, oauth/register lifecycle, OAuthPluginVault

  • Best Practices — Security, performance, testing, compliance

  • Conversation Design — Authoring instructions and conversation starters from scratch

  • Instruction Review — Auditing, diagnosing, and improving existing instructions; anti-pattern detection; before/after rewrites

  • Deployment — ATK CLI workflows, environments, CI/CD

  • Localization — Multi-language support, tokenized manifests, language files

  • Workspace Gates — Detailed gate rules, examples, anti-patterns

Scaffolding
JSON Development

  • Editing Workflow — Step-by-step JSON development instructions

  • Schema — Official JSON schema for agent manifests

  • API Plugins — OpenAPI integration for JSON agents

  • MCP Plugin — MCP server integration with RemoteMCPServer, OAuth, response semantics, logo handling

  • Examples — JSON manifest examples

Files

references/scaffolding-workflow.md

Scaffolding Workflow

Step-by-step instructions for scaffolding a new M365 Copilot agent project.

⛔ STOP — READ THIS FIRST

ATK CLI Setup

Check if ATK CLI is available by running npx -y --package @microsoft/m365agentstoolkit-cli atk --version. If the command is not found, STOP and tell the user that the ATK CLI is required but not installed. Do NOT attempt to install it yourself — the user must install ATK separately before you can proceed.

The Only Valid Command

Copy this command EXACTLY. Replace <project-name> with the user's project name:

npx -y --package @microsoft/m365agentstoolkit-cli atk new -n <project-name> -c declarative-agent -with-plugin no -i false
Forbidden Commands — These Do Not Exist
❌ Invalid CommandWhy It Fails
npx -y --package @microsoft/m365agentstoolkit-cli atk initDOES NOT EXIST — there is no init command
npx -y --package @microsoft/m365agentstoolkit-cli atk init --templateDOES NOT EXIST — there is no init or --template flag
npx -y --package @microsoft/m365agentstoolkit-cli atk createDOES NOT EXIST — there is no create command
npx -y --package @microsoft/m365agentstoolkit-cli atk scaffoldDOES NOT EXIST — there is no scaffold command
--template anythingDOES NOT EXIST — there is no --template flag

Workflow

Step 1: Understand the Request

Action: Verify the user wants to create a NEW M365 Copilot agent project.

Check for:

  • Keywords: "new project", "create agent", "scaffold", "start from scratch", "M365 Copilot", "M365 agent", "declarative agent"

  • Confirmation this is NOT an existing project

If existing project: Stop and use the editing workflow instead.

Step 2: Verify Empty Directory and Collect Project Name

Action: Check if the current directory is empty, then ask for the project name.

Directory check (CRITICAL):

  • Use ls -A to check if the current directory is empty

  • Ignore hidden folders (starting with .) — these are meta-configuration folders (.claude, .copilot, .github) and should not block scaffolding

  • If ONLY hidden folders exist, treat the directory as empty and proceed

  • If directory has non-hidden files/folders, ERROR OUT immediately:

    ❌ Error: Current directory is not empty!

This skill requires an empty directory to scaffold a new M365 Copilot agent project.
Please navigate to an empty directory or create a new one first.

  • Do NOT ask for a project name until the directory check passes

Project naming rules:

  • Use kebab-case (lowercase with hyphens): customer-support-agent, expense-tracker

  • Keep it concise: 2–4 words maximum

  • No spaces, underscores, or special characters

  • ✅ Good: sales-dashboard, document-finder, hr-faq-agent

  • ❌ Bad: agent1, test, ExpenseTrackerAgent, my project

Step 3: Run ATK CLI Command and Move Files

Action: Execute the scaffolding command, then move files from the ATK-created subfolder to the current directory.

Always use -i false (non-interactive mode) to prevent unexpected prompts.

Commands to execute sequentially:

  1. Create the project:

npx -y --package @microsoft/m365agentstoolkit-cli atk new -n <project-name> -c declarative-agent -with-plugin no -i false

  1. Move all files from the subfolder to current directory:

mv <project-name>/* <project-name>/.* . 2>/dev/null || true

  1. Delete the now-empty subfolder:

rmdir <project-name>

  1. Verify success:

  • Check that key files exist in the current directory (package.json, m365agents.yml)

  • Confirm the ATK-created subfolder was removed

  • If the command fails, report the error and stop — do NOT retry automatically

Step 4: Add Agent Context Files

Action: Ensure the project has context files that tell coding agents which skills are available and how to invoke them. This is critical for future sessions — without these files, agents won't know to use the declarative-agent-developer skill.

Detection logic — check for existing files in this order:

  1. .github/copilot-instructions.md — if it exists, edit it to append the skill context block below

  2. AGENTS.md — if it exists, edit it to add the skill context block below

  3. CLAUDE.md (that is NOT a symlink) — if it exists, edit it to add the skill context block below

  4. If NONE of the above exist — create both:

    • AGENTS.md — with the full content below

    • CLAUDE.md — as a symlink to AGENTS.md (ln -sf AGENTS.md CLAUDE.md)

Content to add (when editing an existing file, append this section; when creating AGENTS.md, use this as the full content):

# M365 Declarative Agent Project

This is an M365 Copilot declarative agent project managed by the ATK CLI.

## Available Skills

When working on this project, you MUST use the appropriate skill for the task. **Do NOT work directly on files without invoking a skill first.**

| Skill | When to Use |
|-------|-------------|
| **declarative-agent-developer** | Any task involving this agent (see scenarios below). **This is the primary skill for this project.** |
| **ui-widget-developer** | Only when adding an MCP server that renders rich interactive widgets (HTML) in Copilot Chat using the OpenAI Apps SDK. |
| **install-atk** | Only when the ATK CLI is not installed or needs updating. |

## ⛔ MANDATORY: Invoke `declarative-agent-developer` Skill First

**This is a declarative agent project. For ANY task in this workspace — regardless of what it is — you MUST invoke the `declarative-agent-developer` skill BEFORE doing any work.** This is not optional. Do not attempt to handle any task yourself. Always delegate to the skill.

### Scenarios handled by this skill

- Creating a new agent project from scratch
- Editing manifests (declarativeAgent.json, manifest.json, m365agents.yml)
- Adding or removing capabilities (web search, Graph connectors, etc.)
- Adding API plugins from OpenAPI specs
- Adding MCP server plugins
- Adding OAuth authentication to plugins
- Localizing an agent into multiple languages
- Adding a new language to an already-localized agent
- Writing or updating agent instructions
- Deploying and provisioning with `atk provision`
- Validating the project with `atk validate`
- Fixing manifest errors or validation failures

**Do NOT:**
- Edit `declarativeAgent.json` or other manifest files directly without the skill
- Run `npx -y --package @microsoft/m365agentstoolkit-cli atk` commands without the skill
- "Help" by manually making changes — always delegate to the skill

Rules:

  • When editing an existing file, preserve all existing content — append the skill context block at the end

  • When creating new files, use the content above as-is

  • Always create the CLAUDE.md symlink when creating a new AGENTS.md — both GitHub Copilot CLI and Claude Code read these files automatically

  • This step is NOT optional — every scaffolded project must have agent context files

Step 5: Confirm and Continue

Action: Provide a brief confirmation and immediately continue to the editing workflow.

✅ Project scaffolded in current directory: <absolute-current-directory-path>

Your M365 Copilot agent project structure is ready (JSON-based).
Agent context files have been added for future skill invocation.

🚀 Continuing to help you design and implement your agent...

Then invoke the editing workflow — do NOT wait for user input.

Scope Boundaries

This workflow only handles project creation and agent context setup. After scaffolding:

  • ✅ Confirm creation and hand off to the editing workflow automatically

  • ❌ Do NOT discuss architecture, capability selection, or API plugin design

  • ❌ Do NOT write JSON manifests, instructions, or configuration

  • ❌ Do NOT create TODO files, open VS Code workspaces, or run extra commands

  • ❌ Do NOT provide implementation guidance — that's for the editing workflow

Error Handling

ErrorAction
ATK CLI not installedStop. Tell the user to install ATK first.
Directory not emptyStop. Show error message. Do not proceed.
Invalid project nameWarn and suggest a corrected name.
npx -y --package @microsoft/m365agentstoolkit-cli atk new command failsReport the error with full output. Do not retry.
File move failsReport the error. Files may still be in the subfolder.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Node.js

Security

What our scanner noticed· Low risk

  • Phrasing that asks for actions without confirmation
  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Microsoft
Publisher
Microsoft (Official)
Source
microsoft/skills · .github/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer · commit 0696600
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download declarative-agent-developer.zip