add-global-variable

Name: add-global-variable
Author: microsoft

372stars76forks

How to install add-global-variable?

microsoft/skills-for-copilot-studio/add-global-variable

$npx -y skills add microsoft/skills-for-copilot-studio --skill add-global-variable

Installs into the current project.

Summary

Add a global variable to a Copilot Studio agent. Use when the user needs a variable that persists across topics in the same conversation and can optionally be visible to the AI orchestrator.

Files · 1

View on GitHub

SKILL.md

1	# Add Global Variable
2
3	Create a global variable that persists across all topics within a conversation.
4
5	## Instructions
6
7	1. Auto-discover the agent directory:
8	```
9	Glob: **/agent.mcs.yml
10	```
11	Use the top-level agent. NEVER hardcode an agent name.
12
13	2. Read `settings.mcs.yml` to get the `schemaName` prefix:
14	```
15	Read: <agent-dir>/settings.mcs.yml
16	```
17	Extract the root-level `schemaName` value (e.g., `copilots_header_cre3c_fullagent`).
18
19	3. Determine from the user:
20	- Variable name (PascalCase, e.g., `LastDiscussedCity`)
21	- Description of what it stores
22	- Whether the AI orchestrator should be aware of it (`aIVisibility`)
23	- Default value (if any)
24	- DO NOT skip any of these properties. If the user doesn't provide them, ask follow-up questions to get the necessary information.
25
26	4. Create the variable file at `<agent-dir>/variables/<VariableName>.mcs.yml`:
27
28	```yaml
29	# Name: <Human-readable Name>
30	# <Description>
31	name: <VariableName>
32	aIVisibility: <UseInAIContext or HideFromAIContext>
33	scope: Conversation
34	description: <Description of what the variable stores>
35	schemaName: <prefix>.globalvariable.<VariableName>
36	kind: GlobalVariableComponent
37	defaultValue: <DEFAULT or specific value>
38	```
39
40	5. Key fields explained:
41	- `name` — PascalCase identifier. This is how topics reference the variable: `Global.<name>` (e.g., `Global.LastDiscussedCity`).
42	- `aIVisibility` — Controls orchestrator awareness:
43	- `UseInAIContext` — The orchestrator can read and reason about this variable. Use when the variable influences routing or response generation (e.g., user preferences, conversation state the AI should track).
44	- `HideFromAIContext` — The variable exists but the orchestrator doesn't see it. Use for internal bookkeeping (e.g., counters, flags) that topics use but the AI doesn't need to reason about.
45	- `scope: Conversation` — Always `Conversation` for global variables (persists for the session).
46	- `schemaName` — Must follow the pattern `<agent-schemaName>.globalvariable.<VariableName>`. Read the prefix from `settings.mcs.yml`.
47	- `defaultValue` — Initial value. Use `DEFAULT` if no specific initial value is needed.
48
49	## How Topics Use Global Variables
50
51	Topics reference global variables with the `Global.` prefix:
52
53	```yaml
54	# Reading a global variable in a condition
55	- kind: ConditionGroup
56	id: conditionGroup_Xk9mPq
57	conditions:
58	- id: conditionItem_Lw3nRs
59	condition: =!IsBlank(Global.LastDiscussedCity)
60	actions:
61	- kind: SendActivity
62	id: sendMessage_Yt7vBw
63	activity:
64	text:
65	- "Last time we discussed {Global.LastDiscussedCity}."
66
67	# Setting a global variable from a topic
68	- kind: SetTextVariable
69	id: setTextVariable_Qp4kMn
70	variable: Global.LastDiscussedCity
71	value: =Topic.CityName
72	```
73
74	## When to Use Global Variables
75
76	- Cross-topic state: A value set in one topic needs to be read in another (e.g., user's preferred language, last search query)
77	- AI-aware context: The orchestrator should know something about the conversation state to make better routing decisions (use `UseInAIContext`)
78	- Conversation-wide defaults: A default value that multiple topics can read and optionally override
79	- Dynamic knowledge sources: A global variable can hold a URL that a knowledge source references via `=$"{Global.VarName}"`. This enables routing to different SharePoint folders or websites per user (e.g., by geolocation or department). See `/copilot-studio:add-knowledge` for the full pattern. Important: the variable value must be a clean, direct URL — not a SharePoint AllItems.aspx link with query parameters.

People who liked this also viewed

6 picks

Type

add-global-variable

372stars76forks

View on GitHub

How to install add-global-variable?

microsoft/skills-for-copilot-studio/add-global-variable

$npx -y skills add microsoft/skills-for-copilot-studio --skill add-global-variable

Installs into the current project.

Summary

Add a global variable to a Copilot Studio agent. Use when the user needs a variable that persists across topics in the same conversation and can optionally be visible to the AI orchestrator.

Files · 1

View on GitHub

SKILL.md

1	# Add Global Variable
2
3	Create a global variable that persists across all topics within a conversation.
4
5	## Instructions
6
7	1. Auto-discover the agent directory:
8	```
9	Glob: **/agent.mcs.yml
10	```
11	Use the top-level agent. NEVER hardcode an agent name.
12
13	2. Read `settings.mcs.yml` to get the `schemaName` prefix:
14	```
15	Read: <agent-dir>/settings.mcs.yml
16	```
17	Extract the root-level `schemaName` value (e.g., `copilots_header_cre3c_fullagent`).
18
19	3. Determine from the user:
20	- Variable name (PascalCase, e.g., `LastDiscussedCity`)
21	- Description of what it stores
22	- Whether the AI orchestrator should be aware of it (`aIVisibility`)
23	- Default value (if any)
24	- DO NOT skip any of these properties. If the user doesn't provide them, ask follow-up questions to get the necessary information.
25
26	4. Create the variable file at `<agent-dir>/variables/<VariableName>.mcs.yml`:
27
28	```yaml
29	# Name: <Human-readable Name>
30	# <Description>
31	name: <VariableName>
32	aIVisibility: <UseInAIContext or HideFromAIContext>
33	scope: Conversation
34	description: <Description of what the variable stores>
35	schemaName: <prefix>.globalvariable.<VariableName>
36	kind: GlobalVariableComponent
37	defaultValue: <DEFAULT or specific value>
38	```
39
40	5. Key fields explained:
41	- `name` — PascalCase identifier. This is how topics reference the variable: `Global.<name>` (e.g., `Global.LastDiscussedCity`).
42	- `aIVisibility` — Controls orchestrator awareness:
43	- `UseInAIContext` — The orchestrator can read and reason about this variable. Use when the variable influences routing or response generation (e.g., user preferences, conversation state the AI should track).
44	- `HideFromAIContext` — The variable exists but the orchestrator doesn't see it. Use for internal bookkeeping (e.g., counters, flags) that topics use but the AI doesn't need to reason about.
45	- `scope: Conversation` — Always `Conversation` for global variables (persists for the session).
46	- `schemaName` — Must follow the pattern `<agent-schemaName>.globalvariable.<VariableName>`. Read the prefix from `settings.mcs.yml`.
47	- `defaultValue` — Initial value. Use `DEFAULT` if no specific initial value is needed.
48
49	## How Topics Use Global Variables
50
51	Topics reference global variables with the `Global.` prefix:
52
53	```yaml
54	# Reading a global variable in a condition
55	- kind: ConditionGroup
56	id: conditionGroup_Xk9mPq
57	conditions:
58	- id: conditionItem_Lw3nRs
59	condition: =!IsBlank(Global.LastDiscussedCity)
60	actions:
61	- kind: SendActivity
62	id: sendMessage_Yt7vBw
63	activity:
64	text:
65	- "Last time we discussed {Global.LastDiscussedCity}."
66
67	# Setting a global variable from a topic
68	- kind: SetTextVariable
69	id: setTextVariable_Qp4kMn
70	variable: Global.LastDiscussedCity
71	value: =Topic.CityName
72	```
73
74	## When to Use Global Variables
75
76	- Cross-topic state: A value set in one topic needs to be read in another (e.g., user's preferred language, last search query)
77	- AI-aware context: The orchestrator should know something about the conversation state to make better routing decisions (use `UseInAIContext`)
78	- Conversation-wide defaults: A default value that multiple topics can read and optionally override
79	- Dynamic knowledge sources: A global variable can hold a URL that a knowledge source references via `=$"{Global.VarName}"`. This enables routing to different SharePoint folders or websites per user (e.g., by geolocation or department). See `/copilot-studio:add-knowledge` for the full pattern. Important: the variable value must be a clean, direct URL — not a SharePoint AllItems.aspx link with query parameters.

People who liked this also viewed

6 picks

Type