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/instruction-review.md

Instruction Review & Quality Audit

This reference defines how to evaluate, diagnose, and improve existing agent instructions. Use it whenever you touch instructions — whether auditing an existing agent, adding a capability, or responding to a user who says their agent "doesn't work well."

When to use this guide:

  • User asks to "review", "improve", "audit", or "fix" their agent's instructions
  • User reports the agent "doesn't use the right tool", "gives generic answers", or "doesn't follow the process"
  • You are adding a capability or plugin and need to update instructions (mandatory per the editing workflow)
  • You are reviewing an agent before deployment
  • Agent behavior changed after a model update (GPT 5.0 → 5.1 → 5.2)
  • User wants to migrate instructions for a newer model version

Official references: This guide synthesizes and operationalizes the official Microsoft guidance:


GPT 5.2 Model Awareness

As of April 2026, M365 Copilot uses GPT 5.2. Understanding the model's behavior is essential for writing and reviewing instructions, because the same instructions can produce very different results across model versions.

Instruction Token Budget

Instructions are limited to 8,000 characters. Every character counts. This hard limit means you must be surgical about what goes into instructions.txt:

  • DO include: Decision logic (WHEN to use which capability), workflows with transitions, failure handling, chaining rules, domain vocabulary, output contracts, self-evaluation gates
  • DO NOT include: Tool descriptions, function parameter lists, API schemas, or anything already documented in the plugin metadata

⛔ CRITICAL: Do NOT duplicate tool/capability metadata in instructions.

The orchestrator already has access to tool names, descriptions, and parameters through:

  • ai-plugin.json → description_for_model and function definitions
  • MCP plugin manifest → mcp_tool_description.tools[] with full inputSchema
  • Capability configuration in declarativeAgent.json
  • Meta-prompts injected by the orchestration layer

Listing tools and their parameters in instructions is a waste of the 8,000-character budget. Instead, instructions should provide decision logic that the metadata cannot express: WHEN to choose one tool over another, HOW to chain tools together, and WHAT to do when a tool returns no results.

What belongs in instructions vs metadata

| Belongs in instructions.txt | Belongs in plugin metadata (NOT instructions) | |-------------------------------|------------------------------------------------| | WHEN to use a capability: "Search SharePoint first, fall back to web search" | Tool name and description | | Chaining logic: "After getting weather, create a task with the result" | Function parameters and types | | Failure handling: "If no results, ask the user to rephrase" | Input schemas and validation rules | | Confirmation gates: "Always confirm before deleting" | Response format / adaptive cards | | Multi-turn rules: "Collect all 3 values before calling the API" | API endpoint details | | Domain vocabulary and business rules | Tool-level description_for_model | | Output format and reasoning depth | MCP inputSchema, annotations, execution |

The Model Shift: Literal-First → Intent-First

| Behavior | GPT 5.0 (old) | GPT 5.1+ / 5.2 (current) | |----------|---------------|---------------------------| | Interpretation | Literal — follows instructions step-by-step as written | Intent-first — interprets what instructions intended, not just what they said | | Missing steps | Fails or responds narrowly | Fills gaps, infers missing steps, replans its approach | | Ambiguity | Follows the first plausible path | Dynamically selects reasoning depth; may reorder or merge steps | | Tone | Direct and factual by default | Adapts tone based on inferred context; supports 8 output profiles | | Reasoning | Fixed: chat model OR reasoning model | Adaptive: chooses model + reasoning depth per sub-task within a single request |

What This Means for Instruction Review

GPT 5.2's intent-first behavior amplifies the impact of instruction quality:

  • Well-structured instructions → GPT 5.2 follows them more precisely than GPT 5.0 and can adaptively fill in routine details
  • Ambiguous instructions → GPT 5.2 will replan and improvise, which may produce unexpected behavior: reordered steps, merged tasks, tone drift, added/removed steps based on inferred context
  • Output-only instructions → GPT 5.2 will infer the entire process, often incorrectly, because the instructions give it maximum freedom to interpret intent

