Configure a Bot Framework skill for use in Copilot Studio

  • Article

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.

Copilot Studio lets you extend your copilot by using Bot Framework skills. If you have already built and deployed bots in your organization (using the Bot Framework SDK and pro-code tools) for specific scenarios, you can convert those bots into a skill and register that skill in a Copilot Studio copilot.

Note

To add a skill from within the Copilot Studio app in Microsoft Teams, you must have a Microsoft Copilot Studio standalone subscription.

This article is intended for system administrators or IT professionals who are familiar with Bot Framework skills. After a skill has been registered with a Copilot Studio copilot, authors can seamlessly trigger skill actions in conversation.

Prerequisites

Important

Copilot Studio copilots only support skills built using Bot Framework SDK version 4.12.0+.

Classic chatbots only support skills built using Bot Framework SDK version 4.7+.

If you're using Bot Framework Composer it's strongly recommended that you use Composer 2.x. If you want to use an existing Composer 1.x copilot, first migrate it to Composer 2.x before using it as a skill.

To configure a skill, the associated app registration in Microsoft Entra ID for your skill should be set to Multi-tenant configuration.

Flows actions and skills actions

The following table will help determine when to use skills for a conversation.

Flow actions Skill actions
Persona Copilot authors can build reusable Flows to embed into any copilot conversation Developers can create, deploy, and host custom skills in their own environment
Conversation Use Flows for simple, single-turn operations. For example, place an order, or get order status. Use skills for complex, multi-turn operations. For example, schedule a meeting or book a flight.
Response Use Flows to emit a copilot response. For example, show a personalized message or inline images. Use skills to emit any supported copilot response. For example, show an adaptive card or send random responses.
Actions Use Flows to trigger server-side single-turn actions. For example, call an HTTP API or trigger a custom connector. Use skills to trigger server-side and client-side events and actions. For example, navigate to a page upon copilot response.

Configure a skill

First, use Copilot Studio to create a copilot and create and deploy a skill using pro-code tools into your organization.

Before registering the skill, provide the copilot's ID to your skills developer to authorize the copilot to call actions in the skill. Learn more about skill allowlist. You can get your copilot's ID from the Add a skill window.

To add a skill to your copilot:

  1. In the navigation pane, expand Settings and select Skills.

  2. At the top of the Skills page, select Add skill.

  3. Copy your copilot ID and provide that to your skills developer.

    Screenshot highlighting the copilot ID on the side of the Add a skill window.

  4. Enter the URL to the skill manifest. A skill's manifest contains the information that your copilot will need to trigger actions within a skill.

  5. Select Next to begin the validation process. Once the validation is successful, your skill is added to your copilot. You can now use this skill in your topics.

Compliance considerations

To protect user privacy, we require skills to be registered as an app in the signed-in user's Microsoft Entra ID tenant.

Troubleshoot errors during skill registration

A series of validation checks are made against the URL. These checks ensure compliance, governance, and usability of the skill being added to your copilot. You will need to fix these errors prior to registering a skill.

Error message Troubleshoot / Mitigation
We ran into problems getting the skill manifest.
(MANIFEST_FETCH_FAILED)		 Try opening your manifest URL in a web browser. If the URL renders the page within 10 seconds, re-register your skill.
The manifest is incompatible.
(MANIFEST_MALFORMED)		 (a) Check if the manifest is a valid JSON file.
(b) Check if the manifest contains required properties
For example, (name, msaAppId, single endpoint, activities/id, activities/description, activities/type (only event or message supported)).
There is a mismatch in your endpoints
(MANIFEST_ENDPOINT_ORIGIN_MISMATCH)		 Check if your skill endpoint matches your Microsoft Entra ID application registration's Publisher domain (preferred) or Home page URL field. Learn more about setting the home page for endpoints.
To add a skill, it must first be registered
(APPID_NOT_IN_TENANT)		 Check if your skill's application ID is registered in your organization's Microsoft Entra ID tenant.
The link isn't valid; The link must begin with https://
(URL_MALFORMED, URL_NOT_HTTPS)		 Re-enter the link as a secure URL.
The manifest is too large;
(MANIFEST_TOO_LARGE)		 Check size of the manifest. It must be less than or equal to 500KB.
This skill has already been added to your copilot.
(MANIFEST_ALREADY_IMPORTED)		 Delete the skill and try registering again.
The skill is limited to 100 actions.
(LIMITS_TOO_MANY_ACTIONS)		 There are too many skill actions defined in skill manifest. Remove actions and try again.
Actions are limited to 25 inputs.
(LIMITS_TOO_MANY_INPUTS)		 There are too many skill action input parameters. Remove parameters and try again.
Actions are limited to 25 outputs.
(LIMITS_TOO_MANY_OUTPUTS)		 There are too many skill action output parameters. Remove parameters and try again.
Your copilot can have a maximum of 100 skills.
(LIMITS_TOO_MANY_SKILLS)		 There are too many skills added into a copilot. Remove an existing skill and try again.
It looks like something went wrong.
(AADERROR_OTHER)		 There was a transient error while validating your skill. Retry.
Something went wrong while checking your skill.
(ENDPOINT_HEALTHCHECK_FAILED, HEALTH_PING_FAILED)		 Check if your skill endpoint is online and responding to messages.
This skill has not allow-listed your copilot
(ENDPOINT_HEALTHCHECK_UNAUTHORIZED)		 Check if your copilot has been added to the skills allowlist.