test-auth

The sign-in the testing skills all depend on: do it once here and they reuse it, and it walks you through the Microsoft setup that trips most people up.

WHEN TO USE

SCOPE

USE FOR

Get step-by-step help creating an Azure AD App Registration with the right permissions.
Fix an authentication failure caused by a missing redirect URI or public client setting.
Clear out a stale saved sign-in when the chat quietly hangs instead of replying.

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

Test Agent Authentication

Authenticate with the Power Platform API for evaluation and SDK chat workflows. This caches a token in the "test-agent" slot that is shared by run-eval and chat-sdk.

Step 1: Find the workspace

Locate the agent workspace (directory containing .mcs/conn.json):

Glob: **/agent.mcs.yml

The conn.json provides the tenant ID automatically — no need to ask the user for it.

Step 2: Get the client ID

CRITICAL: You MUST present the FULL configuration checklist below when asking for the client ID. Do NOT omit any items — users frequently miss the redirect URI and public client settings, which causes auth failures.

Ask the user for their App Registration Client ID and show them all of the following requirements in your message:

What is your App Registration Client ID for the Evaluation API?

Before sharing it, please verify your App Registration has all of these settings:

Redirect URI: Under Authentication > Mobile and desktop applications > redirect URI set to http://localhost

Public client: Under Authentication > Advanced settings > Allow public client flows set to Yes

API permissions: Under API permissions, these delegated permissions on the Power Platform API:

CopilotStudio.MakerOperations.Read (list test sets, get results)

CopilotStudio.MakerOperations.ReadWrite (start evaluation runs)

CopilotStudio.Copilots.Invoke (SDK chat — send utterances to the agent)

Admin consent: Granted for the tenant (green checkmarks in the API permissions list)

Missing any of these will cause authentication to fail.

If the user doesn't have one, guide them:

How to create an App Registration:

Go to Azure Portal > App Registrations

Click New registration, name it (e.g., "Copilot Studio Eval")

Under API permissions > Add a permission > APIs my organization uses > search Power Platform API

Select Delegated permissions and add:

CopilotStudio.MakerOperations.Read

CopilotStudio.MakerOperations.ReadWrite

CopilotStudio.Copilots.Invoke

Click Grant admin consent for the tenant

Under Authentication > Add a platform > Mobile and desktop applications > set redirect URI to http://localhost

Still in Authentication, scroll to Advanced settings and set Allow public client flows to Yes (required — without this the interactive browser login will fail with an AADSTS error)

Copy the Application (client) ID from the Overview page

Step 3: Authenticate

Run the auth command (opens a browser — no device code needed):

node ${CLAUDE_SKILL_DIR}/../../scripts/eval-api.bundle.js auth --workspace <path> --client-id <id>

If successful, you'll see:

{"status": "ok", "message": "Authentication successful. Token cached for subsequent commands."}

Return the client ID and workspace path to the caller — they need these for subsequent run-eval and chat-sdk calls.

Troubleshooting

HTTP 403 / InsufficientDelegatedPermissions: The app registration is missing required permissions. Guide the user through adding them (Step 2).
AADSTS700016 / app not found in directory: The client ID doesn't exist in the agent's tenant. The app must be registered in the same tenant as the Copilot Studio environment (check conn.json > AccountInfo.TenantId).
AADSTS7000218 / request body must contain client_secret or client_assertion: The app registration is not configured as a public client. Go to Authentication > Advanced settings > set Allow public client flows to Yes.
SDK chat hangs after auth: The cached token may have stale permissions. Clear the cache and re-authenticate:
- Delete ~/.copilot-studio-cli/test-agent.cache.json
- Run security delete-generic-password -s "copilot-studio-cli" -a "test-agent" to clear the macOS Keychain entry
- Re-run the auth command

Local tool required

3 FOR YOU

All items below are required.

01
Create an Azure AD App Registration
Create an App Registration in Azure Portal for the Copilot Studio evaluation API, then note its Application (client) ID.
02
Set the redirect URI and enable public client flows
Under Authentication, add a Mobile and desktop applications platform with redirect URI http://localhost, then turn on Allow public client flows under Advanced settings.
03
Grant the required Power Platform API permissions
Add the delegated permissions CopilotStudio.MakerOperations.Read, CopilotStudio.MakerOperations.ReadWrite and CopilotStudio.Copilots.Invoke on the Power Platform API, then grant admin consent for the tenant.

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.

01

/plugin marketplace add microsoft/skills-for-copilot-studio

02

/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.

01

/plugin marketplace add microsoft/skills-for-copilot-studio

02

/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 "test-auth" --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

The repository is licensed under MIT — use, modification, and redistribution are allowed under that license’s terms.

View the repository’s license file on GitHub →

Test Agent Authentication

Step 1: Find the workspace

Step 2: Get the client ID

Step 3: Authenticate

Troubleshooting

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