Bottom line: The weaker the instructions, the more GPT 5.2 will improvise — and improvisation in structured workflows is a bug, not a feature.

Fixed vs Adaptive Reasoning — When to Use Each

GPT 5.2 supports two modes, and your instructions should signal which one to use:

Use strict step-by-step instructions when:

  • The agent must follow a defined business process
  • Specific formatting rules or compliance templates are required
  • A fixed retrieval/reasoning sequence must be honored
  • Destructive operations need confirmation gates

Use goal-focused instructions with guardrails when:

  • Tools and knowledge sources are well-defined
  • The output format is flexible
  • The goal matters more than the exact path
  • You want the model to adaptively plan and handle edge cases

Key insight: You can mix both in the same instruction set. Use strict process for critical workflows (ticket creation, data modification) and goal-focused for open-ended tasks (information retrieval, summarization).

Output Style Profiles

GPT 5.2 has 8 built-in output profiles. Instead of writing verbose tone instructions, reference the profile directly:

| Profile | Behavior | |---------|----------| | Default | Verbose, explanatory, teacher-like | | Professional | Neutral, structured, business-oriented | | Friendly | Conversational, supportive | | Candid | Direct, concise | | Quirky | Expressive, informal | | Efficient | Minimal verbosity, outcome-focused | | Nerdy | Technical, detail-oriented, precise | | Cynical | Skeptical, dry, matter-of-fact |

Anti-pattern: Writing 5+ lines about tone ("Be professional but approachable, don't be too formal, use simple language..."). Fix: Tone: Professional — one line is enough. The model maps this to the built-in profile.


The Core Problem: Output-Focused vs Process-Focused Instructions

Most instruction failures share a single root cause: the instructions describe what the response should look like, not how the agent should produce it.

Output-focused (❌ anti-pattern)

Tells the model the shape of the answer — tone, format, length, style — but gives it no strategy for finding the answer.

You are a helpful HR assistant. Provide accurate answers about company policies.
Include policy numbers when available. Be concise and professional. Use bullet points.
Format responses with headers when appropriate.

Why this fails:

  • The model has no idea WHERE to look (SharePoint? Email? Web search?)
  • It doesn't know WHEN to use which capability
  • It will hallucinate policy numbers because you told it to "include" them but didn't tell it where to find them
  • Every response will have the same shape regardless of the question

Process-focused (✅ correct pattern)

Tells the model the decision logic — WHEN to use which tool, in what order, and what to do when things fail. Does NOT duplicate tool descriptions or parameters already in the plugin metadata.

# OBJECTIVE
Help employees find answers to HR policy questions using the company's official policy documents.

# DECISION LOGIC
- Policy/process questions → search **HR Policies** (SharePoint) first. This is the primary source.
- Org/people questions → use People knowledge directly.
- Email → search user's email ONLY when the user mentions a specific HR email or announcement.
- If the answer isn't in any source → direct users to [email protected]. Do not guess.

# WORKFLOW

## Step 1: Classify the question
- **Goal:** Determine if this is a policy lookup, a process question, or an org question.
- **Action:** Read the user's message. Identify the topic (benefits, time off, expenses, etc.).
- **Transition:** If policy → Step 2. If org/people → use People knowledge directly. If unclear → ask one clarifying question.

## Step 2: Search policy documents
- **Goal:** Find the authoritative answer in SharePoint.
- **Action:** Search the HR Policies library for documents matching the topic. Read the relevant sections.
- **Transition:** If found → Step 3. If not found → tell the user: "I couldn't find a policy on [topic]. Contact [email protected] for help."

## Step 3: Respond with citation
- **Goal:** Give a clear, traceable answer.
- **Action:** Summarize the policy in 2-4 bullets. Include the document name and section. If the policy references a form or process, link to it.
- **Constraint:** Never paraphrase in a way that changes the policy's meaning. If the policy is ambiguous, quote it directly and note the ambiguity.

# RESPONSE RULES
- Cite the source document for every factual claim.
- If you cannot find the answer, say so. Do not guess.
- One clarifying question at a time, only when needed.

