int-patterns

A shelf of worked solutions to the problems Copilot Studio builders keep running into, each one with the file you copy in to fix it.

WHEN TO USE

SCOPE

USE FOR

Spell out in-house acronyms before the bot goes looking for an answer.
Detect which channel a user is on and change behavior for Teams versus web chat.
Stop the bot's internal workings leaking into what the person actually sees.
Say something kind when the safety filter blocks a reply, instead of an error code.
Make a tool fire every time for a request the AI otherwise keeps skipping over.

NOT FOR

Not for general YAML schema reference — that's the int-reference skill.
Not for the mechanics of creating a new topic — that's the new-topic skill.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (4)

Copilot Studio Pattern Library

Only read the pattern file relevant to the current task — do NOT read all files.

How to use patterns

Patterns are recommendations, not requirements. How you present them depends on your role:

If you are the Advisor agent:

Present each pattern as a suggestion — explain the challenge it solves and why it's relevant
Use status-appropriate language:
- proven: "This is a proven pattern used in production — consider it for…"
- recommended: "A recommended approach that works well — consider it for…"
- experimental: "This is an experimental approach, not yet fully validated — you may want to test thoroughly before adopting"
Always say "you could consider…" or "a common approach is…", never "you must…"
Let the user decide — do NOT auto-apply patterns without confirmation

If you are the Author agent:

When implementing a pattern the user or Advisor has already chosen, read the relevant pattern file for the correct YAML structure
Do NOT suggest patterns yourself — that is the Advisor's role
Use the YAML examples as reference for the correct kinds, fields, and structure

Pattern Index

JIT Glossary → jit-glossary.md

Loads customer-specific acronyms into a global variable on first message so the orchestrator can expand them before searching knowledge sources.

Read this pattern when:

The user wants to add a glossary, acronym list, or terminology table
Knowledge search quality is poor because the agent doesn't understand internal abbreviations
The user asks about loading CSV/text data into a variable at conversation start

JIT User Context → jit-user-context.md

Loads the current user's M365 profile (country, department) into global variables for personalized answers.

Read this pattern when:

The user wants country-aware, department-aware, or role-aware answers
The agent needs to call the M365 Users connector
The user asks about personalizing responses based on who is chatting

Dynamic Topic Redirect → dynamic-topic-redirect.md

Uses a Switch expression inside a BeginDialog node to route to different topics based on a variable.

Read this pattern when:

The user needs to route to one of several topics based on a variable
The user wants to replace nested ConditionGroup nodes with a cleaner approach
The user asks about dynamic topic redirects or Switch expressions

Prevent Child Agent Responses → prevent-child-agent-responses.md

Stops child agents from messaging users directly by instructing them to use output variables.

Read this pattern when:

The user wants a child agent to return data without messaging the user
The user is confused about the completion setting on a child agent
The parent agent needs to control all user-facing responses

Date Context → date-context.md

Injects the current date into agent instructions using Power Fx for accurate date-relative responses.

Read this pattern when:

Users ask date-relative questions ("What's next week?", "upcoming events")
The agent handles schedules, calendars, deadlines, or time-sensitive content
Date interpretation is causing confusion or hallucinations

Orchestrator-Generated Variables → orchestrator-variables.md

Uses AutomaticTaskInput to classify or extract structured data from the user's message at orchestration time — zero extra cost or latency.

Read this pattern when:

The user needs to route knowledge searches by category
The user wants to extract a classification without asking the user or using an AI Prompt
Knowledge search quality suffers because all sources are searched indiscriminately

Prevent Tool Call Leaks → prevent-tool-call-leaks.md

Stops the orchestrator from leaking internal reasoning and tool call metadata to the end user.

Read this pattern when:

Users report seeing raw JSON in agent responses
The agent has connector actions that the orchestrator invokes indirectly
Responses contain explanation_of_tool_call or similar internal metadata

