int-reference

The cheat sheet for writing Copilot Studio files by hand — every file type, trigger, built-in value, formula function and starter template gathered in one place.

WHEN TO USE

SCOPE

USE FOR

Settle whether the description or the example phrases is what actually routes a request.
Check which formula functions really work here before writing one that does not.
Find the right starter template for a topic, like error handling or disambiguation.
Get the exact quoting a SharePoint filter needs, which is easy to get wrong.

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 (9)

Copilot Studio YAML Reference

Core File Types

File	Purpose
`agent.mcs.yml`	Main agent metadata (kind: GptComponentMetadata)
`settings.mcs.yml`	Agent settings and configuration
`connectionreferences.mcs.yml`	Connector references
`topics/*.mcs.yml`	Conversation topics (kind: AdaptiveDialog)
`actions/*.mcs.yml`	Connector-based actions (kind: TaskDialog)
`knowledge/*.mcs.yml`	Knowledge sources (kind: KnowledgeSourceConfiguration)
`variables/*.mcs.yml`	Global variables (kind: GlobalVariableComponent)
`agents/*.mcs.yml`	Child agents (kind: AgentDialog)

Trigger Types

Topics with OnRecognizedIntent have two routing mechanisms — which one matters depends on the orchestration mode:

modelDescription — used by generative orchestration (GenerativeActionsEnabled: true). The AI orchestrator reads this to decide routing. Primary mechanism for generative agents.
Trigger phrases (triggerQueries) — used by classic orchestration. Pattern-matched against the user's utterance. Secondary hints when generative orchestration is enabled.

System triggers (OnConversationStart, OnUnknownIntent, OnError, etc.) fire automatically and don't use either mechanism.

Kind	Purpose
`OnRecognizedIntent`	Trigger phrases matched
`OnConversationStart`	Conversation begins
`OnUnknownIntent`	No topic matched (fallback)
`OnEscalate`	User requests human agent
`OnError`	Error handling
`OnSystemRedirect`	Triggered by redirect only
`OnSelectIntent`	Multiple topics matched (disambiguation)
`OnSignIn`	Authentication required
`OnToolSelected`	Child agent invocation
`OnKnowledgeRequested`	Custom knowledge source search triggered (YAML-only, no UI)
`OnGeneratedResponse`	Intercept AI-generated response before sending
`OnOutgoingMessage`	Non-functional (2026-03-15) — exists in schema but does not fire at runtime. Do not use.

YAML-Only Features

These features work at runtime but are not visible in the Copilot Studio UI. Warn users that UI edits may silently remove them.

Feature	Notes
`triggerCondition` on knowledge sources	The UI only exposes this as an on/off toggle (`=false` to exclude from `UniversalSearchTool`). Arbitrary Power Fx expressions (e.g., `=Global.UserDepartment = "HR"`) work at runtime but can only be set via YAML. Use with caution. (2026-03-16)

Action Types

Kind	Purpose
`SendActivity`	Send a message
`Question`	Ask user for input
`SetVariable`	Set/compute a variable (Power Fx expression, prefix `=`)
`SetTextVariable`	Set a text variable using template interpolation (`{}`). Useful for converting non-text types (e.g., Number) to text: `"You have {Topic.Count} items"`
`ConditionGroup`	Branching logic
`BeginDialog`	Call another topic
`ReplaceDialog`	Replace current topic
`EndDialog`	End current topic
`CancelAllDialogs`	Cancel all topics
`ClearAllVariables`	Clear variables
`SearchAndSummarizeContent`	Generative answers (grounded in knowledge)
`AnswerQuestionWithAI`	AI answer (conversation history + general knowledge only)
`EditTable`	Modify a collection
`CSATQuestion`	Customer satisfaction
`LogCustomTelemetryEvent`	Logging
`OAuthInput`	Sign-in prompt
`SearchKnowledgeSources`	Search knowledge sources (returns raw results, no AI summary)
`CreateSearchQuery`	AI-generated search query from user input

Connector Actions (TaskDialog)

Connector actions (kind: TaskDialog) invoke external connector operations. They are stored in actions/ and require a connection reference in connectionreferences.mcs.yml.

Use /add-action to create new actions from available connectors. The schema describes the structural properties of TaskDialog and InvokeConnectorTaskAction, but the specific inputs and outputs for each connector operation are connector-specific — use the connector lookup script (connector-lookup.bundle.js) to get the full operation details.

Action Structure