Why this works:

  • Every data source has a clear role and intent (WHEN and WHY to use it)
  • The model has a decision tree, not just a personality description
  • Failure cases are handled ("if not found → tell the user")
  • The response rules are minimal and complementary to the process, not a substitute for it

Diagnostic Checklist

Run this checklist against any set of instructions. Each failed check is a specific, fixable problem.

A. Capability Coverage

| # | Check | How to verify | Failure signal | |---|-------|---------------|----------------| | A1 | Every configured capability has clear intent coverage in instructions | For each capability in capabilities[], check whether the instructions describe when and why the agent should use the underlying data source — e.g., "search company documents" covers OneDriveAndSharePoint even without naming it. The exact capability name is NOT required; what matters is that the instructions give the model a clear reason and context to invoke it. | Capability is configured but instructions provide no context for when to use it → model may underuse it or use it at the wrong time | | A2 | Every action/plugin has a matching section in instructions | Compare actions[] array against instruction text. Unlike built-in capabilities, plugins are custom and SHOULD be referenced by name so the model knows they exist. | Plugin exists but instructions don't reference it → model may never invoke it | | A3 | Each data source or action has a WHEN clause | Look for conditional intent: "when the user asks about...", "for X questions, search Y", "use [data source] for [scenario]". For built-in capabilities, the WHEN clause can reference the data source by purpose ("search internal docs") rather than by capability name. For plugins, reference functions by name. | Instructions mention a data source but provide no trigger or decision logic for when to use it | | A4 | Instructions provide decision logic, not tool descriptions | Check that instructions don't duplicate description_for_model, parameter lists, or schemas from plugin metadata | Token waste — this information is already available to the orchestrator | | A5 | Instructions don't assume data sources that aren't configured | Read instruction text for intent that implies a specific capability (see Capability Reference below). Cross-check against capabilities[] in the manifest. Focus on intent mismatch — e.g., instructions say "check the user's calendar" but no Meetings capability is configured. Minor phrasing overlaps (e.g., "look up" could mean many things) should NOT be flagged. | Instructions clearly direct the agent to use a data source that isn't configured → the agent will try and fail, or hallucinate |

B. Process Structure

| # | Check | How to verify | Failure signal | |---|-------|---------------|----------------| | B1 | Instructions contain at least one workflow or decision tree | Look for steps, numbered sequences, or if/then rules | Instructions are a flat list of personality traits — model has no strategy | | B2 | Workflows have Goal → Action → Transition per step | Each step names what it achieves, what to do, and when to move on | Steps are vague or lack transitions → model gets stuck or skips ahead | | B3 | Decision points have explicit if/then rules | Ambiguous situations have defined behavior | Model guesses instead of following a prescribed path | | B4 | Failure cases are handled | "If not found", "if unclear", "if error" have defined responses | Model hallucinates or goes silent when things don't go as expected |

C. Anti-Pattern Detection

| # | Anti-pattern | What it looks like | Fix | |---|---|---|---| | C1 | Output-only instructions | 80%+ of text is about tone, format, length, style | Add a CAPABILITIES section and at least one WORKFLOW | | C2 | Personality-first instructions | Opens with "You are a friendly, helpful..." and stays there | Move personality to a short RESPONSE RULES section at the end; lead with OBJECTIVE and CAPABILITIES | | C3 | Capability gap | declarativeAgent.json has 3 capabilities and 2 plugins; instructions provide intent coverage for only 1 | Add decision logic for each uncovered data source — describe WHEN and WHY the agent should use it (exact capability names are not required for built-in capabilities) | | C4 | Orphaned starters | Conversation starter references a capability not mentioned in instructions | Either add the capability to instructions or remove the starter | | C5 | Tool ambiguity | Instructions say "search for documents" but the agent has multiple document sources and no guidance on which to prefer | Clarify the intent: "Search the HR Policies library first; if not found, try the Company Wiki" | | C6 | Hallucination invitation | "Include [specific data] in your response" without specifying where to find it | Add: "Retrieve [data] from [capability]. If not found, do not include it." | | C7 | Compound tasks | "Extract metrics and summarize findings and create a report" | Break into separate atomic steps with transitions | | C8 | Over-restriction | Long list of "do NOT" rules with few "DO" rules | Rewrite as positive directives; keep restrictions to genuine guardrails only | | C9 | Missing reasoning calibration | No indication of how deep the model should think | Add a reasoning header: "Short answer only" or "Break the problem into steps" depending on task complexity | | C10 | No self-evaluation | Instructions end without a verification step | Add: "Before responding, confirm: [checklist]" | | C11 | Tool/parameter dumping | Instructions list tool names with descriptions and parameters already in plugin metadata | Remove tool descriptions and parameters from instructions. Keep only WHEN/chaining/failure logic. Reclaim token budget for decision logic. |

