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 · 24000

v1.3 | Teams channel posts, DMs, meeting chat messages (NOT transcripts) | | Email | v1.3 | Email search (inbox, shared mailboxes, group mailboxes) | | People | v1.3 | Org chart, people search, OOO, birthdays | | ScenarioModels | v1.4 | Task-specific AI models | | behavior_overrides | v1.4 | discourage_model_knowledge, suggestions toggle | | disclaimer | v1.4 | Disclaimer text at conversation start | | Meetings | v1.5 | Calendar events, attendees, meeting transcripts, recordings | | sensitivity_label | v1.6 | Purview sensitivity labels (with embedded files) | | worker_agents | v1.6 | Connected agents (delegate to other declarative agents) | | EmbeddedKnowledge | v1.6 | Local files bundled in app package (not yet available) | | user_overrides | v1.6 | Let users toggle capabilities on/off | | People.include_related_content | v1.6 | Include related docs, emails, and Teams messages for people searches | | Email.group_mailboxes | v1.6 | Search Microsoft 365 Group mailboxes | | Meetings.items_by_id | v1.6 | Scope to specific meetings/series |

How to use: If the agent is on v1.4 and the instructions reference "meeting transcripts" or "calendar events", flag that Meetings requires v1.5+. If the instructions reference "people and what we have in common", flag that People.include_related_content requires v1.6. Always offer to upgrade — never silently change the version.


Review Workflow

When reviewing instructions, follow this sequence:

Phase 1: Inventory

  1. Read declarativeAgent.json — list all capabilities, actions, conversation starters, and the schema version
  2. Read instructions.txt (or inline instructions) — note the structure (or lack of it)
  3. Measure instruction length — count the characters in instructions.txt. If inline, count the instructions field value. Record the count against the 8,000-character limit. If over → flag immediately as a blocking issue.
  4. If API plugins exist, read the ai-plugin.json to understand what functions are available and their parameter requirements
  5. If MCP plugins exist, read the plugin manifest to understand what tools are available
  6. Check the version field — note which GPT model era the instructions were likely written for
  7. Version upgrade analysis — Cross-reference the current schema version against the capabilities implied by the instructions (use the Version-Capability Matrix below). If the instructions describe functionality that requires a newer schema version, flag it. Example: instructions say "review meeting transcripts" but the agent is on v1.4 — Meetings capability (which includes transcripts) requires v1.5+.

Quick length check: wc -m appPackage/instructions.txt (Unix/macOS/WSL) or (Get-Content appPackage/instructions.txt -Raw).Length (PowerShell)

Phase 2: Comprehension Check

Before running any diagnostic, explain back to the user what you understood from reading all the files in Phase 1. This surfaces misunderstandings early and gives the user a chance to provide domain context you lack.

Present your understanding in this structure:

## Here's what I understood about your agent

**Purpose:** [One sentence — what this agent is for and who uses it]

**Workflow:** [Summarize the decision process the instructions describe — what does the agent do first, when does it use which capability, what are the branching conditions?]

**Capabilities used:**
- [Capability 1] — used for [what scenario]
- [Capability 2] — used for [what scenario]
- [Any configured capability NOT mentioned in instructions — flag it]

