Export a skill

The Bot Framework supports skills, which are bots that encapsulate bits of conversational logic that can then be used to extend other bots. The bot that contains the skill is a skill bot and the bot that accesses the skill is a skill consumer, also referred to as a root bot if it's the initial bot the user interacts with. You can build a user-facing bot and extend it by consuming your own or third-party skills, without the need to access the skill's source code.

  • A skill is a bot that can perform a set of tasks for another bot.
  • A skill manifest is a JSON file that describes the actions the skill can perform.
  • A local skill does not need to contain a skill manifest when it runs using Composer. A local skill can be called and shared within the Composer environment.
  • A remote skill should contain a skill manifest. A remote skill will expose a skill manifest URL so that the skill can be shared outside the Composer environment.
  • A skill consumer is a bot that can call one or more skills. Any bot created in Composer can be a skill consumer.
  • A root bot is the main bot that is created in your bot's project.
  • A bot project is a top-level container of multiple bots. A bot project must contain a root bot, and may contain one or more local and/or remote skills.

This article explains how to create a local skill and connect it to a consumer bot, and how to create a remote skill. If you already have a remote skill and are looking for how to connect your bot to a remote skill, read the connect to a remote skill article.

Prerequisites

Create a root bot

  1. In Composer, create a new echo bot:

    • Select Create from template, select the Echo Bot template, and select Next.
    • Give your bot a name and description—the bot used in this article is named RootBot— and select OK.
  2. Select the RootBot dialog and change the recognizer type it uses to the Regular expression recognizer.

    In a later step, you will add an Intent recognized trigger to allow the user to start the skill.

Create an echo skill

  1. At the top of the navigation pane, select Add (+), then Create a new skill.

    Add menu for adding a skill.

  2. In the Create a skill in your bot wizard:

    1. Select Create from template, select the Echo Bot template, and select Next.

    2. Give your skill a name and description—the skill used in this article is named EchoBot— and select OK.

      Composer adds the new skill to your project.

      The new skill shown in the project.

  3. By default, the initial EchoBot dialog has Auto end dialog set to true. Change this to false to let the skill loop. Otherwise, it with exit when the dialog's Unknown intent trigger comes to an end.

  4. Select the EchoBot dialog and change the recognizer type it uses to the Regular expression recognizer.

Allow the echo skill to end

Since the echo skill is designed to loop, you need to give the user a way to exit from the skill and return to the root bot.

  1. Go to the EchoBot dialog and add an Intent recognized trigger.

    Name it stop and set the regEx pattern to stop.

  2. To the new stop trigger, add a Send a response action to acknowledge the user's input. Set the bot response to Thanks for using the echo skill.

  3. Then add an End this dialog action from the Dialog management menu. Once all active dialogs in the skill end, control returns to the root bot.

Now, your local skill is ready! Let's connect this skill to another bot in Composer.

Call the local skill from the root bot

Update the root bot to start the skill when the user enters "echo".

  1. Go to the RootBot dialog and add an Intent recognized trigger.

    Name it echo and set the regEx pattern to echo.

  2. To the new echo trigger, add a Send a response action to acknowledge the user's input. Set the bot response to Forwarding you to the echo skill.

  3. Add an Access external resources > Connect to a skill action.

  4. In the Properties pane on the right side, set the following properties:

    1. In the Skill Dialog Name field, select the skill you want to connect to, the EchoBot.

    2. Note that by default the Skill Endpoint field is set to Local Composer. Composer will connect to the skill running locally on your machine. This also means Composer doesn't need a manifest to call the skill.

    3. Set Activity processed to false. This will send the activity for the current turn to the skill as the first activity it receives.

      The intent-recognized trigger for echo, with the actions for acknowledging user input and connecting to the local skill.

  5. Finally, update the Unknown intent trigger in the RootBot dialog.

    • Select the Send a response action and change the response to Enter **echo** to access the echo skill.
    • This will help tell the root bot responses apart from the echo skill's.

You now can test the skill bot and its connection with the consumer bot.

Note

You don't need an Azure registration resource for the local bot-to-bot connection.

Test the bots locally

Start bot bots locally to test that you can access the echo skill from the root bot and that the echo skill can end and return control to the root bot.

  1. Select Start all bots in the upper-right corner of the screen. This tells Composer to start all local bots in the project.

  2. Once the bot's runtime has started, the Local bot runtime manager opens. Use the Open start bots panel ( ) button to expand and collapse the manager.

  3. In the Local bot runtime manager, test the RootBot in the Emulator.

    1. Interact with the root bot, then enter echo to have the root bot start the skill.

      Enter 'echo' to get the root bot to start the echo skill.

    2. Interact with the skill, then enter stop to have the echo skill end and return control to the root bot.

      Enter 'stop' to get the echo skill to return control to the root bot.

Prepare a remote skill

In Composer, a remote skill is a bot that contains a skill manifest and can be shared and consumed using a skill manifest URL. A skill manifest is a JSON file that describes the actions the skill can perform. Make sure you already have a local skill or follow these steps to create one in Composer.

Publish your skill to Azure

The first step is to publish your skill to Azure.

Navigate to the Publish page and select the skill bot. Then follow the instructions in the Publish a bot article to publish your skill to Azure.

Select publish from the navigation pane, select the skill bot, and select **Manage profiles** from the **Select a publish target** menu.