D. GPT 5.2 Model-Sensitivity Anti-Patterns

These anti-patterns are specifically caused or amplified by the GPT 5.1+/5.2 intent-first behavior. They may not have caused issues on GPT 5.0 but will cause problems now.

| # | Anti-pattern | What it looks like | Fix | |---|---|---|---| | D1 | Fused/ambiguous tasks | Single instruction with multiple actions: "extract metrics and summarize" | GPT 5.2 may merge steps or infer unintended processes. Split into atomic steps with explicit transitions. | | D2 | Incorrect numbering | Numbered lists used for parallel tasks that have no required order | GPT 5.2 treats numbering as a strict sequence signal. Use bullets (-) for parallel tasks; reserve numbering for true sequential workflows. | | D3 | Implicit formats | No explicit tone, structure, or verbosity specified | GPT 5.2 will infer these and may produce inconsistent results. Specify the output profile (Tone: Professional) and format explicitly. | | D4 | Weak Markdown hierarchy | Mixed list types, unclear headers, inconsistent nesting | GPT 5.2 uses structure as a control signal. Clean up: ## for sections, - for parallel items, Step N: for sequences. | | D5 | No validation step | Instructions end without a self-check gate | GPT 5.2 may choose faster reasoning and return incomplete output. Add: "Before finalizing, confirm: [checklist]" | | D6 | Verbose tone instructions | 5+ lines describing desired tone and style | Replace with a single output profile reference: Tone: Professional or Tone: Efficient. GPT 5.2 maps these to built-in profiles. | | D7 | Vague verbs | "Verify", "process", "handle", "clean" without specifying observable actions | Replace with precise verbs: "search", "compare", "list", "call [function]", "ask the user for" | | D8 | Missing stabilizing header | Agent that previously worked on GPT 5.0 now shows drift (reordered steps, added reasoning, tone changes) | Add a literal-execution header at the top as an interim fix (see Stabilizing Header section below) |

E. API Plugin Instruction Anti-Patterns

These apply specifically to agents with API plugins (actions).

| # | Anti-pattern | What it looks like | Fix | |---|---|---|---| | E1 | No function-level WHEN clauses | Instructions mention the plugin but don't say when to call each function | List every function with a WHEN clause: "getRepairs — use when user asks to find or list repairs" | | E2 | No chaining instructions | Agent has multiple plugins or plugin + capability but no guidance on combining them | Add chaining rules: "After calling getWeather, use the result to call createTask with the temperature in the title" | | E3 | No multi-turn collection | Function requires 3+ parameters but instructions don't say to collect them before calling | Add: "Before calling createRepair, collect title, description, and assignee. Ask for missing values." | | E4 | Missing confirmation for writes | POST/PATCH/DELETE functions have no confirmation gate in instructions | Add: "Before calling deleteRepair, confirm: 'Are you sure you want to delete repair #[id]?'" | | E5 | Negative/contrasting instructions | "Don't call getWeather for indoor temperatures" instead of defining valid cases | Rewrite as positive: "Call getWeather only for outdoor weather queries with a location." | | E6 | No cross-capability chaining | Agent has SharePoint knowledge + API plugin but instructions treat them as isolated | Add chaining: "Search SharePoint for project statuses, then call createTask for each project needing follow-up" |


