Getting Started: Building your first Cortana Skill using the Cortana Skills Kit in under an hour!


Okay, let’s get started with blogs! And what better way to start than by showing how you can quickly get setup and create a Cortana Skill in under 60 minutes! All you need is access to a web browser, a phone number/credit card (just to verify identity, not charged) and familiarity with a programming language like C# or Node.JS.


 If you don’t know this already, Cortana Skills can be created by building a bot using the Microsoft Bot Framework and publishing it to the Cortana channel. You can check out the Cortana Skills Kit documentation to get a great overview of what Cortana Skills are, what they can do and how users can use them to get things done.


So, let’s get started!


Step 1: Get a free Microsoft Account


You will need a Microsoft Account to deploy and use a Cortana Skill. So, if you don’t already have one, create a new Microsoft Account by following the steps here




Ensure that you sign-up with an email or create a new one ( during the process.


Step 2: Get a free Azure account


The fastest and the easiest way to get a bot up and running is using the Azure Bot Service. It accelerates the process of developing a bot by provisioning a web host with templates that you can modify. You can sign up for a new Azure account for free at


All the resources you need for running a bot are available with a free tier – so you can keep going forever (yep! always free!) if you are under the specified usage limit (up to a million executions per month!).


So, head over to the Azure Free account sign-up page and follow the steps to create a free Azure Account.



Once you are done signing up, you should check out the Azure Accounts page for subscription information (You’ll see the 29-day trial period but don’t worry, you can keep your bot going forever with free tier options).


Step 3: Create a Bot using the Azure Bot Service


Using Azure Bot Service is the quickest way to get a bot up and running. It provisions a web host with one of five bot templates you can modify in an integrated environment. There are two plans to choose from – the App Service Plan (which deploys an Azure Web App) and the Consumption Plan (which uses Azure Functions to run a serverless bot). We’ll use the Consumption plan for now so we are not just getting set-up quickly – but are also lightweight on assets (serverless FTW!).


Navigate to the Azure Portal , click on ‘New’ in the menu blade, and select the Bot Service (Preview) under Data + Analytics category. 



 In the creation view, provide a unique name for your new instance of the Bot Service. Change the Hosting Plan type to a Consumption Plan to ensure your bot runs on Azure Functions. You can continue with the App Service Plan if you wish to run the bot on a full fledged web app. Change the location to Central US so all requests from the region get served with optimal performance. (IYDK The public preview for Cortana is available for the en-us market only.)




Click on Create. Azure will then start creating your bot instance and start deployment. The deployment should take about 2-3 minutes and you will be notified of successful deployment through the notifications on the top right corner of the portal. 


Once the depployment is done, you can refresh the portal to see a new App service instance of your Bot under the All Resources column. 




Click on the bot instance name. 


You will need to register your bot with the Microsoft Bot Framework using a Microsoft App ID. This ID would be used to authenticate requests from and to your bot, across different channels, when the messages pass through the bot framework. Click on Create Microsoft App ID and password.




 You will then be redirected to a new page where you can generate an app password for the newly created ID. Click on Generate an app password to continue. Copy and securely store the password that is shown, then click OK. Click Finish and go back to Bot Framework. Once back, paste the app password you just copied from the previous page. (If you lose the app password later, you can always create a new app ID and associate that with your bot.)


 You can now choose the language in which you want to generate the templates. C# and Node.JS are the two currently available options with more in the works. You can choose either one of them, but for this time, let’s choose C#.




Now you need to choose one out of five available templates that help you quickly get started on creating bots. You can choose any of them (except Proactive – Cortana Skills currently do not support proactive messages). Let’s select the Basic template to start simple and we can extend the code later once we have the basic pluming done. 




Select your country/region and click on Create bot. In under a minute, a new Azure Function with the Basic Template should be provisioned for you. 


Notice the different sections if the integrated development environment that you are presented with once the bot is created. You have the BUILD tab with the files in the project related to the Azure Function that will be used for running the bot, a CHANNELS tab which we will get to – to publish the bot to various channels, an ANALYTICS tab to quickly add analytics to your bot, a SETTINGS tab to modify bot level settings and a TEST tab to verify the bot functionality in real time. 




If you selected C# as your preferred language, you will see the run.csx file in the BUILD tab which is the primary script that is invoked. Change the switch-case in the Run method in run.csx file to 


            switch (activity.GetActivityType())
                case ActivityTypes.Message:
                    var client = new ConnectorClient(new Uri(activity.ServiceUrl));
                    var reply = activity.CreateReply();
                    reply.Text = "Hello World!";
                    reply.Speak = "Hello World!";
                    await client.Conversations.ReplyToActivityAsync(reply);
                case ActivityTypes.ContactRelationUpdate:
                case ActivityTypes.Typing:
                case ActivityTypes.DeleteUserData:
                case ActivityTypes.Ping:
                    log.Error($"Unknown activity type ignored: {activity.GetActivityType()}");


Multiple things to note in this code snippet:

  • ActivityTypes.Message is the activity type generated whenever your bot/skill receives a new message
  • reply.Speak is used to specify the text that Cortana should speak out to the end-user

Once you have made the change, click Save on the top right corner of the code window. You can test the bot text responses by clicking on the TEST tab and sending a new message to your bot. 


Your brand new, simple to set-up, Hello World bot is now ready! Now we just need to let Cortana know of this awesome bot & how to invoke this functionality when a user needs it.


Step 4: Add the Cortana channel to your bot


 Go to the CHANNELS tab and click on the Cortana icon from the list of channels at the bottom. 



You will now enable your bot as a Cortana Skill by providing the necessary information – which includes the 

  • Display name – the name with which the skill is referenced when displaying information and getting the required consent from end users
  • Invocation name – used by Cortana to uniquely identify and invoke your skill
  • Short & Long descriptions for your skill
  • Optional settings related to how Cortana can provide additional context and help manage user’s identity – which we will cover later

Enter a Display name, a unique Invocation name, Short Description & Long Description. Click SAVE when done. 



Once the settings are saved, you should see Cortana as one of the channels on which your Bot is registered.




Congratulations! Your bot is officially a new Cortana skill! 


Can’t wait to try it out? Check out the next step on how you can try out the skill on Cortana. 


Step 5: Invoke the Cortana Skill


Once you register your bot to the Cortana channel, the skill is available for use by the same MSA with which you created the skill. You can manage various stages of publication and testing the skill at the Cortana Dev dashboard. (content for another blog!)


Before you try to invoke the skill on Cortana across Windows, Android or iOS apps, ensure that you are signed into Cortana with the same MSA as you created the skill & that your region settings for the device are set to en-US. 


Go ahead and say “Hey Cortana! Open <invocation name>”. The first time you (or any user) invoke a skill, Cortana confirms that you are OK with sharing the requested information with a Skill. Accept it once and you are good to go. Invoke the skill again for a very enthusiastic “Hello World!”




You can use multiple invocation phrases to invoke the skill. 


Step 6: And we are done!


That’s it. We saw how to use free resources to quickly create a Cortana Skill and invoke it from Cortana on any device.


In subsequent blogs we will see the different ways Cortana Skills can be created using Bot Framework, how we can debug skills locally, test it with a group of users and finally how to publish the Skill for the millions of Cortana users in the US. 


Please let us know below if you have any questions. We would also love to hear about specific topics for blogs that you would like to see and we would be happy to oblige! 


Have a great day!


– The Cortana Skills Kit Team.

* This article was originally published here


Please enter your comment!
Please enter your name here