/new-topic

user-invocable: false
description: Create a new Copilot Studio topic YAML file. Use when the user asks to create a new topic, conversation flow, or dialog for their agent.
argument-hint: <topic description>
allowed-tools: Bash(node *schema-lookup.bundle.js *), Bash(node *manage-agent.bundle.js *), Read, Write, Glob
context: fork
agent: copilot-studio-author

Create New Topic

Generate a new Copilot Studio topic YAML file based on user requirements.

Instructions

1. **Auto-discover the agent directory**:

   Glob: **/agent.mcs.yml

If multiple agents found, ask which one. NEVER hardcode an agent name.

2. **Check for matching templates** in `${CLAUDE_SKILL_DIR}/../../templates/topics/` first:

• `greeting.topic.mcs.yml` — OnConversationStart greeting
• `fallback.topic.mcs.yml` — OnUnknownIntent fallback with escalation
• `arithmeticsum.topic.mcs.yml` — Topic with inputs/outputs and computation
• `question-topic.topic.mcs.yml` — Question with branching logic
• `search-topic.topic.mcs.yml` — Generative answers from knowledge
• `auth-topic.topic.mcs.yml` — Authentication flow
• `error-handler.topic.mcs.yml` — Error handling
• `disambiguation.topic.mcs.yml` — Multiple topics matched

If a template matches, use it as the starting point.

3. **MANDATORY: Verify ALL `kind:` values against the schema** before writing them:

   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js kinds                    # List all valid kind values
   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve AdaptiveDialog   # Resolve trigger structure
   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve <TriggerType>    # Resolve specific trigger
   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js search <ActionKind>      # Verify an action kind exists

**NEVER write a `kind:` value you haven't verified exists in the schema.** This is the #1 source of hallucination errors. If `schema-lookup.bundle.js search <kind>` returns no results, the kind does NOT exist — do not use it.

4. **Determine the trigger type** from the user's description:

• `OnRecognizedIntent` — For topics triggered by user phrases (most common)
• `OnConversationStart` — For welcome/greeting topics
• `OnUnknownIntent` — For fallback topics
• `OnEscalate` — For escalation to human agent
• `OnError` — For error handling

5. **Generate the topic YAML** with:

• A `# Name:` comment at the top
• `kind: AdaptiveDialog`
• Appropriate `beginDialog` with correct trigger
• **Unique IDs** for ALL nodes (format: `<nodeType>_<6-8 random alphanumeric>`)
• If using a template, replace ALL `_REPLACE` placeholders with unique IDs

6. **Check settings.mcs.yml** for `GenerativeActionsEnabled`. Read the agent's `settings.mcs.yml` to check.

7. **Save** to the agent's `topics/<topic-name>.topic.mcs.yml` directory

8. **MANDATORY: Validate the generated file** after saving:

**Step A: Schema validation** — always run this first:

   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js validate <saved-file.yml>

**Step B: LSP-based validation** — also run this if the agent has `.mcs/conn.json`: Read `.mcs/conn.json` to get connection details, then:

   node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js validate \
     --workspace "<path-to-agent-folder>" \
     --tenant-id "<tenantId>" \
     --environment-id "<envId>" \
     --environment-url "<envUrl>" \
     --agent-mgmt-url "<mgmtUrl>"

Both validations are complementary: schema validation checks structural correctness (action kinds, property placement), while LSP validation checks Power Fx expressions, cross-file references, and environment-specific rules. If either fails, fix the issues before reporting success to the user.

Generative Orchestration Guidelines

When the agent has `GenerativeActionsEnabled: true` in settings:

**Use Topic Inputs** (AutomaticTaskInput) instead of Question nodes to auto-collect user info. Place `inputs` at the **AdaptiveDialog root level** (NOT inside `beginDialog`):

kind: AdaptiveDialog
inputs:                    # <-- at AdaptiveDialog root, NOT inside beginDialog
  - kind: AutomaticTaskInput
    propertyName: userName
    description: "The user's name"
    entity: StringPrebuiltEntity
    shouldPromptUser: true
beginDialog:
  kind: OnRecognizedIntent
  id: main
  actions:
    - ...

• The orchestrator auto-collects inputs based on the description — no explicit Question node needed.
• Still use Question nodes when: conditional asks (ask X only if Y), or end-of-flow confirmations.

**Use Topic Outputs** instead of SendActivity for final results. Use `outputType` at the root level and `SetVariable` to set output values — do NOT use `TaskOutput` (which is only valid in `TaskDialog` connector actions):

kind: AdaptiveDialog
inputs:
  - ...
beginDialog:
  kind: OnRecognizedIntent
  id: main
  actions:
    - kind: SetVariable
      id: setVar_abc123
      variable: Topic.result
      value: ="computed value"
outputType:                # <-- at AdaptiveDialog root
  properties:
    result:
      displayName: result
      description: The computed result
      type: String

• The orchestrator generates the user-facing message from outputs.
• Do NOT use SendActivity to show final outputs (rare exceptions: precise mid-flow messages).

**Include inputType/outputType schemas** at the AdaptiveDialog root level when using inputs/outputs:

inputType:
  properties:
    userName:
      displayName: userName
      description: "The user's name"
      type: String
outputType:
  properties:
    result:
      displayName: result
      type: String

Topic-Action Chaining Under Generative Orchestration

When a topic exists alongside other topics or other actions (i.e. TaskDialog), think carefully about **the topic outputs** — it directly affe