Capability Reference (v1.6)

Use this table to understand what each built-in capability provides and to detect intent mismatches between instructions and the manifest. This is a guide for understanding intent, not a keyword checklist.

⚠️ IMPORTANT: M365 Copilot uses internal names for built-in capabilities that differ from the manifest identifiers (e.g., OneDriveAndSharePoint). The orchestrator already knows which capabilities are configured — instructions do NOT need to use the exact capability name. What matters is that the instructions convey clear intent for when and why the agent should access each data source. For example, "search our internal HR documents" is sufficient coverage for OneDriveAndSharePoint — you don't need to write "use the OneDriveAndSharePoint capability."

| Capability name | What it provides | Instruction intent that implies this capability | |----------------|-------------|--------------------------------------------------| | WebSearch | Search the web for grounding | "search the web", "look online", "find on the internet", "web results", "current news" | | OneDriveAndSharePoint | Search SharePoint sites, OneDrive files, document libraries | "SharePoint", "OneDrive", "documents", "files", "shared files", "document library", "site" | | GraphConnectors | Search Copilot connectors (external data sources) | "Jira", "ServiceNow", "connector", "external system", "tickets", connector-specific names | | GraphicArt | Generate images from text | "create image", "generate art", "draw", "illustration", "visual" | | CodeInterpreter | Run Python code for analysis, math, visualizations | "calculate", "analyze data", "run code", "chart", "graph", "visualization", "Excel analysis" | | Dataverse | Search Dataverse tables | "Dataverse", "CRM", "Dynamics", "Power Platform data", "business data" | | TeamsMessages | Search Teams channels, chats, meeting chats (messages only — NOT transcripts) | "Teams", "channels", "chat", "messages", "Teams messages", "mentions", "DMs" | | Email | Search user's email (and shared/group mailboxes) | "email", "inbox", "messages", "mail", "sent items", "flagged", "unread" | | People | Search people in the organization | "people", "org chart", "who is", "manager", "reports to", "birthday", "OOO", "colleagues" | | ScenarioModels | Use task-specific AI models | "model", "custom model", "specialized model" | | Meetings | Search calendar events, meeting details, and meeting transcripts | "meetings", "calendar", "events", "schedule", "invites", "attendees", "join link", "transcript", "what was discussed", "meeting notes", "recording" | | EmbeddedKnowledge | Use files bundled in the app package | "embedded files", "local files", "bundled docs" (not yet available) |

How to use this table: During Phase 2 (Comprehension Check) and Phase 3 (Diagnose), use this table to understand intent alignment — not for strict keyword matching. For A1: if a capability is in the manifest but the instructions never describe a scenario where the agent would use that data source (even in general terms), flag it as a gap — but do NOT require the exact capability name. For A5: if the instructions clearly direct the agent to access a data source that has no corresponding capability configured, flag it as an intent mismatch. Ambiguous phrasing that could apply to multiple capabilities should NOT be flagged.

Advanced capability configuration: Some capabilities support scoping (e.g. OneDriveAndSharePoint with items_by_url, Email with shared_mailbox and folders, TeamsMessages with specific channel URLs, Meetings with items_by_id, People with include_related_content). When reviewing instructions, also check whether scoping in the manifest aligns with what the instructions describe — e.g. instructions say "search all SharePoint" but the capability is scoped to a single site.

Version-Capability Matrix

Use this table during Phase 1 step 7 to check if the agent's schema version supports the capabilities its instructions imply.

| Capability | Minimum version | What it unlocks | |------------|----------------|------------------| | WebSearch | v1.0 | Web search for grounding | | OneDriveAndSharePoint | v1.0 | SharePoint/OneDrive file search | | GraphConnectors | v1.0 | External data via Copilot connectors | | GraphicArt | v1.0 | Image generation from text | | CodeInterpreter | v1.0 | Python code execution, data analysis, charts | | Dataverse | v1.3 | CRM/Dynamics/Power Platform table search | | TeamsMessages |