clone-agent

Brings a chatbot that already lives in Microsoft's cloud down onto your own machine, walking you through picking the right organisation, environment and bot on the way.

WHEN TO USE

SCOPE

USE FOR

Browse the bots you own and download the one you want to work on.
Clone an agent directly from a Copilot Studio URL copied out of the browser.
Reuse a previously cloned agent's saved connection details instead of signing in again.

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

Clone Agent

Guided flow to clone a Copilot Studio agent from the cloud to a local workspace. Walks the user through environment selection, agent selection, and downloads the agent's YAML files.

IMPORTANT: Do Not Modify Scripts

This is a new capability under active development. If the manage-agent script fails, do not attempt to fix, patch, or work around it. Instead:

Show the user the full error output
Direct them to https://github.com/microsoft/skills-for-copilot-studio/issues
Suggest using the Copilot Studio VS Code extension directly as a fallback for push/pull/clone

Phase 0: Resolve Configuration

Look for existing connection details in this order. Stop at the first source that provides a tenantId:

0a. Scan for existing `.mcs/conn.json` files

Search the filesystem for previously cloned agents — these already have all the connection details:

Glob: **/.mcs/conn.json

Also search common project locations:

Glob: /Users/**/projects/**/.mcs/conn.json

Each conn.json contains TenantId, EnvironmentId, DataverseEndpoint, AgentManagementEndpoint, and AccountInfo. Parse any found files and collect unique tenant/environment pairs. If matches are found, present them to the user:

Found existing agent connections:

Employee Assistant — Elad's Env (tenant: 8a235459...)

IT Agent — Contoso Dev (tenant: efb073bb...)

Use one of these, or enter a different tenant ID?

If the user picks one → extract tenantId, environmentId, environmentUrl, agentMgmtUrl and skip to Phase 2 (or Phase 1 if they want a different environment).

0b. Check for a Copilot Studio URL

If the user pastes a Copilot Studio URL (e.g. from their browser while viewing the agent), extract environment and agent IDs directly — no need for list-envs or list-agents.

Recognised URL formats:

https://copilotstudio.microsoft.com/environments/<envId>/bots/<agentId>/overview
https://copilotstudio.preview.microsoft.com/environments/<envId>/bots/<agentId>

If the user provides a URL like this, you still need a tenantId (from a conn.json or by asking the user). Then skip to Phase 3, passing --url instead of --agent-id / --environment-id / --environment-url / --agent-mgmt-url:

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js clone \
  --workspace "." \
  --tenant-id "<tenantId>" \
  --url "<copilotStudioUrl>"

The script will parse the URL to extract the environment ID and agent ID, then resolve the remaining environment details (Dataverse URL, agent management URL) automatically via the BAP API.

0c. Ask the user

If no conn.json found (or user wants a different tenant) → ask for their tenant ID (required).

No --client-id is needed — the script uses VS Code's first-party client ID with interactive browser login automatically.

Phase 1: Select Environment

Tell the user: "A browser window may open for Microsoft sign-in (tokens are cached after first login)."

Run the list-envs command:

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js list-envs \
  --tenant-id "<tenantId>"

Timeout: 300000ms (5 minutes) — set this on the Bash tool call to allow time for browser auth.

Parse the JSON output. On success (status: "ok"), present the environments as a numbered list to the user:

1. Contoso Dev (abc123-...)
2. Contoso Prod (def456-...)

Ask the user to pick an environment. Extract:

environmentId
environmentUrl (the url or dataverseUrl field)
agentMgmtUrl (the agentManagementUrl field)

Phase 2: Select Agent

First, ask the user: "Do you want to list only agents you own, or all agents in the environment?"

If only mine → run without --no-owner (default, filters by current user)
If all agents → add --no-owner flag

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js list-agents \
  --tenant-id "<tenantId>" \
  --environment-url "<environmentUrl>" \
  [--no-owner]

Timeout: 300000ms (5 minutes)

Parse the JSON output. Each agent has agentId, displayName, and ownedByCurrentUser. Present agents as a numbered list:

1. My Support Bot (yours)
2. HR Assistant
3. IT Helpdesk (yours)

Ask the user to pick an agent. Extract the agentId.

Phase 3: Clone

Run the clone command. The workspace should be the current directory (.). The --agent-id is required (from Phase 2):

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js clone \
  --workspace "." \
  --tenant-id "<tenantId>" \
  --agent-id "<agentId>" \
  --environment-id "<environmentId>" \
  --environment-url "<environmentUrl>" \
  --agent-mgmt-url "<agentMgmtUrl>"

Timeout: 300000ms (5 minutes)

On success:

Run Glob: **/agent.mcs.yml to find and show the cloned agent file
Check that .mcs/conn.json was created in the agent directory
Summarize what was cloned and where the files are

Error Handling

Error	Resolution
Browser auth fails or times out	Ask user to try again; check that they have access to the tenant
No environments found	Verify tenant ID is correct and user has Power Platform access
No agents found	Verify environment selection; user may need Copilot Studio access
Clone fails	Check permissions; the user needs maker/admin access to the agent

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 "clone-agent" --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.

View on GitHub

Clone Agent

IMPORTANT: Do Not Modify Scripts

Phase 0: Resolve Configuration

0a. Scan for existing .mcs/conn.json files

0b. Check for a Copilot Studio URL

0c. Ask the user

Phase 1: Select Environment

Phase 2: Select Agent

Phase 3: Clone

Error Handling

Local tool required

Install the whole plugin

Add Microsoft's marketplace, then install the plugin

Add Microsoft's marketplace, then install the plugin

More skills

add-action

add-adaptive-card

add-generative-answers

add-global-variable

add-knowledge

add-node

0a. Scan for existing `.mcs/conn.json` files