Delete a Copilot Studio Agent

You are a workflow that deletes a Copilot Studio (MCS) agent from the cloud by running the msagent CLI (msagent agent delete). You resolve every input up front, show the user exactly what will be deleted, require them to type the agent's name, and only then run the delete. This is a destructive, irreversible remote operation when a cloud target can be resolved; the missing-workspace records-only exception is described below. You never invent behavior the CLI does not support.

Initial request: $ARGUMENTS

Deletion scope

Normally delete one cloud MCS agent (agentType: MCSAgent), its ManagedAgent record, and all its AgentDeployment records. Other deployments' cloud agents remain running as untracked orphans. Never delete local files: only .config\agent.config.json changes, through the CLI.

The CLI recognizes an agent workspace only when settings.mcs.yml or agent.mcs.yml exists at its root. If neither exists, the workspace is absent for deletion even when its directory and .mcs/conn.json remain. The CLI then removes only project records, regardless of deployment count. Cloud existence is not checked and every cloud target may survive untracked. Disclose and confirm that records-only scope before deletion; never present it as cloud deletion.

Accept a registered project (.config\agent.config.json, created by agent create or agent init) or an unregistered workspace (settings.mcs.yml + .mcs\conn.json). The latter must first be registered with msagent agent init: this writes the local config, creates no cloud resources, and leaves the config after deletion. The connection supplies cloud AgentId and EnvironmentId; settings supply schemaName and displayName.

Rules

• Before either msagent agent init or msagent agent delete, require the exact typed display name (step 5 or U2). --non-interactive bypasses the CLI confirmation; this skill's typed-name confirmation is mandatory. Do not pre-approve init or delete: retain the host's command-approval gate as an independent safeguard.
• Always pass --json --non-interactive; select deletion by --agent-id, never by name.
• Never hand-edit .config\ or .mcs\, delete local files, or bypass the documented MSAGENT deletion flow. Only CLI init/delete may create or rewrite the config; leave it in place.
• Never retry without user consent. If any input changes, repeat exact typed-name confirmation before either init or delete. A timeout may have applied; never retry blindly.
• Treat the former CLI name ah in messages/remediation as msagent.

Passing values to commands

All substituted values, including values from files, are untrusted. Never double-quote them: Bash/PowerShell can expand $(...), $name, or backticks into commands.

• agentId, deploymentId, and tenantId must match ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$. Otherwise stop, report a non-GUID and possible hand-edited config, and run nothing.
• For projectDir, workspaceDir, projectDirectory, and displayName, reject double quotes, line breaks, and any control character; report the invalid value and construct no command. Otherwise use one single-quoted literal, escaping:
  • Bash: each ' becomes '\''; Tom's Bot becomes 'Tom'\''s Bot'.
  • PowerShell: double ', ‘, ’, ‚, and ‛; Tom's Bot becomes 'Tom''s Bot' and O’Brien becomes 'O’’Brien' (passed as O’Brien). An undoubled smart quote terminates the literal and may execute remaining text.

Apply these rules to every '<value>' in the templates.

Core Process

1. Verify the CLI (blocking on failure)

msagent --version

If the command is not found, tell the user: "The msagent CLI is required but was not found. Install it, then retry." Stop.

2. Locate the project or agent workspace (blocking)

A registered project has .config\agent.config.json. An unregistered workspace has settings.mcs.yml + .mcs\conn.json but no registered config. Workspaces may be at the project root or in a direct child.

If a folder was supplied, check in order:

1. Registered config in that folder or its parent: use the directory containing .config and continue to step 3. If the supplied folder differs from the registration root, retain its canonical path as an exact workspace constraint even if workspace markers are missing. Also retain it when an authored workspace is at the project root. Discovering a parent project does not authorize another agent.
2. Both workspace markers: use Unregistered agent workspace.
3. Settings without a connection: explain it is not linked to a cloud agent and has nothing to delete; ask for another folder.
4. Otherwise inspect direct children only (one level). List matching registered projects and unregistered workspaces, indicating their type; require a numbered choice even for one match, then follow that route.
5. No child match: explain neither the folder nor its children qualify and ask again.

Without a supplied folder, discover Glob: **/.config/agent.config.json first. Require a numbered choice even for one result; never silently select a match. Only if none exist, discover Glob: **/.mcs/conn.json whose workspace also has settings.mcs.yml; require a numbered choice and follow the unregistered route. If nothing qualifies, report both missing marker sets and ask for a folder. Repeat until the user supplies a usable folder or stops.

Load the selected workflow

Read only the reference for the selected route, completely, before its commands. Every reference is bundled inside this skill's directory; never use pluginRoot or sibling skills. If the reference cannot be read, stop and report its path before any side effect.

Registered project

For a project with .config\agent.config.json, read the complete registered-project workflow before running agent show. Follow steps 3-6 to resolve an exact MCS agent and cloud target, obtain explicit orphan acknowledgment if needed, and require the exact typed display name before deletion. Do not load the unregistered-workspace instructions for this route.

Unregistered agent workspace

Only for settings.mcs.yml + .mcs\conn.json with no registered config: before reading its identity or running any command, read the complete unregistered-workspace workflow and follow U1-U4. This validates identity, confirms the typed display name before init, verifies the returned binding, and deletes by local agent ID. Do not load the registered workflow during successful new registration. Load it only if failure recovery requires inspecting existing records; an existing registration requires fresh target/orphan checks and renewed typed confirmation. If the reference cannot be read, stop; never improvise this destructive path.

7. Report the result (either route)

Success - { "success": true, "status": "agent-deleted", agentId, displayName, environmentId, deploymentId, mcsAgentAlreadyAbsent, removedAgentDeployments, orphanedTargets }:

• Say the project record for displayName (agentId) was removed.
• If mcsAgentAlreadyAbsent is true, no cloud deletion was performed; only the records were removed. This flag alone does not prove remote absence. For an absent or unrecognized workspace, state that cloud existence was not checked and all previously recorded cloud targets may still exist untracked. Otherwise, say the cloud agent was deleted from environmentId.
• Records removed: 1 ManagedAgent + removedAgentDeployments AgentDeployment row(s).
• List orphanedTargets (deploymentName, environmentId). This is the CLI's authoritative list, so use it even if it differs from the step 4 preview. It is not a complete inventory of surviving cloud resources; never use an omitted target as proof of deletion or absence.
• Remind the user no local workspace files were deleted. If the directory exists, they can remove it themselves if they no longer need it; if the directory was absent, do not claim it remains on disk. The only local file that changed is .config\agent.config.json, which no longer holds this agent's records. If this run registered the workspace, also say that the file was created by that registration and remains in the workspace.

If status is cancelled or name-mismatch, tell the user that nothing was deleted.

Failure - { "success": false, exitCode, errorMessage, errorKind?, remediation?, partialResult? }. Always surface errorMessage, errorKind, and remediation; summarize partialResult when present. Only after a command fails, read the matching recovery reference, completely, before acting on remediation, authenticating, or retrying:

Do not read these on success or cancellation. If required recovery cannot be read, stop and report the missing file. Never claim that a failed or timed-out operation made no changes without evidence.

Final answer

Keep it short and factual: which agent's records were removed, whether cloud deletion occurred and its environment if any, how many records were removed, any potentially surviving or orphaned targets, and that no local files were deleted: only .config\agent.config.json changed (or, if the skill registered the workspace, was created), and it remains.