Add Node

Add Node to Topic

Add a new node to an existing Copilot Studio topic, or modify an existing one.

In Copilot Studio, the elements inside a topic's actions array are nodes (SendActivity, Question, ConditionGroup, etc.). These are different from actions (actions/*.mcs.yml), which are connector-based TaskDialogs. This skill handles nodes within topics.

For generative answers (SearchAndSummarizeContent, AnswerQuestionWithAI), use the /add-generative-answers skill instead — it has the specific patterns, follow-up ConditionGroup logic, and disambiguation guidance needed to set them up correctly.

Instructions

1. Auto-discover the agent directory:

`` Glob: **/agent.mcs.yml `` NEVER hardcode an agent name.

1. Parse the arguments to identify:

• The node type (SendActivity, Question, SetVariable, ConditionGroup, etc.)
• The target topic file
• If modifying an existing node, which node to modify

1. Look up the node schema:

``bash node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve ``

1. Read the existing topic file to understand its current structure.

1. Generate or modify the node with:

• A unique ID (format: _)
• All required properties from the schema
• Appropriate default values

1. Determine the correct insertion point in the actions array and present the plan to the user before writing.

Common Node Types

| Node | Purpose | Key Properties | |------|---------|----------------| | SendActivity | Send message | kind, id, activity | | Question | Ask user input | kind, id, variable, prompt, entity | | SetVariable | Set/compute value | kind, id, variable, value | | SetTextVariable | Set text with interpolation (YAML-only, no canvas) | kind, id, variable, value | | ConditionGroup | Branching logic | kind, id, conditions | | BeginDialog | Call another topic | kind, id, dialog | | EndDialog | End topic | kind, id | | CancelAllDialogs | Cancel all topics | kind, id |

Generative Orchestration Guidelines

When the agent has GenerativeActionsEnabled: true:

• Prefer AutomaticTaskInput over Question nodes for collecting user info (the orchestrator handles prompting automatically).
• Still use Question nodes when: conditional asks (ask X only if Y), or end-of-flow confirmations.
• Prefer topic outputs over SendActivity for returning results.
• Do NOT use SendActivity to show final outputs unless it's a precise mid-flow message.

Power Fx Quick Reference

• Expressions start with =: condition: =System.FallbackCount < 3
• String interpolation uses {}: activity: "Error: {System.Error.Message}"
• Variable init on first assignment: variable: init:Topic.MyVar
• Common: Text(), Now(), IsBlank(), !IsBlank()

Example: Adding a Question Node

- kind: Question
  id: question_k7xPm2
  variable: init:Topic.UserName
  prompt: What is your name?
  entity: StringPrebuiltEntity
  alwaysPrompt: true
  interruptionPolicy:
    allowInterruption: false

Important Notes

• Unique IDs: Use random 6-8 alphanumeric characters. Duplicate IDs cause Copilot Studio errors.
• Verify the node type exists in the schema before generating.
• For ConditionGroup, include at least one condition item with its own unique ID.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/skills-for-copilot-studio
• License: MIT

Install and usage instructions live in the source repository linked above.