Channel-Aware Behavior → channel-aware-behavior.md

Detects the host channel from System.Activity.ChannelId and gates behavior per surface (Teams, M365 Copilot, web chat, Direct Line, voice).

Read this pattern when:

A feature works on one channel but breaks on another (file upload, Adaptive Card variants, hyperlinks)
The user asks to detect Teams vs. M365 Copilot vs. web vs. voice
A naive =Lower(ChannelId) = "msteams" check is silently failing for msteams:Copilot or other compound channel IDs

RAI Error Handling → rai-error-handling.md

Classifies Azure OpenAI content-filter errors by subcode in the OnError topic and returns category-specific user messages with telemetry. Azure OpenAI models only — does not work with Anthropic or xAI models.

Read this pattern when:

The user needs industry-specific or empathetic error messages for RAI content-filter violations
The user wants category-specific handling (e.g., crisis resources for self-harm, security messaging for jailbreak attempts)
The user asks about OnError, ContentFiltered, Azure OpenAI content filters, or RAI subcodes

Line Breaks in Messages → line-breaks-in-messages.md

Uses <br /><br /> inside message and question nodes to render reliable paragraph spacing across channels.

Read this pattern when:

Users report that bot messages feel like walls of text
Multi-part questions or welcome messages need visual separation
The user asks about line breaks, <br />, or formatting in messages or questions

Knowledge Hold Message → knowledge-hold-message.md

Sends a randomized hold message during knowledge search so users know the agent is working.

Read this pattern when:

The agent has noticeable knowledge-search latency
Users are abandoning conversations or resending questions during delays
The user asks about OnKnowledgeRequested, typing indicators, or hold messages

Deterministic MCP Calls → deterministic-mcp-calls.md

Workarounds to improve MCP tool invocation reliability using instruction-based nudges or a dedicated child agent wrapper.

Read this pattern when:

An MCP tool must fire every time for a specific intent but the orchestrator skips it
The user asks about forcing MCP tool invocation or / syntax with MCP tools
The user needs deterministic tool calls for business-critical workflows

Chain of Thought Logging → chain-of-thought-logging.md

Sends high-level "Thinking" messages during multi-step orchestration to improve observability and perceived responsiveness.

Read this pattern when:

The agent uses multiple tools, MCP servers, or child agents that chain together
Users experience long silences during multi-step reasoning
The user wants a debug or observability trace of orchestrator behavior
The user asks about streaming, typing indicators, or progress messages for complex flows

Conversation History Variable → conversation-history-variable.md

Captures a best-effort conversation transcript into a variable for escalation, logging, and downstream automation.

Read this pattern when:

The user needs to capture conversation context for live-agent escalation
A downstream tool or connector requires conversation history as input
The user wants to log conversations to Dataverse, a ticketing system, or email

Teams Production Hardening → teams-production-hardening.md

Eight coordinated production patterns for Teams and M365 Copilot agents covering reinstalls, stale context, resets, diagnostics, and suggested prompts.

Read this pattern when:

The user is deploying or hardening a Copilot Studio agent on Microsoft Teams
Users report stale context after returning to a long-running Teams conversation
Context variables work on web chat but not in Microsoft 365 Copilot
The user wants richer OnError or Start Over experiences with diagnostic info
The user asks about OnInstallationUpdate, OnInactivity, OnSystemRedirect, suggested prompts, or Teams-specific behavior

Combining patterns

Multiple patterns can be combined in a single agent. Common combinations:

JIT Glossary + JIT User Context → merge into a single conversation-init OnActivity topic (template at templates/topics/conversation-init.topic.mcs.yml)
Date Context + JIT User Context → both go in agent instructions; date is a Power Fx expression, user context is a global variable reference
Orchestrator Variables + JIT User Context → classify by category AND personalize by country for precise knowledge routing
RAI Error Handling + Teams Production Hardening → handle RAI subcodes first in OnError, then fall through to the generic diagnostic card from Pattern 7
Knowledge Hold Message + Chain of Thought Logging → use hold messages for knowledge-heavy agents and CoT logging for multi-tool agents; both reduce perceived latency but solve different problems
Teams Production Hardening + JIT User Context → Pattern 4 sets Global.UserContext cross-channel; replace hard-coded values with the JIT User Context connector call for real profile data

