manage-agent

The link between the copy of a chatbot on your machine and the one running in Microsoft's cloud — fetch it down, send changes back, compare the two, and publish when it is ready.

WHEN TO USE

SCOPE

USE FOR

Clone an existing Copilot Studio agent into a local folder to start editing it.
Pull the latest remote changes before pushing your own edits, to avoid a version conflict.
Send your edits back up to the agent's draft, before anyone else sees them.
See a diff between your local files and what is currently live in Copilot Studio.
Publish a draft agent so the current version goes live for everyone it is shared with.
List the Copilot Studio agents and environments available to your account.

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

Manage Agent

Push and pull Copilot Studio agent content by calling the VS Code extension's LanguageServerHost binary directly, using the same custom LSP protocol the extension uses internally.

IMPORTANT: Do Not Modify Scripts

This is a new capability under active development. The manage-agent scripts (manage-agent.bundle.js, chat-with-agent.bundle.js) are pre-built bundles that must not be modified, patched, or monkey-patched. If a script fails:

Report the error as-is — show the user the full error output
Do not attempt to fix, patch, or work around script errors — the scripts interact with the LSP binary using a specific protocol and any modifications will break things
Direct the user to raise an issue at https://github.com/microsoft/skills-for-copilot-studio/issues with the error output
Suggest using the VS Code extension directly — the user can perform the same push/pull/clone operations from the Copilot Studio VS Code extension UI as a fallback

Prerequisites

Copilot Studio VS Code extension must be installed (ms-copilotstudio.vscode-copilotstudio).
Azure AD app registration (optional) — only needed for device code flow (auth command). If --client-id is omitted, the script uses VS Code's first-party client ID with interactive browser login instead.
Environment details — tenant ID, environment ID, environment URL, and agent management URL. These come from the .mcs/conn.json inside a cloned agent workspace (created automatically during clone).

Phase 0: Resolve Configuration

Search for .mcs/conn.json in the workspace and nearby directories to find existing connection details. The script auto-reads environment details from conn.json. If no conn.json is found, ask the user for the required parameters.

Phase 1: Authenticate

There are two different auth flows depending on the operation:

For push / pull / clone / changes / list-agents (interactive browser login)

These commands use VS Code's first-party client ID with the Island API gateway. Authentication is interactive — a browser window opens automatically for sign-in. No manual code entry is needed.

On first use, a browser window opens for Microsoft sign-in
Tokens are cached in the OS credential store and silently refreshed for ~90 days
After ~90 days, the browser will open again for re-authentication

No separate auth step is needed before push/pull. The commands handle token acquisition automatically. Just run the command directly (Phase 2).

For the `auth` command (device code flow — chat/test token)

The auth command acquires a generic api.powerplatform.com token using device code flow. This token is used by the chat and test skills, not by push/pull.

Run with a 5-minute timeout:

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js auth \
  --tenant-id "<tenantId>" \
  --client-id "<clientId>" \
  --environment-url "<environmentUrl>"

Timeout: 300000ms (5 minutes) — set this on the Bash tool call.

Token caching and silent refresh

Tokens and MSAL refresh tokens are persisted in the OS credential store (macOS Keychain, Windows DPAPI, Linux secret-tool). After initial authentication:

Access tokens are valid for ~1 hour
Refresh tokens are valid for ~90 days
The script automatically refreshes expired access tokens silently using the cached refresh token
Re-authentication is only needed on the very first use or after ~90 days

When device code flow starts (auth command only)

The script emits a JSON line to stdout:

{"status":"device_code","userCode":"XXXXXXXX","verificationUri":"https://login.microsoft.com/device","message":"...","expiresIn":900}

When you see this in the output, immediately tell the user:

Authentication Required

Please open {verificationUri} in your browser and enter code {userCode}

The command is waiting for you to complete sign-in. You have {expiresIn/60} minutes.

The command will automatically continue once the user completes authentication. Do NOT cancel the command — it is waiting for the browser sign-in to complete.

Two tokens are acquired sequentially (Copilot Studio API, then Dataverse API), so the user may need to authenticate twice on first use.

If the command completes with `status: "ok"`

Tokens are cached. Proceed to Phase 2.

If the command fails with `device_code_expired`

The user didn't authenticate in time. Re-run the auth command and remind them to authenticate promptly.

Phase 2: Execute Command

All commands auto-detect the agent directory (finds the subfolder with .mcs/conn.json) and read connection details from it.

Pull (download remote changes)

--client-id is optional. When omitted, uses VS Code's 1p client with interactive browser login.

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

Push (upload local changes)

Important: Always pull before push to get fresh row versions. If you push without pulling first, you'll get a ConcurrencyVersionMismatch error.

Push automatically validates all .mcs.yml files before pushing and blocks if there are errors. Add --force to bypass validation (not recommended).

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