Field	Purpose
`kind: TaskDialog`	Identifies this as a connector action
`inputs`	Inputs: `AutomaticTaskInput` (AI-provided) or `ManualTaskInput` (fixed value)
`modelDisplayName`	Display name for AI orchestrator routing
`modelDescription`	Description for AI orchestrator routing
`outputs`	Output property names returned by the connector
`action.kind`	Always `InvokeConnectorTaskAction` for connector actions
`action.connectionReference`	Logical name of the connection (registered in `connectionreferences.mcs.yml`)
`action.connectionProperties.mode`	`Maker` (maker's credentials) or `Invoker` (end user's credentials)
`action.operationId`	The connector's specific operation identifier
`outputMode`	Usually `All` — exports all operation outputs

Input Types

Input Kind	Use When	Notes
`AutomaticTaskInput`	The AI orchestrator should provide the value based on context	Includes `description` for the AI to understand what to provide
`ManualTaskInput`	A fixed/hardcoded value (e.g., timezone, folder path)	Can only hardcode strings. Non-string values (IDs, enums) should be reviewed by the user after pushing

`$`-Prefixed Property Names (SharePoint, OData)

Some connectors (notably SharePoint) use OData parameters like $filter, $orderby, $top. These require special quoting in TaskDialog YAML — both single and double quotes:

# TaskDialog (actions/*.mcs.yml) — CORRECT
- kind: ManualTaskInput
  propertyName: "'$filter'"
  value: "Status eq 'Active'"

"'$filter'" means: the outer "" are YAML string delimiters; the inner '' are part of the literal value sent to the runtime. Using $filter, "$filter", or '$filter' alone will fail.

InvokeConnectorAction (inline in topics) uses a different format — the parameters/ prefix with no inner single quotes:

# InvokeConnectorAction (inside topics) — CORRECT
- kind: InvokeConnectorAction
  operationId: GetItems
  input:
    parameters/$filter: "Status eq 'Active'"

Never mix these two formats.

System Variables

Variable	Description
`System.Bot.Name`	Agent's name
`System.Activity.Text`	User's current message
`System.Conversation.Id`	Conversation identifier
`System.Conversation.InTestMode`	True if in test chat
`System.FallbackCount`	Number of consecutive fallbacks
`System.Error.Message`	Error message
`System.Error.Code`	Error code
`System.SignInReason`	Why sign-in was triggered
`System.Recognizer.IntentOptions`	Matched intents for disambiguation
`System.Recognizer.SelectedIntent`	User's selected intent
`System.SearchQuery`	AI-rewritten search query (available in `OnKnowledgeRequested`)
`System.KeywordSearchQuery`	Keyword version of search query (available in `OnKnowledgeRequested`)
`System.SearchResults`	Table to populate with custom search results — schema: Content, ContentLocation, Title (available in `OnKnowledgeRequested`)
`System.ContinueResponse`	Set to `false` in `OnGeneratedResponse` to suppress auto-send
`System.Response.FormattedText`	The AI-generated response text (available in `OnGeneratedResponse`)

Variable Scopes

Prefix	Scope	Lifetime
`Topic.<name>`	Topic variable	Current topic only
`Global.<name>`	Global variable	Entire conversation (defined in `variables/` folder)
`System.<name>`	System variable	Built-in, read-only

Global variables are defined as YAML files in variables/<Name>.mcs.yml (kind: GlobalVariableComponent). aIVisibility accepts UseInAIContext (orchestrator can read and reason about the value) or Hidden (orchestrator unaware — use for flags and internal bookkeeping).

Prebuilt Entities

Entity	Use Case
`BooleanPrebuiltEntity`	Yes/No questions
`NumberPrebuiltEntity`	Numeric inputs
`StringPrebuiltEntity`	Free text
`DateTimePrebuiltEntity`	Date/time
`EMailPrebuiltEntity`	Email addresses

Power Fx Expression Reference

Only use functions from the supported list below. Copilot Studio supports a subset of Power Fx — using unsupported functions will cause errors.

# Arithmetic
value: =Text(Topic.number1 + Topic.number2)

# Date formatting
value: =Text(Now(), DateTimeFormat.UTC)

# Conditions
condition: =System.FallbackCount < 3
condition: =Topic.EndConversation = true
condition: =!IsBlank(Topic.Answer)
condition: =System.Conversation.InTestMode = true
condition: =System.SignInReason = SignInReason.SignInRequired
condition: =System.Recognizer.SelectedIntent.TopicId = "NoTopic"

# String interpolation in activity (uses {} without =)
activity: "Error: {System.Error.Message}"
activity: "Error code: {System.Error.Code}, Time (UTC): {Topic.CurrentTime}"

# Record creation
value: "={ DisplayName: Topic.NoneOfTheseDisplayName, TopicId: \"NoTopic\", TriggerId: \"NoTrigger\", Score: 1.0 }"

