Localized reading guide

declarative-agent-developerPurpose, usage and source

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"

Source retrieved: 2026-10-29

Source repository: microsoft/skills
SKILL.md: .github/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/SKILL.md
Repository stars: 3,157
Repository updated: 2026-10-31
Categories: Agent workflows
Last collected: 2026-10-31 10:38 UTC+08:00

License: MIT

Source SKILL.md

Workflow excerpts are reading aids, not executable instructions from Codez. No third-party Skill was run to produce this page.

The purpose and workflow passages below are upstream material, organized and translated for reading. They are distinct from the separately labeled Codez editorial analysis.

What this Skill does

How the upstream workflow works

⛔ Workspace Check — MANDATORY FIRST STEP

Before doing ANYTHING, check the workspace files to fingerprint the project: 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. Check for m365agents.yml or teamsApp.yml at the project root. Check for appPackage/declarativeAgent.json.

Upstream passage · L26 ↗

6. Always Update Instructions & Starters After Changes

Adding a capability or plugin without updating instructions is incomplete. After ANY change: 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. 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. Add at least 1 conversation starter per added capability/plugin

Upstream passage · L158 ↗

Upstream passage · bash ↗

export ATK_CLI_SKILL=true

Requirements and setup

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).

Upstream passage · L91 ↗

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:

Upstream passage · L131 ↗

Limits and quality checks

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

Upstream passage · L123 ↗

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

Upstream passage · L141 ↗

Start with a safe trial

Check the supported host and the repository installation instructions. Keep the Skill directory and its referenced scripts, assets and documentation together; SKILL.md alone may omit dependencies.
Give the agent your real input, desired output and acceptance criteria. Invocation syntax and available tools depend on the host; this site does not assume a universal install command.
Try the source workflow in a disposable project or on a copy. Review operations that change files, remote services or billable resources before allowing them.
Validate the output against the source quality checks and your own requirements. A successful trigger or a high repository Star count does not establish a correct result.

Skill format and directory specification ↗

Read further in the source

Translation and scope

This reading guide selects passages from the pinned upstream SKILL.md. Translation is assisted. It is not a complete manual or a claim of tested compatibility. Read the original and its referenced files before use.

This introduction refers to the pinned version below; current repository activity and collection time are shown separately.

Pinned source: Read the original ↗
Source retrieved: 2026-10-29T09:32:23Z
Source commit: 00d66a64919edca5bca2c673373444e36a4b5461
Source SHA-256: 13d2af8dd44cca049c8ebf8a8880cca304fc3dc419c926ef146dba35b14df412

Back to the full Skill catalog