Write a skill manifest

  • Article

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

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