title: Implement a skill | Microsoft Docs description: Learn how to implement a skill, using the Bot Framework SDK. keywords: skills author: JonathanFingold ms.author: kamrani manager: kamrani ms.topic: article ms.service: bot-service ms.date: 01/27/2020 monikerRange: 'azure-bot-service-4.0'

Implement a skill

[!INCLUDEapplies-to]

You can use skills to extend another bot. A skill is a bot that can perform a set of tasks for another bot.

• A skill's interface is described by a manifest. Developers who don't have access to the skill's source code can use the information in the manifest to design their skill consumer.
• A skill can use claims validation to manage which bots or users can access it.

This article demonstrates how to implement a skill that echoes the user's input.

Prerequisites

• Knowledge of bot basics and skills.
• An Azure subscription. If you don't have one, create a free account before you begin.
• A copy of the skills simple bot-to-bot sample in C#, JavaScript or Python.

About this sample

The skills simple bot-to-bot sample includes projects for two bots:

• The echo skill bot, which implements the skill.
• The simple root bot, which implements a root bot that consumes the skill.

This article focuses on the skill, which includes support logic in its bot and adapter.

C#

JavaScript

Python

For information about the simple root bot, see how to Implement a skill consumer.

Resources

Bot-to-bot authentication requires that each participating bot has a valid app ID and password.

To be able to test the skill as a user-facing bot, register the skill with Azure. You can use a Bot Channels Registration. For more information, see how to register a bot with Azure Bot Service.

Application configuration

Add the skill's app ID and password to the skill's configuration file.

The allowed callers array can restrict which skill consumers can access the skill. Leave this array empty, to accept calls from any skill consumer.

C#

EchoSkillBot\appsettings.json

Add the skill's app ID and password to the appsettings.json file.

[!code-csharpconfiguration file]

JavaScript

echo-skill-bot/.env

Add the skill's app ID and password to the .env file.

[!code-javascriptconfiguration file]

Python

Add the skill's app ID and password to the config.py file.

config.py

[!code-pythonconfiguration file]

Activity handler logic

To accept input parameters

The skill consumer can send information to the skill. One way to accept such information is to accept them via the value property on incoming messages. Another way is to handle event and invoke activities.

The skill in this example does not accept input parameters.

To continue or complete a conversation

When the skill sends an activity, the skill consumer should forward the activity on to the user.

However, you need to send an endOfConversation activity when the skill finishes; otherwise, the skill consumer will continue to forward user activities to the skill. Optionally, use the activity's value property to include a return value, and use the activity's code property to indicate why the skill is ending.

C#

EchoSkillBot\Bots\EchoBot.cs

[!code-csharpMessage handler]

JavaScript

echo-skill-bot/bot.js

[!code-javascriptMessage handler]

Python

echo-skill-bot/bots/echo_bot.py

[!code-pythonMessage handler]

To cancel the skill

For multi-turn skills, you would also accept endOfConversation activities from a skill consumer, to allow the consumer to cancel the current conversation.

The logic for this skill does not change from turn to turn. If you implement a skill that allocates conversation resources, add resource cleanup code to the end-of-conversation handler.

C#

EchoSkillBot\Bots\EchoBot.cs

[!code-csharpEnd-of-conversation handler]

JavaScript

echo-skill-bot/bot.js

Use the onUnrecognizedActivityType method to add an end-of-conversation logic. In the handler, check whether the unrecognized activity's type equals endOfConversation.

[!code-javascriptEnd-of-conversation handler]

Python

echo-skill-bot/bots/echo_bot.py

[!code-pythonEnd-of-conversation handler]

Claims validator

This sample uses an allowed callers list for claims validation. The list is defined in the skill's configuration file and is read into the validator object when it's created.

You can add a claims validator to the authentication configuration. The claims are evaluated after the authentication header. Your validation code should throw an error or exception to reject the request. There are many reasons you may want to reject an otherwise authenticated request. For example:

• The skill is part of a paid-for service. User's not in the data base should not have access.
• The skill is proprietary. Only certain skill consumers can call the skill.

C#

Derive a claims validator from the ClaimsValidator class. It will throw an UnauthorizedAccessException to reject an incoming request. Note that the IConfiguration.Get method returns null if the value in the configuration file is an empty array.

EchoSkillBot\Authentication\AllowedCallersClaimsValidator.cs

[!code-csharpClaims validator]

JavaScript

Define a claims validation method that throws an error to reject an incoming request.

echo-skill-bot/authentication/allowedCallersClaimsValidator.js

[!code-javascriptClaims validator]

Python

Define a claims validation method that throws an error to reject an incoming request.

echo-skill-bot/authentication/allowed_callers_claims_validator.py

[!code-pythonClaims validator]

Skill adapter

When an error occurs, the skill's adapter should clear conversation state for the skill, and it should also send an endOfConversation activity to the skill consumer. Use the code property of the activity to signal that the skill ended due to an error.

C#

EchoSkillBot\SkillAdapterWithErrorHandler.cs

[!code-csharpError handler]

JavaScript

echo-skill-bot/index.js

[!code-javascriptError handler]

Python

echo-skill-bot/app.py

[!code-pythonError handler]

Service registration

The Bot Framework adapter uses an authentication configuration object (set when the adapter is created) to validate the authentication header on incoming requests.

This samples adds claims validation to the authentication configuration and uses the skill adapter with error handler described in the previous section.

C#

EchoSkillBot\Startup.cs

[!code-csharpConfiguration]

JavaScript

echo-skill-bot/index.js

[!code-javascriptconfiguration]

Python

app.py

[!code-pythonconfiguration]

Skill manifest

A skill manifest is a JSON file that describes the activities the skill can perform, its input and output parameters, and the skill's endpoints. The manifest contains the information you need to access the skill from another bot.

C#

EchoSkillBot\wwwroot\manifest\echoskillbot-manifest-1.0.json

[!code-jsonManifest]

JavaScript

echo-skill-bot/manifest/echoskillbot-manifest-1.0.json

[!code-jsonManifest]

Python

echo_skill_bot/wwwroot/manifest/echoskillbot-manifest-1.0.json

[!code-jsonManifest]

The skill manifest schema is a JSON file that describes the schema of the skill manifest. The current schema version is skill-manifest-2.0.0.json.

Test the skill

At this point, you can test the skill in the Emulator as if it were a normal bot. However, to test it as a skill, you would need to implement a skill consumer.

Download and install the latest Bot Framework Emulator

1. Run the echo skill bot locally on your machine. If you need instructions, refer to the README file for the C#, JavaScript, or Python sample.
2. Use the Emulator to test the bot as shown below. Note that when you send an "end" or "stop" message to the skill, it sends an endOfConversation activity in addition to the reply message. The skill sends the endOfConversation activity to indicate the skill has finished.

Next steps

[!div class="nextstepaction"] Implement a skill consumer