AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

declarative-agent-developer

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"

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read microsoft--declarative-agent-developer at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 14

references/mcp-plugin.md · 24000

a specific claim with key details. Use claim ID or claim number.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } }, { "name": "create-inspection", "description": "Creates a new inspection record. Only claimNumber is required. ID is auto-generated, status defaults to 'open'. claimId is optional.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } }, { "name": "list-inspectors", "description": "Lists all available inspectors with their specializations.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } } ], "runtimes": [ { "type": "RemoteMCPServer", "auth": { "type": "None" }, "spec": { "url": "https://zava-insurance-mcp.azurewebsites.net/mcp", "mcp_tool_description": { "tools": [ { "name": "show-claims-dashboard", "description": "Displays the Zava Insurance claims dashboard showing all claims with status overview, filters, and summary metrics. Supports filtering by status and/or policy holder name. When the user mentions a person's name, first name, last name, or partial name, always pass it as the policyHolderName parameter. The name filter is case-insensitive and supports partial matches.", "inputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "Filter claims by status keyword (e.g. 'Open', 'Approved', 'Pending', 'Denied', 'Closed')" }, "policyHolderName": { "type": "string", "description": "Filter claims by policy holder name. Supports partial, case-insensitive matching." } }, "additionalProperties": false }, "annotations": { "readOnlyHint": true }, "execution": { "taskSupport": "forbidden" }, "_meta": { "ui": { "resourceUri": "ui://zava/claims-dashboard.html" } } }, { "name": "show-claim-detail", "description": "Displays detailed information about a specific insurance claim including related inspections, purchase orders, and contractor assignments. Use claim ID (e.g. '1', '2') or claim number (e.g. 'CN202504990').", "inputSchema": { "type": "object", "properties": { "claimId": { "type": "string", "description": "The claim ID or claim number to look up" } }, "required": ["claimId"], "additionalProperties": false }, "annotations": { "readOnlyHint": true }, "execution": { "taskSupport": "forbidden" }, "_meta": { "ui": { "resourceUri": "ui://zava/claim-detail.html" } } }, { "name": "show-contractors", "description": "Displays the list of contractors available for insurance repair work. Optionally filter by specialty or preferred status.", "inputSchema": { "type": "object", "properties": { "specialty": { "type": "string", "description": "Filter by contractor specialty (e.g. 'Roofing', 'Water Damage', 'Fire')" }, "preferredOnly": { "type": "boolean", "description": "Show only preferred contractors" } }, "additionalProperties": false }, "annotations": { "readOnlyHint": true }, "execution": { "taskSupport": "forbidden" }, "_meta": { "ui": { "resourceUri": "ui://zava/contractors-list.html" } } }, { "name": "update-claim-status", "description": "Updates the status of an insurance claim. Use claim ID (e.g. '1', '2').", "inputSchema": { "type": "object", "properties": { "claimId": { "type": "string", "description": "The claim ID" }, "status": { "type": "string", "description": "New status (e.g. 'Approved', 'Denied', 'Closed', 'Open - Under Investigation')" }, "note": { "type": "string", "description": "Optional note to add to the claim" } }, "required": ["claimId", "status"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "update-inspection", "description": "Updates an inspection record — status, findings, recommended actions, property, or inspector assignment.", "inputSchema": { "type": "object", "properties": { "inspectionId": { "type": "string", "description": "The inspection ID (e.g. 'insp-001')" }, "status": { "type": "string", "description": "New status (e.g. 'completed', 'scheduled', 'in-progress', 'cancelled')" }, "findings": { "type": "string", "description": "Updated findings text" }, "recommendedActions": { "type": "array", "items": { "type": "string" }, "description": "Updated recommended actions" }, "property": { "type": "string", "description": "Updated property address" }, "inspectorId": { "type": "string", "description": "Inspector ID to assign (e.g. 'inspector-003')" } }, "required": ["inspectionId"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "update-purchase-order", "description": "Updates a purchase order status (e.g. approve, reject, complete).", "inputSchema": { "type": "object", "properties": { "purchaseOrderId": { "type": "string", "description": "The purchase order ID (e.g. 'po-001')" }, "status": { "type": "string", "description": "New status (e.g. 'approved', 'rejected', 'completed', 'in-progress')" }, "note": { "type": "string", "description": "Optional note to add" } }, "required": ["purchaseOrderId", "status"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "get-claim-summary", "description": "Returns a text summary for a specific claim with key details. Use claim ID or claim number.", "inputSchema": { "type": "object", "properties": { "claimId": { "type": "string", "description": "Claim ID or claim number" } }, "required": ["claimId"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "create-inspection", "description": "Creates a new inspection record. Only claimNumber is required. ID is auto-generated, status defaults to 'open'. claimId is optional.", "inputSchema": { "type": "object", "properties": { "claimNumber": { "type": "string", "description": "The claim number (e.g. 'CN202504990')" }, "claimId": { "type": "string", "description": "Optional claim ID" }, "taskType": { "type": "string", "description": "Type of inspection: 'initial', 're-inspection', 'final'. Defaults to 'initial'" }, "priority": { "type": "string", "description": "Priority: 'low', 'medium', 'high'. Defaults to 'medium'" }, "status": { "type": "string", "description": "Status. Defaults to 'open'" }, "scheduledDate": { "type": "string", "description": "Scheduled date (ISO string)" }, "inspectorId": { "type": "string", "description": "Inspector ID to assign" }, "property": { "type": "string", "description": "Property address" }, "instructions": { "type": "string", "description": "Inspection instructions" } }, "required": ["claimNumber"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "list-inspectors", "description": "Lists all available inspectors with their specializations.", "inputSchema": { "type": "object", "properties": {} }, "execution": { "taskSupport": "forbidden" } } ] } }, "run_for_functions": [ "show-claims-dashboard", "show-claim-detail", "show-contractors", "update-claim-status", "update-inspection", "update-purchase-order", "get-claim-summary", "create-inspection", "list-inspectors" ] } ] }


> **Note how tools with UI widgets** (e.g., `show-claims-dashboard`, `show-claim-detail`, `show-contractors`) include `annotations`, `execution`, AND `_meta` with `resourceUri` — all copied verbatim from the tools/list response. Tools without UI (e.g., `update-claim-status`) still include `execution` when the server returned it, but omit `annotations` and `_meta` since the server didn't provide them.

Register in `declarative-agent.json`: `{ "actions": [{ "id": "zavaPlugin", "file": "zava-plugin.json" }] }`

---

## Complete Example — Authenticated Server

For an OAuth-protected MCP server at `https://mcp.example.com/mcp`. See [authentication.md](authentication.md) for the full `oauth/register` template (must be added to both `m365agents.yml` and `m365agents.local.yml`).

### `appPackage/example-plugin.json`

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.4/schema.json",
  "schema_version": "v2.4",
  "name_for_human": "Example Service",
  "description_for_human": "Search and browse Example Service content",
  "namespace": "example",
  "functions": [
    {
      "name": "search",
      "description": "Search Example Service for content matching a query.",
      "capabilities": { "response_semantics": { "data_path": "$.items", "properties": { "title": "$.title", "url": "$.url" }, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "[${title}](${url})", "wrap": true, "maxLines": 2 }] } } }
    }
  ],
  "runtimes": [
    {
      "type": "RemoteMCPServer",
      "auth": { "type": "OAuthPluginVault", "reference_id": "${{<PREFIX>_MCP_AUTH_ID}}" },
      "spec": {
        "url": "https://mcp.example.com/mcp",
        "mcp_tool_description": {
          "tools": [
            { "name": "search", "description": "Search Example Service for content matching a query.", "inputSchema": { "type": "object", "properties": { "query": { "description": "Search query", "type": "string" } }, "required": ["query"] } }
          ]
        }
      },
      "run_for_functions": ["search"]
    }
  ]
}

Multiple MCP Servers

You can integrate multiple MCP servers by adding multiple runtimes, each with its own auth type. Each runtime has its own mcp_tool_description.tools and run_for_functions:

{
  "functions": [
    { "name": "docs_search", "description": "Search Microsoft docs.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } },
    { "name": "search", "description": "Search authenticated service.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } }
  ],
  "runtimes": [
    {
      "type": "RemoteMCPServer",
      "auth": { "type": "None" },
      "spec": { "url": "https://learn.microsoft.com/api/mcp", "mcp_tool_description": { "tools": [{ "name": "docs_search", "description": "Search Microsoft docs.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] } }] } },
      "run_for_functions": ["docs_search"]
    },
    {
      "type": "RemoteMCPServer",
      "auth": { "type": "OAuthPluginVault", "reference_id": "${{<PREFIX>_MCP_AUTH_ID}}" },
      "spec": { "url": "https://mcp.example.com/mcp", "mcp_tool_description": { "tools": [{ "name": "search", "description": "Search authenticated service.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] } }] } },
      "run_for_functions": ["search"]
    }
  ]
}

Common Issues

| Issue | Solution | |---|---| | Plugin fails to load | Verify {name}-plugin.json exists and has correct mcp_tool_description.tools array | | Tools not recognized | Verify function names match exactly between functions[] and mcp_tool_description.tools[] | | Runtime errors | Check that run_for_functions includes all functions using that runtime | | OAuth token errors | Re-authenticate with mcp-remote — cached tokens may have expired | | <PREFIX>_MCP_AUTH_ID empty | Check oauth/register step in both m365agents.yml and m365agents.local.yml and verify credentials | | "Invalid redirect URI" | Ensure redirect URI in DCR is https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect |


Best Practices

  1. Always discover tools via MCP protocol — run the full handshake (initialize → notifications/initialized → tools/list) before writing the plugin manifest. NEVER fabricate tool names or descriptions.
  2. Full-fidelity tool copying in mcp_tool_description.tools — each tool object must be a verbatim copy of the tools/list output. Copy every property exactly as returned (inputSchema, annotations, execution, _meta, outputSchema, title, and any other field). The MCP protocol evolves — do NOT maintain a hardcoded allowlist of known fields. If the server returns it, the plugin must include it. Never abbreviate, omit, or rename properties. Do NOT duplicate inputSchema or other properties in functions[].
  3. Inline tools in mcp_tool_description.tools — do NOT use a separate tools file; embed the tools array directly in the runtime spec
  4. Match function names exactly — copy tool names directly from the tools/list output
  5. Always add response semantics — every function must have capabilities.response_semantics, even if using the default (empty body) pattern
  6. Include all tools by default — inline every tool from tools/list unless the developer explicitly asks to limit the set; for all included tools always keep the complete tool object with all properties
  7. Logos are optional — ask the user if they want a custom logo; if not, use the defaults from npx -y --package @microsoft/m365agentstoolkit-cli atk new. Logos must be PNG only (no JPG, SVG, etc.)