# Variable initialization (first assignment uses init: prefix)
variable: init:Topic.UserEmail
variable: init:Topic.CurrentTime
# Subsequent assignments omit init:
variable: Topic.UserEmail

Supported Power Fx Functions

These are all the Power Fx functions available in Copilot Studio. Do NOT use any function not on this list.

Math: Abs, Acos, Acot, Asin, Atan, Atan2, Cos, Cot, Degrees, Exp, Int, Ln, Log, Mod, Pi, Power, Radians, Rand, RandBetween, Round, RoundDown, RoundUp, Sin, Sqrt, Sum, Tan, Trunc

Text: Char, Concat, Concatenate, EncodeHTML, EncodeUrl, EndsWith, Find, Left, Len, Lower, Match, MatchAll, Mid, PlainText, Proper, Replace, Right, Search, Split, StartsWith, Substitute, Text, Trim, TrimEnds, UniChar, Upper, Value

Date/Time: Date, DateAdd, DateDiff, DateTime, DateTimeValue, DateValue, Day, EDate, EOMonth, Hour, IsToday, Minute, Month, Now, Second, Time, TimeValue, TimeZoneOffset, Today, Weekday, WeekNum, Year

Logical: And, Coalesce, If, IfError, IsBlank, IsBlankOrError, IsEmpty, IsError, IsMatch, IsNumeric, IsType, Not, Or, Switch

Table: AddColumns, Column, ColumnNames, Count, CountA, CountIf, CountRows, Distinct, DropColumns, Filter, First, FirstN, ForAll, Index, Last, LastN, LookUp, Patch, Refresh, RenameColumns, Sequence, ShowColumns, Shuffle, Sort, SortByColumns, Summarize, Table

Aggregate: Average, Max, Min, StdevP, VarP

Type conversion: AsType, Boolean, Dec2Hex, Decimal, Float, GUID, Hex2Dec, JSON, ParseJSON

Other: Blank, ColorFade, ColorValue, Error, Language, OptionSetInfo, RGBA, Trace, With

Available Templates

Templates are bundled with the plugin. Skills that use templates reference them via ${CLAUDE_SKILL_DIR}/../../templates/.

Template	File	Pattern
Greeting	`templates/topics/greeting.topic.mcs.yml`	OnConversationStart welcome
Fallback	`templates/topics/fallback.topic.mcs.yml`	OnUnknownIntent with escalation
Arithmetic	`templates/topics/arithmeticsum.topic.mcs.yml`	Inputs/outputs with computation
Question + Branching	`templates/topics/question-topic.topic.mcs.yml`	Question with ConditionGroup
Knowledge Search	`templates/topics/search-topic.topic.mcs.yml`	SearchAndSummarizeContent fallback
Custom Knowledge Source	`templates/topics/custom-knowledge-source.topic.mcs.yml`	OnKnowledgeRequested with custom API (YAML-only)
Remove Citations	`templates/topics/remove-citations.topic.mcs.yml`	OnGeneratedResponse citation stripping
Authentication	`templates/topics/auth-topic.topic.mcs.yml`	OnSignIn with OAuthInput
Error Handler	`templates/topics/error-handler.topic.mcs.yml`	OnError with telemetry
Disambiguation	`templates/topics/disambiguation.topic.mcs.yml`	OnSelectIntent flow
Agent	`templates/agents/agent.mcs.yml`	GptComponentMetadata
Connector Action (generic)	`templates/actions/connector-action.mcs.yml`	TaskDialog with connector (structural reference)
Knowledge (Public Website)	`templates/knowledge/public-website.knowledge.mcs.yml`	PublicSiteSearchSource
Knowledge (SharePoint)	`templates/knowledge/sharepoint.knowledge.mcs.yml`	SharePointSearchSource
Global Variable	`templates/variables/global-variable.variable.mcs.yml`	GlobalVariableComponent

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 just this skill

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-reference" --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.

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 ↗

What's inside

Files included with this skill.

View on GitHub

Copilot Studio YAML Reference

Core File Types

Trigger Types

YAML-Only Features

Action Types

Connector Actions (TaskDialog)

Action Structure

Input Types

$-Prefixed Property Names (SharePoint, OData)

System Variables

Variable Scopes

Prebuilt Entities

Power Fx Expression Reference

Supported Power Fx Functions

Available Templates

No requirements beyond installing this skill were found.

Install just this skill

Install the whole plugin

Add Microsoft's marketplace, then install the plugin

Add Microsoft's marketplace, then install the plugin

What's inside

More skills

add-action

add-adaptive-card

add-generative-answers

add-global-variable

add-knowledge

add-node

`$`-Prefixed Property Names (SharePoint, OData)