Write a skill manifest
APPLIES TO: SDK v4
A skill manifest is a JSON file that describes the actions a skill can take, its input and output parameters, and the skill's endpoints. The manifest contains machine-readable information a developer can use to access the skill from another bot.
This article describes supported versions of the Bot Framework skill manifest schema.
Version | Notes |
---|---|
version 2.2 | Updated some URI properties to accept URI references. |
version 2.1 | Adds ability to describe proactive activities the skill can send and the dispatch models the skill uses. |
version 2.0 | Initial version. |
The Bot Framework skill manifest schemas use draft 7 of the JSON schema vocabulary.
Prerequisites
- Knowledge of skills.
- Some familiarity with JSON Schema and the JSON format.
The skill manifest
The skill manifest contains different categories of information:
- Metadata that describes the skill at a general level.
- A list of the endpoints that the skill provides.
- Optional lists of the activities the skill can receive and proactively send.
- An optional definitions object that contains schemas for objects referenced by other parts of the document.
- An optional list of the dispatch models the skill supports.
The following table describes the full schema for v2.2 of the Bot Framework skill manifest.
Category/Field | Type/Format | Required | Description |
---|---|---|---|
Metadata | |||
$id | String | Required | The identifier for the skill manifest. |
$schema | String/URI | Required | The HTTPS URI of a JSON schema resource that describes the format of the manifest. For version 2.2, the URI is https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json . |
copyright | String | Optional | The copyright notice for the skill. |
description | String | Optional | A human-readable description of the skill. |
iconUrl | String/URI-reference | Optional | The URI of the icon to show for the skill. |
license | String | Optional | The license agreement for the skill. |
name | String | Required | The name of the skill. |
privacyUrl | String/URI-reference | Optional | The URI of the privacy description for the skill. |
publisherName | String | Required | The name of the skill publisher. |
tags | String array | Optional | A set of tags for the skill. If present, each tag must be unique. |
version | String | Required | The version of the skill the manifest describes. |
Endpoints | |||
endpoints | endpoint array | Required | The list of endpoints supported by the skill. At least one endpoint must be defined. Each endpoint must be unique. |
Activities | |||
activities | Object containing named activity objects | Optional | The set of initial activities accepted by the skill. |
activitiesSent | Object containing named activity objects | Optional | Describes the proactive activities that the skill can send. |
Definitions | |||
definitions | Object | Optional | An object containing subschemas for objects used in the manifest. |
Dispatch models | |||
dispatchModels | dispatchModels object | Optional | Describes the language models and top-level intents supported by the skill. See Dispatch models for the schema for this object. |
Endpoints
Each endpoint object describes an endpoint supported by the skill.
This example lists two endpoints for a skill.
"endpoints": [
{
"name": "americas",
"protocol": "BotFrameworkV3",
"description": "Production endpoint for SkillBot in the Americas",
"endpointUrl": "http://myskill.contoso.com/api/messages",
"msAppId": "00000000-0000-0000-0000-000000000000"
},
{
"name": "eu",
"protocol": "BotFrameworkV3",
"description": "Production endpoint for SkillBot in Europe",
"endpointUrl": "http://myskill.contoso.com/api/messages",
"msAppId": "11111111-0000-0000-0000-000000000000"
}
],
endpoint object
Describes an endpoint supported by the skill.
Field | Type/Format | Required | Description |
---|---|---|---|
description | String | Optional | A description of the endpoint. |
endpointUrl | String/URI | Required | The URI endpoint for the skill. |
msAppId | String | Required | The Microsoft AppId (GUID) for the skill, used to authenticate requests. Must match the regular expression: ^[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}$ . |
name | String | Required | The unique name for the endpoint. |
protocol | String | Optional | The supported Bot protocol. Default is "BotFrameworkV3", which represents the Bot Connector API version 3. Use the default value unless your skill specifically uses a different protocol. |
Activities
Each activity object describes an activity accepted by the skill. The skill begins an action or task based on the initial activity it receives. The name associated with the activity object indicates the action or task the skill will perform.
Some activity types have a value property that can be used to provide extra input to the skill. When the skill ends (completes the action), it can provide a return value in the associated end-of-conversation activity's value property.
The activity types allowed are: message, event, invoke, and other activities. A skill can receive an invoke activity, but can't send one.
Here's a sample activity description.
"bookFlight": {
"description": "Books a flight",
"type": "event",
"name": "BookFlight",
"value": {
"$ref": "#/definitions/bookingInfo"
},
"resultValue": {
"$ref": "#/definitions/bookingInfo"
}
},
eventActivity object
Describes an event activity accepted or sent by the skill. The meaning of an event activity is defined by its name field, which is meaningful within the scope of the skill.
Field | Type | Required | Description |
---|---|---|---|
description | String | Optional | A description of the action the event should initiate. |
name | String | Required | The value of the event activity's name property. |
resultValue | Object | Optional | A JSON schema definition of the type of object that the action can return. |
type | String | Required | The activity type. Must be "event". |
value | Object | Optional | A JSON schema definition of the type of object that this action expects as input. |
invokeActivity object
Describes an invoke activity accepted by the skill. The meaning of an invoke activity is defined by its name field, which is meaningful within the scope of the skill.
Field | Type | Required | Description |
---|---|---|---|
description | String | Optional | A description of the action the invoke should initiate. |
name | String | Required | The value of the invoke activity's name property. |
resultValue | Object | Optional | A JSON schema definition of the type of object that the associated action can return. |
type | String | Required | The activity type. Must be "invoke". |
value | Object | Optional | A JSON schema definition of the type of object that this action expects as input. |
messageActivity object
Describes a message activity accepted or sent by the skill. The message activity's text property contains the user's or bot's utterance.
Field | Type | Required | Description |
---|---|---|---|
description | String | Optional | A description of the action. |
resultValue | Object | Optional | A JSON schema definition of the type of object that the associated action can return. |
type | String | Required | The activity type. Must be "message". |
value | Object | Optional | A JSON schema definition of the type of object that this action expects as input. |
otherActivities object
Describes any other activity type accepted or sent by the skill.
Field | Type | Required | Description |
---|---|---|---|
type | String | Required | The activity type. Must be one of the other Bot Framework activity types: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace", or "typing". |
The otherActivities object can include other properties, but the skill manifest schema doesn't define their meaning.
Definitions
Each definition describes a subschema that can be consumed by other parts of the document.
Here's a sample subschema for flight booking information.
"bookingInfo": {
"type": "object",
"required": [
"origin"
],
"properties": {
"origin": {
"type": "string",
"description": "this is the origin city for the flight"
},
"destination": {
"type": "string",
"description": "this is the destination city for the flight"
},
"date": {
"type": "string",
"description": "The date for the flight in YYYY-MM-DD format"
}
}
},
Dispatch models
The dispatch model contains a list of language models and a list of top-level intents supported by the skill. It's an advanced feature to enable a developer of a skill consumer to compose a language model that combines the features of the consumer and skill bots.
Each language model uses the .lu
or .qna
file format. For more information on these formats, see .lu file format and .qna file format.
A locale name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an optional ISO 3166 two-letter uppercase subculture code associated with a country or region, for example "en" or "en-US".
Field | Type | Required | Description |
---|---|---|---|
intents | String array | Optional | A list of the top-level intents supported by the skill. Each intent must be unique. |
languages | Object containing named languageModel arrays | Optional | A list of the language models supported by the skill. Each name is the locale the language models are for, and the array contains the language models for that locale. A dispatch model must support at least one locale. Each locale within the languages field must be unique. |
Here's a sample dispatch model that contains two languages models across three locales. It also describes two top-level intents that the skill can recognize.
"dispatchModels": {
"languages": {
"en": [
{
"name": "SkillBot LU (English)",
"contentType": "application/lu",
"url": "http://sample.com/SkillBot-en.lu",
"description": "English language model for the skill"
},
{
"name": "SkillBot QnA LU (English)",
"contentType": "application/qna",
"url": "http://sample.com/SkillBot-QnA-en.qna",
"description": "English language model for the skill (QnAMaker)"
}
],
"es-ES": [
{
"name": "SkillBot LU (Spanish-Spain)",
"contentType": "application/lu",
"url": "http://sample.com/SkillBot-es-ES.lu",
"description": "Spanish (Spain) language model for the skill"
},
{
"name": "SkillBot QnA LU (Spanish-Spain)",
"contentType": "application/qna",
"url": "http://sample.com/SkillBot-QnA-es-ES.qna",
"description": "Spanish (Spain) language model for the skill (QnAMaker)"
}
],
"es-MX": [
{
"name": "SkillBot LU (Spanish-Mexico)",
"contentType": "application/lu",
"url": "http://sample.com/SkillBot-es-MX.lu",
"description": "Spanish (Mexico) language model for the skill"
},
{
"name": "SkillBot QnA LU (Spanish-Mexico)",
"contentType": "application/qna",
"url": "http://sample.com/SkillBot-QnA-es-MX.qna",
"description": "Spanish (Mexico) language model for the skill (QnAMaker)"
}
]
},
"intents": [
"bookFlight",
"getWeather"
]
},
languageModel object
Describes a language model for a given culture. The name is a locale name.
Field | Type/Format | Required | Description |
---|---|---|---|
contentType | String | Required | Type of the language model. |
description | String | Optional | A description of the language model. |
name | String | Required | Name of the language model. |
url | String/URI-reference | Required | The URL for the language model. |
Sample manifest
Here's a full sample v2.2 manifest for a skill that exposes multiple activities.
{
"$schema": "https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json",
"$id": "SkillBot",
"name": "Sample skill definition that can handle multiple types of activities",
"version": "1.0",
"description": "This is a sample skill definition for multiple activity types",
"publisherName": "Microsoft",
"privacyUrl": "https://myskill.contoso.com/privacy.html",
"copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
"license": "",
"iconUrl": "skillIcon.png",
"tags": [
"sample",
"travel",
"weather"
],
"endpoints": [
{
"name": "americas",
"protocol": "BotFrameworkV3",
"description": "Production endpoint for SkillBot in the Americas",
"endpointUrl": "http://myskill.contoso.com/api/messages",
"msAppId": "00000000-0000-0000-0000-000000000000"
},
{
"name": "eu",
"protocol": "BotFrameworkV3",
"description": "Production endpoint for SkillBot in Europe",
"endpointUrl": "http://myskill.contoso.com/api/messages",
"msAppId": "11111111-0000-0000-0000-000000000000"
}
],
"dispatchModels": {
"languages": {
"en": [
{
"name": "SkillBot LU (English)",
"contentType": "application/lu",
"url": "http://sample.com/SkillBot-en.lu",
"description": "English language model for the skill"
},
{
"name": "SkillBot QnA LU (English)",
"contentType": "application/qna",
"url": "http://sample.com/SkillBot-QnA-en.qna",
"description": "English language model for the skill (QnAMaker)"
}
],
"es-ES": [
{
"name": "SkillBot LU (Spanish-Spain)",
"contentType": "application/lu",
"url": "http://sample.com/SkillBot-es-ES.lu",
"description": "Spanish (Spain) language model for the skill"
},
{
"name": "SkillBot QnA LU (Spanish-Spain)",
"contentType": "application/qna",
"url": "http://sample.com/SkillBot-QnA-es-ES.qna",
"description": "Spanish (Spain) language model for the skill (QnAMaker)"
}
],
"es-MX": [
{
"name": "SkillBot LU (Spanish-Mexico)",
"contentType": "application/lu",
"url": "http://sample.com/SkillBot-es-MX.lu",
"description": "Spanish (Mexico) language model for the skill"
},
{
"name": "SkillBot QnA LU (Spanish-Mexico)",
"contentType": "application/qna",
"url": "http://sample.com/SkillBot-QnA-es-MX.qna",
"description": "Spanish (Mexico) language model for the skill (QnAMaker)"
}
]
},
"intents": [
"bookFlight",
"getWeather"
]
},
"activities": {
"bookFlight": {
"description": "Books a flight",
"type": "event",
"name": "BookFlight",
"value": {
"$ref": "#/definitions/bookingInfo"
},
"resultValue": {
"$ref": "#/definitions/bookingInfo"
}
},
"getWeather": {
"description": "Retrieves and returns the weather for the user's location",
"type": "invoke",
"name": "GetWeather",
"value": {
"$ref": "#/definitions/location"
},
"resultValue": {
"$ref": "#/definitions/weatherReport"
}
},
"message": {
"type": "message",
"description": "Receives the user's' utterance and attempts to resolve it using the skill's LU models"
},
"typing": {
"type": "typing"
},
"conversationUpdate": {
"type": "conversationUpdate"
}
},
"definitions": {
"localeValue": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"description": "The current user's locale ISO code"
}
}
},
"bookingInfo": {
"type": "object",
"required": [
"origin"
],
"properties": {
"origin": {
"type": "string",
"description": "this is the origin city for the flight"
},
"destination": {
"type": "string",
"description": "this is the destination city for the flight"
},
"date": {
"type": "string",
"description": "The date for the flight in YYYY-MM-DD format"
}
}
},
"weatherReport": {
"type": "array",
"description": "Array of forecasts for the next week.",
"items": [
{
"type": "string"
}
]
},
"location": {
"type": "object",
"description": "Location metadata",
"properties": {
"latitude": {
"type": "number",
"title": "Latitude"
},
"longitude": {
"type": "number",
"title": "Longitude"
},
"postalCode": {
"type": "string",
"title": "Postal code"
}
}
}
},
"activitiesSent": {
"flightUpdated": {
"type": "event",
"name": "FlightUpdated",
"description": "Event which is sent by the skill when there is an update in flight info",
"value": {
"type": "object",
"description": "Flight update information",
"properties": {
"flightNumber": {
"type": "string"
},
"departureDate": {
"type": "string",
"description": "The departure date for the flight in YYYY-MM-DD format"
},
"departureTime": {
"type": "string",
"description": "The departure time for the flight in HH-MM format"
}
}
}
}
}
}
Next steps
- How to Implement a skill.
- How to Use dialogs within a skill.
- How to Implement a skill consumer.
- How to Use a dialog to consume a skill.