Copilot Studio — Shared Project Context

You are working inside a Copilot Studio agent project. All YAML files have the .mcs.yml extension.

Project Structure

<agent-dir>/                          # Auto-discover via Glob: **/agent.mcs.yml
├── agent.mcs.yml                     # Agent metadata (display name, schema version)
├── settings.mcs.yml                  # Agent settings (schemaName, GenerativeActionsEnabled, instructions)
├── topics/                           # Conversation topics (AdaptiveDialog YAML files)
├── actions/                          # Connector-based actions (TaskDialog YAML files)
├── knowledge/                        # Knowledge sources (KnowledgeSourceConfiguration YAML files)
├── variables/                        # Global variables (GlobalVariableComponent YAML files)
└── agents/                           # Child agents (AgentDialog YAML files, each in its own subfolder)

Schema Lookup Script

The schema lookup script is at ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js. Use it for any schema queries:

node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js lookup SendActivity       # Look up a definition
node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js search trigger             # Search by keyword
node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve AdaptiveDialog     # Resolve with $refs
node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js kinds                      # List all valid kind values
node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js summary Question           # Compact overview
node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js validate <file.yml>        # Validate a YAML file

NEVER load the full schema file (reference/bot.schema.yaml-authoring.json) — it's too long. Always use the script above.

Connector Lookup Script

The connector lookup script is at ${CLAUDE_SKILL_DIR}/../../scripts/connector-lookup.bundle.js. Use it for any questions about connectors, actions, their inputs, and outputs:

node ${CLAUDE_SKILL_DIR}/../../scripts/connector-lookup.bundle.js list                              # List all connectors with operation counts
node ${CLAUDE_SKILL_DIR}/../../scripts/connector-lookup.bundle.js operations <connector>            # List operations for a connector
node ${CLAUDE_SKILL_DIR}/../../scripts/connector-lookup.bundle.js operation <connector> <operationId>  # Full details of one operation (inputs/outputs)
node ${CLAUDE_SKILL_DIR}/../../scripts/connector-lookup.bundle.js search <keyword>                  # Search operations across all connectors

<connector> matches by API name (shared_office365) or partial display name (outlook).

When to use this: When the user asks about connectors, what inputs/outputs an action has, or what operations are available. The action YAML files in the agent only show configured inputs — connector-lookup shows the full connector definition with all available inputs and outputs.

Skill-First Rule

You have access to specialized skills that handle YAML creation, editing, validation, and testing. ALWAYS invoke the matching skill instead of doing it manually. Skills contain correct templates, schema validation, and patterns. Doing it manually risks hallucinated kind: values, missing required fields, and broken YAML.

Available Skills

Skill	When to use
/copilot-studio:new-topic	Create a new topic
/copilot-studio:add-node	Add/modify a node in an existing topic
/copilot-studio:add-action	Add a connector action (Teams, Outlook, etc.)
/copilot-studio:edit-action	Edit an existing connector action (inputs, outputs, descriptions)
/copilot-studio:add-knowledge	Add a knowledge source (website, SharePoint)
/copilot-studio:add-generative-answers	Add SearchAndSummarizeContent or AnswerQuestionWithAI nodes
/copilot-studio:add-other-agents	Add child agents, connected agents, or other multi-agent patterns
/copilot-studio:add-global-variable	Add a global variable
/copilot-studio:add-adaptive-card	Add an adaptive card to a topic
/copilot-studio:edit-agent	Edit agent settings, instructions, or display name
/copilot-studio:edit-triggers	Modify trigger phrases or model description
/copilot-studio:best-practices	JIT glossary, user context, OnActivity initialization
/copilot-studio:validate	Validate YAML structure against schema
/copilot-studio:lookup-schema	Query a schema definition
/copilot-studio:list-kinds	List all valid kind values
/copilot-studio:list-topics	List all topics in the agent
/copilot-studio:run-tests	Run tests against a published agent
/copilot-studio:chat-with-agent	Send a test message to a published agent
/copilot-studio:known-issues	Search the known-issues KB (GitHub label: kb) for symptoms and mitigations

If no skill matches, only then work manually — but always validate with /copilot-studio:validate afterward.

Key Conventions

• Agent Discovery: NEVER hardcode agent names. Always Glob: **/agent.mcs.yml.
• ID Generation: Random alphanumeric, 6-8 chars after prefix (e.g., sendMessage_g5Ls09).
• Template _REPLACE: Always replace _REPLACE placeholder IDs with unique random IDs.
• Power Fx: Expressions start with =. String interpolation uses {}. Only use supported functions (check _reference skill).
• Generative Orchestration: When GenerativeActionsEnabled: true, use topic inputs/outputs instead of hardcoded questions/messages.