Validate (check YAML before pushing)

Validates all .mcs.yml files in the workspace using the LSP binary's full diagnostics (YAML structure, Power Fx, schema, cross-file references).

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

Returns JSON: { "valid": true|false, "summary": { "errors": N, "warnings": N }, "files": [...] }

Clone (download agent to new local folder)

Requires either --agent-id (the bot GUID from list-agents) or --url (a Copilot Studio web URL). Uses Island API token automatically.

With explicit IDs:

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

With a Copilot Studio URL (recommended shortcut):

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js clone \
  --workspace "<target-folder>" \
  --tenant-id "<tenantId>" \
  --url "https://copilotstudio.microsoft.com/environments/<envId>/bots/<agentId>/overview"

When --url is provided, the script extracts environmentId and agentId from the URL and resolves environmentUrl and agentMgmtUrl automatically via the BAP API. The --url flag also works with push, pull, changes, and validate commands.

View Changes (diff local vs remote)

--client-id is optional. When omitted, uses VS Code's 1p client with interactive browser login.

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

Publish (make draft agent live)

Publishes the agent so that the current draft becomes the live version reachable by external clients (/chat-with-agent, /run-tests, Teams, etc.). Uses the Dataverse PvaPublish bound action directly (no LSP binary needed).

IMPORTANT — Publishing makes this version of the agent available to ALL users the agent is shared with. If you are working in a development environment this is fine, but if the agent is shared with production users, always confirm with the user before publishing. Ask: "This will publish the agent and make it live for all users it's shared with. Should I proceed?"

The command polls the publishedon field on the bot entity until the timestamp changes, confirming that publish has taken effect. Default timeout is 5 minutes.

node ${CLAUDE_SKILL_DIR}/../../scripts/manage-agent.bundle.js publish \
  --workspace "<path-to-agent-folder>" \
  --tenant-id "<tenantId>" \
  --environment-url "<envUrl>" \
  [--timeout <ms>]

Timeout: 300000ms (5 minutes) — set this on the Bash tool call.

Optional: --agent-id "<agentId>" overrides the bot ID from conn.json.

Publish output (success)

{"status":"ok","botId":"...","publishedOn":"2026-03-27T12:00:00Z","previousPublishedOn":"2026-03-26T10:00:00Z","durationMs":45000,"durationSeconds":45}

When to publish

After a successful push, if the user wants changes to be testable via /chat-with-agent or /run-tests
In an improvement loop (edit → push → publish → test), publish is required between push and test
The command confirms publish completion via API — do not use time-based waits

List Agents

Uses Dataverse REST API directly (no LSP binary needed). --client-id is optional.

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

By default lists only agents owned by the current user. Add --no-owner to list all unmanaged agents.

List Environments

Uses BAP REST API directly (no LSP binary needed). --client-id is optional.

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

Output Format

All commands output JSON to stdout with a status field:

Device code prompt (during auth)

{"status":"device_code","userCode":"XXXXXXXX","verificationUri":"https://login.microsoft.com/device","message":"...","expiresIn":900}

Success

{"status":"ok","method":"powerplatformls/syncPull","result":{...}}

Error

{"status":"error","error":"description of what went wrong"}

Error Handling

Error	Likely cause	Resolution
Extension not found	Copilot Studio VS Code extension not installed	Install from VS Code marketplace
LSP request timed out	Binary not responding or wrong protocol version	Check extension version, try updating
device_code_expired	User didn't authenticate in time	Re-run auth, authenticate promptly
ConcurrencyVersionMismatch	Push without fresh row versions	Pull first, then push
Token expired + silent refresh failed	Refresh token expired (~90 days)	Run `auth` command for new device code flow
Binary missing	Extension installed but binary not present	Reinstall the extension
PvaPublish failed	Insufficient permissions or bot not found	Verify the user has publish permissions and the agent ID is correct
Publish timed out	Publish still in progress after timeout	Increase `--timeout` or check the Copilot Studio UI for status

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 "manage-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

Manage Agent

IMPORTANT: Do Not Modify Scripts

Prerequisites

Phase 0: Resolve Configuration

Phase 1: Authenticate

For push / pull / clone / changes / list-agents (interactive browser login)

For the auth command (device code flow — chat/test token)

Token caching and silent refresh

When device code flow starts (auth command only)

If the command completes with status: "ok"

If the command fails with device_code_expired

Phase 2: Execute Command

Pull (download remote changes)

Push (upload local changes)

Validate (check YAML before pushing)

Clone (download agent to new local folder)

View Changes (diff local vs remote)

Publish (make draft agent live)

Publish output (success)

When to publish

List Agents

List Environments

Output Format

Device code prompt (during auth)

Success

Error

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

For the `auth` command (device code flow — chat/test token)

If the command completes with `status: "ok"`

If the command fails with `device_code_expired`