**Capability alignment:**
| Capability | In manifest? | In instructions? | Gap |
|------------|-------------|-----------------|-----|
| [For each configured capability] | ✅ | ✅ or ❌ | [If ❌: instructions never reference this — model won't know when to use it] |
| [For each capability implied by instructions but NOT configured] | ❌ | ✅ | [Instructions assume this exists but it's not configured — will fail or hallucinate] |

**Version upgrade opportunities:**
- [If the current schema version is not the latest (v1.6), list capabilities available in newer versions that could benefit this agent's intent. Example: "You're on v1.4. Upgrading to v1.5 would unlock `Meetings` (calendar + transcripts), which aligns with your instruction's references to meeting prep and scheduling."]
- [If already on v1.6: "✅ You're on the latest schema version — no upgrade needed."]

**Tone / personality:** [What personality or communication style the instructions establish, if any]

**Gaps or things I'm unsure about:**
- [Anything ambiguous, unclear, or that seems to be missing context]
- [Domain-specific terms or processes you don't fully understand]

Then ask:

Does this match your intent? Is there anything I'm missing or misunderstanding about how this agent should work?

Wait for the user's response before proceeding to Phase 3. The user's clarifications become additional context for the diagnostic — they may reveal that something you'd flag as a "gap" is intentional, or surface requirements that aren't written anywhere.

Shortcut: For proactive reviews triggered from the editing workflow (where the user didn't ask for a review), you may combine Phase 2 into a brief confirmation: "I see this agent is designed to [purpose]. The instructions cover [X, Y] but don't mention [Z capability]. Does that sound right?" — then proceed.

Phase 3: Diagnose

Run the full Diagnostic Checklist — sections A (Capability Coverage), B (Process Structure), C (Anti-Patterns), D (GPT 5.2 Model Sensitivity), and E (API Plugin patterns, if applicable). Record every failed check.

For rapid assessment or when reviewing multiple agents, use the Structured Evaluation Prompt (see section below) — paste the current instructions into the template and run the automated checks. The eval prompt covers all checklist sections in a single pass.

When scoring issues, factor in the user's clarifications from Phase 2 — if they confirmed a gap is intentional, downgrade or skip that check.

Phase 4: Report

Present findings to the user in this format:

## Instruction Review

**Instruction length:** [X] / 8,000 characters [✅ within limit | ⚠️ close (>6,500) | ❌ over limit]

### What's working
- [List things that are correctly structured]

### Issues found
| # | Issue | Severity | Description |
|---|-------|----------|-------------|
| 1 | C1 — Output-only | High | Instructions describe response format but have no workflow for finding answers |
| 2 | A1 — Intent gap | Medium | Email capability is configured but instructions never describe when the agent should search email — no decision logic for this data source |
| 3 | C11 — Token waste | Medium | Tool descriptions duplicated from plugin metadata — reclaim ~800 chars |
| 4 | C6 — Hallucination risk | Medium | "Include policy numbers" but no instruction on where to find them |

### Recommended structure
[Show the proposed skeleton with sections mapped to their capabilities]

### Token budget impact
[If rewrite is needed, estimate: current length → projected length after fix]

Phase 5: Rewrite (only after user confirms)

Follow Detect → Inform → Ask — the same protocol used for JSON errors. Present the diagnosis, propose the fix, wait for approval before rewriting.

When rewriting:

  • Preserve any existing content that passes the checklist
  • Incorporate the domain context and clarifications gathered in Phase 2 — use the user's own terminology and process descriptions
  • Do NOT invent domain-specific content (policy names, SharePoint URLs, process details) — ask the user
  • Structure using the process-focused pattern: OBJECTIVE → DECISION LOGIC → WORKFLOW → FAILURE HANDLING → RESPONSE RULES → SELF-CHECK
  • Ensure every configured capability has clear intent coverage in the instructions with WHEN clauses and chaining rules — built-in capabilities don't need exact names, but actions/plugins should be named
  • Do NOT add tool descriptions or parameters — these are already in plugin metadata
  • Measure the result — verify the rewritten instructions are within 8,000 characters. If over, cut in this priority order:
    1. Remove any remaining tool descriptions/parameter lists (C11)
    2. Replace verbose tone blocks with a single output profile reference (D6)
    3. Consolidate redundant workflow steps
    4. If still over, ask the user what to prioritize

Before/After Examples

Example 1: Knowledge Base Agent

Capabilities configured: OneDriveAndSharePoint (scoped to /sites/IT-KB/Documents), WebSearch (scoped to docs.contoso.com)

❌ Before (output-focused):

You are an IT knowledge base assistant. Help users find answers to technical questions.
Be thorough but concise. Use bullet points when listing steps. Always be professional
and patient. If you don't know the answer, say so politely.

Issues: C1 (output-only), A1 (two capabilities configured, zero intent coverage — instructions don't describe when to use any data source), C5 (tool ambiguity — "find answers" doesn't say where), C6 (no sourcing strategy)

✅ After (process-focused — decision logic only, no tool descriptions):

# OBJECTIVE
Help employees resolve IT questions by searching internal documentation and company-approved external resources.

# DECISION LOGIC
- Always search the **IT Knowledge Base** (SharePoint) first — this is the primary source.
- If not found in the KB → search **docs.contoso.com** as a secondary source.
- If not found in either → escalate: "Please submit a ticket to [email protected] or the ServiceNow portal."

# WORKFLOW

## Step 1: Understand the question
- **Goal:** Identify what the user needs help with.
- **Action:** If the question is clear, proceed. If vague (e.g., "it's not working"), ask ONE clarifying question: what system, what error, what they were trying to do.
- **Transition:** Once clear → Step 2.

## Step 2: Search
- **Goal:** Find the answer in internal documentation.
- **Action:** Search IT-KB. If not found, search docs.contoso.com.
- **Transition:** If found → Step 3. If not found in either → escalate.

## Step 3: Respond
- **Action:** Summarize the solution in numbered steps. Cite the source document name.
- **Constraint:** Do not combine information from multiple documents without noting it.

# RESPONSE RULES
Tone: Professional
- Cite the source for every answer.
- One clarifying question at a time.
- If multiple solutions exist, present the simplest first.

Example 2: Agent with API Plugin

Capabilities configured: Email, API plugin (Repairs API with GET/POST/PATCH/DELETE)

❌ Before (output-focused):

You help manage repair tickets and can access email. Be helpful and professional.
When showing repairs, display them in a clear format with the ticket ID, title,
status, and assignee. For new tickets, confirm the details before creating them.

Issues: C1 (output-only), A2 (Repairs API not explained), C5 ("can access email" — when? for what?), B3 (no decision rules for CREATE vs SEARCH vs UPDATE), E1 (no function-level WHEN clauses), E3 (no multi-turn collection), E4 (no confirmation for destructive ops)

✅ After (process-focused — decision logic only, no tool descriptions):

# OBJECTIVE
Help users search, create, and manage repair tickets. Use email context when relevant to a repair.

# DECISION LOGIC
- When user asks to find repairs → search by keyword or ID. If no results, offer to create one.
- When user reports a new issue → collect title, description, and assignee first. Confirm details before creating.
- When user asks to update a repair → identify the ticket first (by ID or search), confirm what to change, then update.
- When user asks to delete → identify the ticket, **always confirm before deleting**.
- Use **Email** ONLY when: (a) the user mentions an email about a repair, or (b) you need a reference number from prior correspondence.

# FAILURE HANDLING
- No results from search → ask user to rephrase or offer to create a new ticket.
- User provides incomplete info for creation → ask for missing values one at a time.
- Ambiguous intent (search vs create) → ask: "Would you like me to search for an existing repair or create a new one?"

# RESPONSE RULES
Tone: Professional
- Always show the ticket ID when referencing a repair.
- Confirm before any destructive operation.

Example 3: MCP Server Agent

Capabilities configured: MCP plugin (Microsoft Docs with docs_search tool)

❌ Before (output-focused):

You are a documentation search assistant. Help users find relevant Microsoft
documentation. Provide clear, well-organized responses. Include links when available.
Summarize key points from the documentation you find.

Issues: C1 (output-only), A2 (MCP tool not referenced), C6 ("include links when available" — where do they come from?), C9 (no reasoning calibration), D3 (no explicit tone/format — GPT 5.2 will infer inconsistently), D5 (no validation step)

✅ After (process-focused — decision logic only, no tool descriptions):

# OBJECTIVE
Help users find and understand official Microsoft documentation.

# DECISION LOGIC
- For factual questions → search docs, summarize the most relevant result with title and link.
- For comparisons ("X vs Y") → search for each topic separately, present side-by-side citing both.
- For troubleshooting ("error Z") → search with the error message first, then by product + "known issues" if no match.
- If no results after two searches → tell the user: "I couldn't find official documentation. Try browsing https://learn.microsoft.com directly."

# GROUNDING RULES
- Never answer from general knowledge — always search first.
- Cite the source document for every claim.
- Do not stitch information across documents without noting it.

# RESPONSE RULES
Tone: Efficient
Reasoning: Short answer for simple lookups. Break into steps for troubleshooting.

# SELF-CHECK
Before responding: confirm you searched, cited a source, and answered the actual question asked.

Stabilizing Header — Interim Fix for Model Drift

If an agent that worked on GPT 5.0 shows unexpected behavior on GPT 5.2 (reordered steps, added reasoning, tone drift, merged tasks), add this header at the top of instructions.txt as an immediate stabilization:

Always interpret instructions literally.
Never infer intent or fill in missing steps.
Never add context, recommendations, or assumptions.
Follow step order exactly with no optimization.
Respond concisely and only in the requested format.
Do not call tools unless a step explicitly instructs you to do so.

This is a temporary fix, not a long-term solution. Use it to stabilize behavior while you rewrite the instructions using the process-focused structure from this guide. Once the instructions are properly structured with explicit workflows, remove the header — well-structured instructions don't need it, and the header prevents GPT 5.2 from using its adaptive reasoning which can be beneficial for open-ended tasks.

Reference: Pattern 8 — Literal-execution header


Structured Evaluation Prompt

For rapid auditing of existing instructions — especially when migrating from GPT 5.0 to 5.2 or reviewing multiple agents at scale — use this structured evaluation prompt. Paste the agent's current instructions into the <instructions> block and run the analysis:

You are reviewing declarative agent instructions for GPT 5.2 stability.

INPUT
<instructions>
[PASTE CURRENT INSTRUCTIONS]
</instructions>

TASK
Concise audit. Identify ONLY issues and exact fixes.

CHECKS
- Step order: identify ambiguity, missing steps, or merged steps → propose atomic, numbered steps.
- Tool use: identify auto-calls, retries, or tool switching → add "use only in step X; no auto-retry".
- Grounding: detect inference, blending, or citation gaps → add "cite only retrieved; no inference; no cross-document stitching".
- Missing-data handling: if retrieval is empty or conflicting → add "stop and ask the user".
- Verbosity: identify chatty or explanatory output → replace with "return only the requested data/format".
- Contradictions or duplicates: resolve discrepancies; prefer explicit over implied.
- Vague verbs ("verify", "process", "handle", "clean"): replace with precise, observable actions.
- Safety: prohibit step reordering, optimization, or reinterpretation.
- Reasoning calibration: match reasoning depth to task type (fast extraction vs deep analysis).
- API plugin functions: verify each function has a WHEN clause, multi-turn parameter collection, and confirmation gates for writes.

OUTPUT (concise)
- Header patch (3–6 lines) — stabilizing header if needed
- Top 5 changes (bullet list: "Issue → Fix")
- Example rewrite (≤10 lines) for the riskiest step

Reference: Pattern 9 — Evaluate and migrate existing instructions


API Plugin Chaining Patterns

When an agent has API plugins, instructions must cover how functions chain together. Missing chaining instructions cause the agent to treat each function as isolated, forcing the user to manually bridge between calls.

Pattern: Output-as-Input Chaining

Use the result of one API call as input for another:

To get the weather, always use the `getWeather` action, then create a task with
the title "temperature in [location]: [temperature]" by calling `createTask`.

Pattern: Conversation-History Chaining

Use prior responses to handle follow-up actions:

1. When the user asks to list all to-dos, call `getTasks` to retrieve the list with title and ID.
2. After listing, if the user asks to delete a to-do by name, use the ID from the previous response to call `deleteTask`.

Pattern: Cross-Capability Chaining (SharePoint + API)

Combine knowledge sources with API actions:

- To get project statuses, use SharePoint knowledge from **ProjectDeadlines**.
- Always create a to-do for each project using the status update for the title by calling `createTask`.

Pattern: Capability + Code Interpreter Chaining

Process API output with code interpreter:

When the user asks to list all to-dos, call `getTasks` to retrieve the list,
then use code interpreter to generate a chart based on the output.

Pattern: Multi-Turn Parameter Collection

When a function requires multiple parameters, instruct the agent to collect all values before calling:

If the user asks about the weather:
1. Ask the user for location.
2. Ask the user for forecast day.
3. Ask the user for unit system (Metric or Imperial).
4. Only call `getWeather` when you have all three values.

Anti-pattern: Letting the agent call the function with partial parameters and handle errors — this produces a poor user experience.


Domain Vocabulary

Define specialized terms, formulas, acronyms, and dataset-specific language in a dedicated section. This prevents GPT 5.2 from incorrectly inferring definitions.

# VOCABULARY
- **ROI** — Return on Investment. Calculate as: (Benefit - Cost) / Cost. Do not use any other formula.
- **SLA** — Service Level Agreement. In this context, refers to the 4-hour response time commitment.
- **P1/P2/P3** — Priority levels. P1 = production down, P2 = degraded, P3 = cosmetic/minor.
- **CSAT** — Customer Satisfaction score, on a 1-5 scale. Do not invent definitions; use only these.

Minimum Quality Bar

Instructions pass the quality bar when ALL of these are true:

  1. Every configured capability has clear intent coverage in the instructions — the instructions describe when and why the agent should use each data source. Built-in capabilities do NOT need to be referenced by their exact manifest name (M365 Copilot uses internal names); what matters is clear decision logic. Actions/plugins SHOULD be referenced by name.
  2. At least one workflow exists with Goal → Action → Transition (or equivalent decision rules)
  3. Failure cases are handled — the instructions say what to do when a search returns nothing, a tool fails, or the user's question is ambiguous
  4. Output-focused content is ≤20% of the total — tone, format, and style rules exist but don't dominate
  5. No hallucination invitations — every "include X" statement has a corresponding "retrieve X from Y" instruction
  6. No tool/parameter duplication — instructions contain decision logic only; tool descriptions, parameters, and schemas live in plugin metadata
  7. Within the 8,000-character limit — if instructions exceed this, cut tool descriptions first, then consolidate verbose workflows
  8. Reasoning depth is calibrated — fast extraction tasks say "short answer only"; analysis tasks say "break the problem into steps"
  9. Markdown structure is clean — sections use ##, parallel tasks use bullets, sequential workflows use numbered steps; no mixed list types
  10. API plugin functions have WHEN clauses, chaining rules, and confirmation gates (if applicable)
  11. A self-evaluation gate exists — instructions end with "Before responding, confirm: [checklist]"
  12. No GPT 5.2 model-sensitivity anti-patterns — no fused tasks, no incorrect numbering, no vague verbs, no verbose tone blocks

If any of these fail, the instructions need improvement before deployment.