This skill ships inside the Copilot Studio YAML Toolkit plugin. Listed package contents include 4 agents and hooks. Installed components and skill versions may vary by AI tool.

Install the whole plugin

This route installs the Copilot Studio YAML Toolkit plugin package selected for your AI tool.

Add Microsoft's marketplace, then install the plugin

Type both lines inside a Claude Code session, not at your shell prompt. They add Microsoft's marketplace, which is this repository, and the copilot-studio plugin, with its Copilot Studio skills and four sub-agents.

Install checklist

Microsoft lists Node.js 18 or later, and VS Code with the Copilot Studio extension for cloning, pushing and pulling agents.

/plugin marketplace add microsoft/skills-for-copilot-studio

/plugin install copilot-studio@skills-for-copilot-studio

Installation and loading

Claude Code installs it once you pick an install option.

Good to know

A hook that runs whenever a session starts adds Microsoft's Copilot Studio instructions; one tells Claude to lean towards reading your requests as Copilot Studio requests unless there are clear signs otherwise.
The option that installs it for you in every project brings the hook's instructions into every project; to keep them to one Copilot Studio repository, pick the option for this repo only.
On first run, and after an update that changes its dependencies, the session-start hook runs npm install in the plugin's data folder; every session it also writes ~/.copilot-studio-cli/plugin-paths.json.

Add Microsoft's marketplace, then install the plugin

Type both lines in an interactive GitHub Copilot CLI session, not at your shell prompt. The first adds Microsoft's marketplace, which is this repository; the second installs the copilot-studio plugin.

Install checklist

Microsoft lists Node.js 18 or later, and VS Code with the Copilot Studio extension for cloning, pushing and pulling agents.

/plugin marketplace add microsoft/skills-for-copilot-studio

/plugin install copilot-studio@skills-for-copilot-studio

Good to know

The plugin also carries a hooks/hooks.json file with SessionStart hooks, a path GitHub's plugin reference lists as a hooks file for plugins in this format; read the file in the repository before you install.

Open plugin page ↗

Install without the plugin (incomplete)

What's missing

Installing just this skill adds only its own folder. Its instructions also call for other plugin components, such as shared scripts, reference files or other skills, which aren't included. Installing the whole plugin avoids this gap.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add microsoft/skills-for-copilot-studio --skill "int-patterns" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

Copilot Studio Pattern Library

How to use patterns

Pattern Index

JIT Glossary → jit-glossary.md

JIT User Context → jit-user-context.md

Dynamic Topic Redirect → dynamic-topic-redirect.md

Prevent Child Agent Responses → prevent-child-agent-responses.md

Date Context → date-context.md

Orchestrator-Generated Variables → orchestrator-variables.md

Prevent Tool Call Leaks → prevent-tool-call-leaks.md

Channel-Aware Behavior → channel-aware-behavior.md

RAI Error Handling → rai-error-handling.md

Line Breaks in Messages → line-breaks-in-messages.md

Knowledge Hold Message → knowledge-hold-message.md

Deterministic MCP Calls → deterministic-mcp-calls.md

Chain of Thought Logging → chain-of-thought-logging.md

Conversation History Variable → conversation-history-variable.md

Teams Production Hardening → teams-production-hardening.md

Combining patterns

No requirements beyond installing this skill were found.

Install the whole plugin

Add Microsoft's marketplace, then install the plugin

Add Microsoft's marketplace, then install the plugin

More skills

add-action

add-adaptive-card

add-generative-answers

add-global-variable

add-knowledge

add-node