Publishing Cortana Skills

Cortana provides three deployment groups that you can deploy your skill to: self, group, and world.

Each deployment environment contains the same instance of your skill.

Cortana assigns two IDs to your skill, skillId and skillProductId. Cortana passes the IDs in the message's channel data (see Get Cortana's channel data). The skill's ID is unique per deployment environment. If your skill checks the ID, be aware that the IDs are different for each environment. You might use the skill's ID if you want to turn on more logging in the group environment.

The skill's product ID is unique across deployment environments.

Deploy to self

Deploying to self makes the skill available to you only, so you can thoroughly test your skill before deploying it to one of the other environments. After configuring the Cortana channel for your skill (see Configure Cortana Channel, it's automatically deployed to self.

To confirm that your skill was deployed, log in to the Cortana dashboard using the same Microsoft account (MSA) that you used to register it in Bot Frameworks.

For information about testing your skill, see Testing and debugging Cortana Skills.

To deploy your skill to group or world, see Deploy to group and Deploy to world.

Deploy to group

Deploying to group makes the skill available to a group of users that you specify using their MSA email address. Typically, you use this deployment to have others test your skill and provide feedback, so you can improve it before making it generally available.

The following are the steps to deploy your skill to group.

  1. Log in to the Cortana dashboard using the MSA you used to register your skill in Bot Framework.
  2. Locate the skill you want to deploy and click Deploy to group.
  3. In the Deploy your skill to a group window, enter a semicolon-delimited list of MSA email addresses belonging to the users you want to share your skill with. When done, click Deploy.
  4. If successful, copy the URL that the deployment returns and send it to the users in your group.
  5. When the users click the link, they're taken to a page where they can join or leave the group as they see fit. They must be logged in using the MSA account you used in step 3.

At this point, in the dashboard, you can see that the skill is deployed to self and group.

To add or remove users from the group, click Edit group and update the semicolon-delimited list of MSA email addresses as appropriate. Then, click Deploy.

To delete the group deployment, click Delete deployment.

Deploy to world

Deploy to world when you're satisfied with your skill and want to make it available to everyone. Deploying to world makes your skill available in all markets that you specified when you registered your bot. Before deploying your skill to world, make sure that you read the review guidelines and fully comply.

The following are the steps to deploy your skill to world.

  1. Log in to the Cortana dashboard using the MSA you used to register your skill in Bot Framework.
  2. Locate the skill you want to deploy and click Deploy to world.
  3. In the Submit your skill for publication window, specify the following information:
Field Description
Testing instructions Provide instructions about how to test your skill. Provide at least three invocation phrases that demonstrate all the features of your skill. If your skill requires credentials, provide a test account. See section 2.3 Skill is Testable in the Publishing review guidelines.
Terms of use URL Provide a link to your Terms of Use that users must consent to before using the skill. For an sample terms of use, see Terms of Use Guidelines.
Privacy policy URL Provide a link to the privacy policy for your skill. For information about creating a privacy policy, see Privacy Policy Guidelines.
Example phrases users can say to your skill Provide a list invocation phrases (utterances) that user can say to exercise features of your skill.
Search key words Provide a comma-delimited list of keywords that user might use to search for your skill. You may specify a maximum of seven keywords.
Category Select the category that your skill belongs to. For example, sports, music, or personal finance.
Contact email Provide an email address where Microsoft may send correspondence. If you don't provide a monitored email address, you will not receive import updates and notifications.
  1. To submit your skill for review, click Submit. If the submission is successful, Cortana adds the World deployment instance to the skill in the dashboard, and the skill is sent to the Cortana team for review. The skill is not deployed until it passes the review.

If the Cortana team has any concerns or questions during the review process, they will email you. If all requirements are met, your skill is approved and deployed.

Withdraw your skill

Because the skill is locked while it's under review, you may not make changes to it. If you want to make changes to your skill, click Withdraw. You may withdraw your skill only while it's being reviewed or has been approved but not deployed to the world. Clicking Withdraw generates an email template that you fill out and send to the Cortana team.

Common reasons why skills don't pass the review

If you read the review requirements and made sure that you followed them, you shouldn't have too much problem passing the review. But, the following are some of the common reasons why skill fail the review.

  • The invocation name does not meet policy requirements.
  • Your submission did not provide sample invocation phrases. Provide at least three sample invocation phrases that demonstrate how your skill works. Ensure that the invocation phrases actually work with your skill. You should provide enough samples that demonstrate all the key features of your skill.
  • You provide sample phrases but:
    • Forget to include a launch word (Ask, Tell, ...) or invocation name. For example, for a skill called, My Events:
      • "My Events update" - missing the launch word.
      • "ask for an update" - missing the invocation name.
    • The samples do not work ask expected or described. For example, if the invocation phrase is, "Ask My Events to find a nearby event," it should return nearby event information, or ask for more information if needed.
  • The skill does not provide support for Help. Most first-time users will ask the for help (say Help). If a user asks for help, your skill should tell the user how to use the skill. For example, "Do you want available miles, used miles, or discounts?" or "Please say a stock's name. For example, say Microsoft."
  • Your skill infringes on the intellectual property (IP) of another company. Your skill's name and invocation name should not consist of any trademarked or copyrighted words unless you have permission to do so from the owner. Ensure that you have the right to share the content that your skill provides. For example, your skill shouldn't make use of any unlicensed or pirated audio content.