Table of contents
Last Updated: 12/13/2016
Important

You must apply to join the Cortana Developer Preview Program to create and use a Cortana skill.
Enroll in the Cortana developer preview today.

Cortana skills

Cortana skills let you harness and extend the power of the Cortana experience by integrating functionality from your app or website. In short, the things your app does, from basic commands to rich user experiences, can be offered to users as Cortana skills.

Skills can be presented to the user on both the Cortana canvas and in a notification from Cortana, or they can be executed directly by Cortana through delegation. The user experience depends on the type of skill you create. See Types of skills.

Note

Cortana skills are compatible with Windows apps, Android apps, and web sites.

A skill relies on one or more insights). Insights are bound to a skill and contain information that is provided by the user through a command or query, gathered from user settings and preferences, or derived from the current context of both user and system.

Note

At least one insight is required per skill.

Insights empower Cortana with the ability to be a mediator between the user and your app. They indicate whether a particular skill is appropriate to a situation. They are the conditions that dictate what skills are presented to a user, and when.

The information provided by the insights bound to a Cortana skill are passed to an app through a deep link.

Important

A user must grant Cortana permission to use insights.

Types of skills

There are two types of skills that you can associate with your app.

Predefined (or innate) skills

You can create an skill from scratch (see Create your own skill), or select one from a set of predefined skills that correspond to functionality from your app or web service.

Predefined skills are more deeply integrated into the Cortana experience and can be presented on both the Cortana canvas and in Cortana notifications, activated through both speech and text input, and executed by Cortana without direct user interaction through delegation.

Cortana supports the following predefined skills:

Predefined skillRelated app functionalityShown when a user
Order foodYour app or website can order food and beverage for delivery or pickup.
  • Asks Cortana to order food
  • Has a meeting during a designated meal time.
Send a messageYour app or website can send a message to a contact.
  • Asks Cortana to send a message
  • Arrives at work
  • Leaves work
  • Arrives at home
  • Leaves home

Define your own skill

If none of the predefined skills correspond to functionality from your app or website, you can define your own skill.

Skills defined by you can appear in the Cortana canvas and in Cortana notifications, but do not support speech and text activation, and cannot use Cortana delegation.

Here are some examples of apps with functionality related to a predefined skill:

SkillDescriptionLink
Get nutrition infoThe Contoso Cafe app retrieves nutrition info for specific food items.Contoso Cafe
Turn on LightsThe Peel app for Windows 10 turns smart lights on when you arrive home.Peel


Components of an skill

A skill consists of the following components.

Insight

An insight is a predefined condition associated with a user.

A skill must have at least one insight associated with it, and all associated insights must be true for a skill to be triggered.

The Cortana skill developer preview dashboard steps you through the process of mapping insights to a predefined skill.

You cannot modify the collection of insights associated with a predefined skill.

When defining your own skill, you must manually map insights to the skill.

Here's an example of a predefined skill ("Order Food") that is activated when the user's scheduling preferences for lunch (specified in the Cortana Notebook)coincides with a scheduled meeting.

Insights

Entity

An entity is a single piece of user info relevant to a skill, represented by a name/value pair.

Each skill, predefined or otherwise, includes a collection of one or more entities. If using a predefined skill, you only have to supply the entity values, as the entity names cannot be modified. Otherwise, you must specify both.

Entities can resolve to different types of data, depending on the insight.

Predefined skill entities

The items (such as number, datetime, and so on) specified in an entity for a predefined skill. This data may come from speech and text input, or from contextual data for the skill being invoked.

Insight entities

Contextual data for the skill being invoked. This data can change depending on the insight. See [Skill Insights]() for a list of all insights and the data available to each.

Notebook entities

Information provided by the user through the Cortana Notebook.

A deep link is a URI that identifies specific content, functionality, or business logic provided by an app or web site. Selecting a deep link launches the app or web site and passes the entity data - typically as query string parameters.

A skill must have a valid deep link for each platform you support. If you don't provide a deep link, the skill will not be presented to the user.

When including an entity to a deep link URI, the identifier must be immediately preceded by @@, and immediately followed by @@. The deep link is URL-encoded at run time.

For example, here is a deep link specification for the Order Food skill defined by Contoso Cafe:

contosocafe://order?item=@@food_item@@&user=@@uid@@

At run time, this resolves to:

contosocafe://order?item=Turkey%20Sandwich&user=98c61574-a9ff-4409-960a-33a3880cb893

We recommend that entities be passed as query string parameters. However, they can also be incorporated into the URI themselves, as shown here:

contosocafe://menu/@@food_item@@/details?datatype=@@nutrition_type@@

At run time, this resolves to:

contosocafe://menu/Turkey%20Sandwich/nutrition?datatype=calories

Each skill is presented to the user on the Cortana canvas through a card, or in a notification, that highlights the app associated with the skill. Clicking the card activates the deep link and invokes the skill.

Register your skill

Use the Cortana skill developer preview dashboard to register skills for your apps and websites. (A link to the dashboard is also provided in the top right corner of each screen in the Cortana dev center.)

Registering a skill is free, but requires a Microsoft account (MSA).

You must apply to join the Cortana Developer Preview Program to create and use a Cortana skill.
Enroll in the Cortana developer preview today.

You might need to submit your skills to the respective store for each platform you support. Additional costs might apply.

Learn more

© 2017 Microsoft