int-project-context

The background briefing the other Copilot Studio skills share: where everything lives in the project, which lookup tools exist, and the standing rule to go through a proper skill rather than hand-write the files.

WHEN TO USE

SCOPE

USE FOR

Find where topics, actions, knowledge sources, and variables live in the agent's folder structure.
Check what a file is required to contain before anyone writes one by hand.
See everything a connected service can accept, not just what is already wired up.

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

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

When you write new YAML files, be sure to use the schema lookup script to understand the schema, including mandatory fields, definitions, and references. The script is located at ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js, and you can use it in the terminal as follows:

node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js search trigger             # Search by keyword
node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js lookup SendActivity        # Look up a definition
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

If you already know the specific definition you want to look up, use lookup. If you want to explore the schema around a certain topic, use search or summary. Always check the schema before writing YAML to ensure you include all required fields and use valid values.

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 you need to understand available 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 (VERY IMPORTANT)

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. Example skills include /copilot-studio:new-topic for creating new topics, /copilot-studio:add-action for adding connector actions and tools, and /copilot-studio:validate for validating YAML files.

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 int-reference skill).
Generative Orchestration: When GenerativeActionsEnabled: true, use topic inputs/outputs instead of hardcoded questions/messages.

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 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 ↗

Install without the plugin (incomplete)

What's missing

Installing just this skill adds only its own folder. Its instructions also call for other plugin components, such as shared scripts, reference files or other skills, which aren't included. Installing the whole plugin avoids this gap.

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-project-context" --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.

What's inside

Files included with this skill.

View on GitHub

Copilot Studio — Shared Project Context

Project Structure

Schema Lookup Script

Connector Lookup Script

Skill-First Rule (VERY IMPORTANT)

Key Conventions

Local tool required

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