Generate a skill manifest

The second step is to use the creation wizard in Composer to generate your skill manifest.

  1. Select Design to go back to the Authoring canvas. On the Navigation pane, select the three-dot icon to the right of your skill. Select Create/edit skill manifest from the drop-down menu.

    Create a skill manifest.

  2. On the Create or edit skill manifest window, select a manifest version and then select Create.

  3. On the Describe your skill window, enter some values to describe your skills manifest in the form. Select Next.

    You will find the following table helpful when you enter the values to generate your skill manifest.

    Category Type Required Description
    Name String Required The name of the skill.
    Version String Required The version of the skill the manifest describes.
    Publisher Name String Required The name of the skill publisher.
    Description String Optional A human-readable description of the skill.
    Privacy Url String Optional The URI of the privacy description for the skill.
    Copyright String Optional The copyright notice for the skill.
    License String Optional The license agreement for the skill.
    Icon Url String Optional The URI of the icon to show for the skill.
    Tags String Optional A set of tags for the skill. If present, each tag must be unique.

    Tip

    For the complete tables describing the full schema for v2.0 and v2.1 of the Bot Framework skill manifest, read the how to write a v2.0 skill manifest and how to write a v2.1 skill manifest articles from the Bot Framework SDK documentation.

  4. On the Skills endpoints window, enter the values for Name, Endpoint Url, Microsoft App Id, and optionally enter a description in the Description field. Select Next.

    • The Name will be the human-readable name for the endpoint.
    • The Description should describe what features available through this endpoint. This is useful when a skill exposes more than one endpoint.
    • The Endpoint Url should be the messaging endpoint of your remote skill.
    • The Microsoft App Id should be the value of the Bot Channel Registration of your published skill.

    skills endpoints

  5. On the next screen, select the dialogs to be included in the skill manifest. Check Select all to select all the dialogs. Select Next.

  6. On the next screen, select the triggers to be included in the skill manifest. Check Select all to select all the dialogs. Select Generate.

  7. On the Review and generate screen, review the manifest file generated. Select Next.

  8. Finally, on the Save your skill manifest screen, enter a name for the skill manifest. You can select Edit in JSON if you want to make changes to the manifest file. Select Save.

  9. Now you can find the generated skill manifest file in your skill bot's project folder such as C:\Users\UserName\Documents\Composer\SkillBotName\manifests. Record the skill manifest file name. You will use it in step 2 of the republish the skill to Azure section to concatenate your remote skill's manifest URL.

    An example skill manifest generated in this process may look like the following.

    {
        "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
        "$id": "TodoSimple",
        "name": "Todo skill",
        "version": "1.0",
        "description": "This skill echoes whatever the user says",
        "publisherName": "Microsoft",
        "privacyUrl": "https://myskill.contoso.com/privacy.html",
        "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
        "license": "",
        "iconUrl": "https://myskill.contoso.com/icon.png",
        "tags": [
            "sample",
            "echo"
        ],
        "endpoints": [
            {
                "name": "default",
                "protocol": "BotFrameworkV3",
                "description": "Production  endpoint for SkillBot.",
                "endpointUrl": "http://localhost:3983/api/messages",
                "msAppId": "0000000-0000-0000-0000-0000000000000"
            }
        ],
        "activities": {
            "message": {
                "type": "message",
                "description": "A message activity containing the utterance that the skill will echo back to the user"
            }
        }
    }
    

Update the allowed-callers setting

Before republishing your skill to Azure, make sure the following setting is updated in your skill bot:

On the Project Settings page, toggle Advanced Settings View (json). Update the allowedCallers property of the skillConfiguration settings.

    "skillConfiguration": {
    "isSkill": true,
    "allowedCallers": []
    },
Property Description Type Example value
allowedCallers The msAppIds of all the bots it connects to. Set to "*" to allow all callers. array "123-34-456", "234-45-567"

Republish the skill to Azure

  1. Follow the instructions in the publish section of the publish a bot article and republish the skill to Azure.

  2. After publishing the skill to Azure successfully, you will need to concatenate your remote skill URL in the following format:

    https://skill-name.azurewebsites.net/manifests/manifest-file-name.json

    Note

    Refer to step 9 of the generate skill manifest section to learn how to find the skill's manifest file name.

  3. Enter the remote skill manifest URL in your browser. You should be able to see your manifest file like the following:

    {
      "$schema": "https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json",
      "$id": "Skill-ea085bd2-e19a-41b1-b67b-d83e0bd73a06",
      "endpoints": [
        {
          "protocol": "BotFrameworkV3",
          "name": "EchoSkill",
          "endpointUrl": "https://skill-name.azurewebsites.net/api/messages",
          "msAppId": "0000000-0000-0000-0000-0000000000000"
        }
      ],
      "name": "Skill",
      "version": "1.0",
      "publisherName": "Microsoft",
      "activities": {
        "Skill": {
          "type": "event",
          "name": "Skill"
        },
        "conversationUpdate": {
          "type": "conversationUpdate"
        }
      }
    }
    

Note

Learn how to find a remote skill manifest URL from the Composer FAQ - How do I find my remote skill manifest URL article.

Now your remote skill is ready! Read the how to connect to a skill article and learn how to connect a bot to this remote skill.

Further reading