Use this tutorial to build a how-to skill and get your free Alexa Dev t-shirt. For more details, see terms and conditions.

We have launched a new skill template that makes it easy for developers and non-developers to create a skill similar to “DrinkMaster,” "Aromatherapy", "Timed Meditation", "Minecraft Helper", etc. These type of skills share the unique ability to parameterize what the user says and map it to a content catalog. For example, a user might say "Alexa, Ask Aromatherapy for a recipe for focus" and Alexa would map the word "focus" to the correct oil combination in the content catalog. Or, a user might say "Alexa, Ask DrinkMaster how to make a Margarita" and Alexa would map the word "margarita" to the correct drink recipe in the content catalog.

This template leverages AWS Lambda and the Alexa Skills Kit, while providing the business logic, use cases, error handling and help functions for your skill. You just need to come up with a content idea (like "Snack Recipes"), plug in your content and edit the sample provided (we walk you through how it’s done). It's a valuable way to quickly learn the end-to-end process for building and publishing an Alexa skill.

Using the Alexa Skills Kit, you can build an application that can receive and respond to voice requests made on the Alexa platform. In this step-by-step tutorial, you will build a web service to handle notifications from Alexa and map this service to a Skill in the Amazon Developer Portal, making it available on your device and to all Alexa users after certification.

After completing this tutorial, you will know how to:

• Create a parameter-based skill - This tutorial will walk first-time Alexa skills developers through all the required steps involved in creating a how-to or recipe-based skill using a code template called ‘Minecraft Helper’.
• Design for VUI - Creating this skill will help you understand the basics of creating a working Voice User Interface (VUI) while using a cut/paste approach to development. You will learn by doing and end up with a published Alexa skill. This tutorial includes instructions on how to customize the skill and submit it for certification. For guidance on designing a voice experience with Alexa you can also watch this video.
• Use JavaScript/Node.js and the Alexa Skills Kit - You will use the template as a guide but the customization is up to you. For more background information on using the Alexa Skills Kit please watch this video.
• Get your skill published - Once you have created your skill, this tutorial will guide you through testing it and submitting it for certification. After your skill is certified, it's available for any Alexa user to enable.

Let’s Get Started

We'll start by getting the sample working. First, download the code, then follow the instructions below.

Step 1 – Create an AWS Account

1.  Open aws.amazon.com and choose ‘Create a Free Account’. If you already have an account, continue to the next step.

1. Follow the instructions. You may be asked to create an IAM (Identity and Access Management) role, you can ignore it for now as we will be doing this in a later step.
2. You will need a valid Credit Card to set up your account (note the AWS Free Tier will suffice. You can find out more about the free tier here.)
3. The sign-up process involves receiving a phone call and entering a PIN using your phone's keypad.

2.  Sign into the AWS Console

It can sometimes take a couple minutes for your new AWS account to become active. You will receive an e-mail when your account is active.

Step 2 – Create a Lambda Function

AWS Lambda lets you run code without provisioning or managing servers. You pay only for the compute time you consume - there is no charge when your code is not running. With Lambda, you can run code for virtually any type of application or backend service - all with zero administration. Just upload your code and Lambda takes care of everything required to run and scale your code with high availability.

Note: If you are new to Lambda and would like more information, see the Lambda Getting Started guide.

1.  IMPORTANT: Select US East (N. Virginia) region (upper right). This is the only region that currently supports Alexa skill development. If you do not select the correct region, it will not work.

2.  Select Lambda from Compute Services (upper left).

3.  Select "Create a Lambda Function" to begin the process of defining your Lambda function.

4.  At the bottom of the ‘Select Blueprint’ page, select "Skip"

5.  You should now be in ‘Configure Function’

• Enter the Name, Description, and Runtime for your skill as shown in the example. Select “Node.js 4.3” as the runtime setting.

6.  Select the ‘Code Entry Type’ as ‘Upload Zip File’ and upload the zip file containing the example code. Here’s the link again for reference.

7.  Set your handler and role as follows:

a.  Keep Handler as ‘index.handler’

b.  Drop down the "Role" menu and select "Basic execution role". (Note: If you've already used Lambda you may already have a ‘lambda_basic_execution’ role created that you can use. You may need to scroll down to see the option.) This will launch a new tab in the IAM Management Console.

c.  You'll be asked to set up your Identity and Access Management or "IAM" role if you have not done so. AWS Identity and Access Management (IAM) enables you to securely control access to AWS services and resources for your users. Using IAM, you can create and manage AWS users and groups, and use permissions to allow and deny their access to AWS resources. We need to create a role that allows our skill to invoke this Lambda function.

8.  Accept the defaults to create a new IAM Role with a role name of ‘lambda_basic_execution’. Select "Allow" in the lower right corner and you will be returned to your Lambda function.

9.  Keep the Advanced Settings as default. Select ‘Next’ to review. You should see something like below. Then select ‘Create Function’:

10.  Next we will need to create an Event source. Event sources publish events that cause the Lambda function to be invoked. Upon invocation, AWS Lambda executes your code by passing the event to the handler in your Lambda function. You associate an event source with your Lambda function using an event source mapping. We will use the Alexa Skills Kit as the event source and map it to this function.

a.  From the Lambda function tabs, select ‘Event sources’:

b.  Select ‘Add event source’

c.  Select ‘Alexa Skills Kit’ from the dropdown:

d.  You should see confirmation of creation of the free tier event source "Alexa Skills Kit":

11.  Keep this tab open as you will need to copy the ARN for your Lambda function for use in the developer portal. You can find your ARN at the top right corner of the function page:

Step 3 – Set-up Your Alexa Skill in the Developer Portal

Skills are managed through the Amazon Developer Portal. You will link the Lambda function you created above to a Skill defined in the Developer Portal.

1.  Open a new tab and go to the Developer Portal. Sign in or create a free account (upper right). You might see a different image if you have registered already (or our page may have changed). If you see a similar menu and the ability to create an account or sign in, you are in the right place.

2.  Once you’ve signed in, navigate to Alexa. You can also bookmark this page for future reference here.

3.  Under Alexa Skills Kit, select ‘Get Started’:

4.  Here is where you'll define and manage your skill. Select "Add a New Skill":

5.  This will guide you through the settings required to create your skill. First, you need to select the type of skill you are creating. For this example, select the "Custom Interaction Model" radio button, as we are not creating a smart home API skill in this tutorial. Add the name of your skill. You can use "Minecraft Helper" for this example. Remember, when you create a skill that you will publish, you will use a name that you define for your skill. That name will be the one that shows up in the Alexa App. Note: You will NOT be publishing this example.

6.  Add the Skill Name and Invocation Name. Since we are using the sample, type "Minecraft Helper" for both.

7.  Select Next.

a.  Now we need to define our skill’s interaction model. Let’s begin with the Intent Schema. In the context of Alexa, an intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots. We will be leveraging custom slots to parameterize our user’s requests.

b.  Review the Intent Schema here. This is written in JSON and provides the information needed to map the intents we want to handle programmatically.

c.  Highlight the contents of the intent schema and copy it.

d.  Paste the intent schema into the intent schema section of the interaction model. Again, you can find this in our Github repository here.

Below you'll see the intents for getting a recipe, and then a collection of built-in intents to simplify handling common user tasks. Help intent will handle any time the user asks for help, stop and cancel are built-in intents to make it easier for you to handle when a user wants to exit the application. For more on the use of built-in intents, go here.

 

JSON     


{ "intents": [   


{"intent": "RecipeIntent",    

"slots": [     {      

"name" : "Item",      

"type": "LIST_OF_ITEMS"    

}   

]  

}, 

{     "intent": "AMAZON.HelpIntent"   },

{     "intent": "AMAZON.StopIntent"   },  

{     "intent": "AMAZON.CancelIntent"   }

]  

}

You will notice that the RecipeIntent has a custom slot containing "Items". This allows you to let the user provide a parameter and you can customize the response based on which "item" they choose. For example, for an Aromatherapy recipe skill, items could be "focus", "stress relief" or "relaxation".

8.  The next step is to build the list of Sample Utterances. Given the flexibility and variation of spoken language in the real world, there will often be many different ways to express the same request. Providing these different phrases in your sample utterances will help improve voice recognition for the abilities you add to Alexa. It is important to include as wide a range of representative samples as you can – all the phrases that you can think of that are possible (though do not include samples that users will never speak). Alexa also attempts to generalize based on the samples you provide to interpret spoken phrases that differ in minor ways from the samples specified.

9.  Now it is time to add the Sample Utterances. Copy the utterance list from our GitHub sample. There should be 135+ utterances in your list.

a.  Once they are copied, the screen should look similar to the following image:

b.  Select Save. This will cause an error as we are referring to an utterance parameter of "Item" that has not been defined. This also shows you where errors will show up, if they occur.

c.  To fix this we will need to add the custom slot. Select “Add Slot Type”.

d.  In "Enter Type" type in "LIST_OF_ITEMS".

   

e.  We will copy the 516 acceptable values based on this sample from our GitHub sample. Go to GitHub and copy the list of values.

f.  Paste the values into the "Enter Values" text box. Then select Ok.

g.  Now you should see that your custom slot has been defined. Choose Next to build the interaction model.

h.  Well done! Your custom interaction model is now successfully created.

10.  Select Next, and you will be taken to the Configuration screen. The skill’s endpoint is the mechanism for executing a skill's functionality. Our code is running on AWS Lambda, so select Lambda ARN. Copy the ARN from the AWS console browser tab you should still have open from a previous step. Copy the ARN from the Lambda function:

Select "No" for Account Linking and Next to move to the Test screen.

11.  You have now completed the initial development of your skill. You should see a screen that looks like this:

Step 4 – Test your Alexa Skill

We are now ready to test.

In the Test area, we are going to enter a sample utterance in the service simulator section and see how Alexa will respond. In this example, we have called the skill ‘Minecraft Helper’. This is the ‘Invocation Name’ we set up on the Skill Information line in the "Skill Information" section. We recommend testing every utterance before certification. Since we will not be certifying this example, you can reduce the number of utterances you test.

1.  In the Service Simulator, type ‘How can I build a map’ and select "Ask Minecraft Helper". Remember the "map" is the parameter "Item" that we created through a custom slot earlier. If you need a refresher on what you can ask, review the interaction model and custom slot values for acceptable combinations.

Here are a few additional examples to help you begin testing:

• How can I build a juke box
• How can I craft a firework rocket
• How can you make a red carpet
• How do I build a wooden pick ax
• How do I get a cauldron

2.  You should see the formatted JSON request from the Alexa Service and the response coming back. Verify that you get a correct Lambda response, and notice the card output. You will want to change this output later when you customize this skill.

3.  (Optional) Testing with an Alexa-enabled device. This is optional as you can do all the testing in the developer portal. Assuming your Amazon Echo device is online (and logged in with the same account as your developer account), you should now see your skill enabled in the Alexa app and ask Alexa to launch your skill. For more information on testing an Alexa skill and registering an Alexa-enabled device, check here.

Troubleshooting (Getting an Invalid Response)?

• Do you have the right ARN copied from your Lambda function into your Developer Portal / Skill?
• Are you calling the right invocation name?
• Are you saying Launch, Start or Open?
• Are you sure you have no other skills in your accounts with the same invocation name?
• For this template specifically, you should have a minimum of 20 items in your content catalog for a good customer experience.

Step 5 – Make it Yours

1.  In the Skill Information section in the Developer Console, edit the text fields to reflect your new Recipe Skill:

a.  Provide a skill name that represents the new skill you are creating. Our example will be Aromatherapy.

b.  Come up with a unique and intuitive Invocation Name that users will use to invoke your skill, again we will be using Aromatherapy. You will change the setting from the Minecraft example to your own custom values. You can review the invocation name guidelines here.

2.  Go to the Intent Schema section. Review the JSON for the Intent Schema, you can leave this as is for this example.

• In the Intent Schema section, you will need to edit the custom slots. Leave the name of the slot the same (LIST_OF_ITEMS), you just want to change the values. You do not need 500+ slot values, but the more you have the better your skill can react to your user's requests. In this example, we will be adding the following values for the Aromatherapy skill. Choose Edit to add your own custom slot values to the skill.

The following is an example catalog for the Aromatherapy skill:

focus

eliminating odors

boosting my immune system

peace and calm

stuffy nose

insect repellent

stress relief

happy

etc...

It is recommended to brainstorm these values in a separate document, and then copy and paste them into the values needed for the custom slot. You will match these values to the content you want provided to the user in the recipe.js file. We will do this in a few steps.

When you have added all your values, select Save.

3.  Everything else can stay as-is for now in the Developer Portal

4.  Update your item content catalog. The recipe.js file contains all the items that will be mapped to the custom slots you defined earlier in your skill. This can be found in the recipe.js file. Locate the directory you downloaded earlier, and open the recipe.js file with your favorite text editor.

In this file, the recipes follow this format "Item": "description". Here is a snippet of code for reference.

"snow golem": "A snow golem can be created by placing a pumpkin on top of  two snow blocks on the ground.",    

"pillar quartz block": "A pillar of quartz can be obtained by placing a block of quartz on top of a block of quartz in mine craft.",

You will want to replace these entries with content specific for your skill. We have created an example skill, Aromatherapy. Here is an example snippet of how we modified these entries for our Aromatherapy skill.

"focus": "You can combine Rosemary, Peppermint, and Sage to help with Focus.",    

"eliminating odors": "You can combine Lemongrass, Myrtle and TeeTree oils for a refreshing scent.",    

"boosting my immune system": "You can combine Peppermint and Lavender or Peppermint and Lemon to boost your immune system",

Try to create at least 20 different items in your content catalog. Once you have updated all the entries specific to your skill, you need to update the index.js file.

5.  Next, open the source file for your Lambda function, index.js, in an editor of your choice. The zip file was downloaded in an earlier step or you can find it here.

We will need to make several edits to this file.

Find line 43, where the event handler for onlaunch is defined:

MinecraftHelper.prototype.eventHandlers.onLaunch = function (launchRequest, session, response) {

Change the SpeechText variable in this handler to provide a welcome message to the user. This is what will be read to the user when they launch the skill without a specific intent. You will want to use the welcome message to provide a brief introduction to the skill and give the user some sample phrases to use with your skill.

Here is the example for Aromatherapy:

MinecraftHelper.prototype.eventHandlers.onLaunch = function (launchRequest, session, response) {    

var speechText = "Welcome to the Aromatherapy Skill. This skill helps you learn what essential oils to use for different situations in your life. After hearing a recipe you can also find the details listed in the Alexa App. You can ask questions like, what's the recipe for focus? ... Now, what can I help you with.";

6.  You may also want to consider changing the built-in intents with something other than "Goodbye". Here is an example for Aromatherapy.

"AMAZON.StopIntent": function (intent, session, response) { var speechOutput = "Thanks for using AromaTherapy. Peace Be With you. Until next time"; response.tell(speechOutput); },

"AMAZON.CancelIntent": function (intent, session, response) {
    var speechOutput = "Thanks for using AromaTherapy. Peace Be With you. Until next time.";
    response.tell(speechOutput);
},

7.  Next you will edit how your skill handles when a user asks for help. This needs to be different than the welcome message. You will want to provide additional details about the skill and educate the user on how to use it. Here is the example for Aromatherapy.

"AMAZON.HelpIntent": function (intent, session, response) {

       var speechText = "Aromatherapy is a skill that provides you with recipes for diffusing, combining certain essential oils for a specific effect, such as peace or comfort. You can say things like What's the recipe for focus. or Tell me a recipe for a stuffy nose. Or you can also say exit... Now, what can I help you with?"; 

       var repromptText = "You can say things like, what's the recipe for focus, or you can say exit... Now, what can I help you with?";

8.  Notice the intent handler for RecipeIntent. We do not have to change this since we are using the custom slots created in the sample. Take some time to review this code as it’s important to understand how the slot values are retrieved from the intent. Here is the snippet:

"RecipeIntent": function (intent, session, response) {        

var itemSlot = intent.slots.Item, itemName;

if (itemSlot && itemSlot.value){

    itemName = itemSlot.value.toLowerCase();

}

9.  Save all of your changes.

Step 6 - Prepare for Publishing

1.  Be careful as you edit the strings during customization. Make sure not to delete quotation marks or remove code you might need. You can always go back to GitHub and copy it again if you make a mistake.

2.  You will also want to make sure to change the “MinecraftHelper” references to the name of your skill. You don’t have to edit them all, but make sure none of the string responses contain "Minecraft Helper". If you miss this, it will impact your submission process.

3.  In order to control who accesses your web service, we should validate the Application ID in requests made to your web service. Let’s go back to your Alexa skill in your Developer Portal for a moment. Copy in your Application ID from the ‘Skill Information’ section in your developer portal / skill and copy it into your Lambda function.

4.  In your AWS Lambda function, in the index.js file, find the definition of the APP_ID in the first few lines of code. Replace undefined with your app id in quotes. See the example of what you will change below.

var APP_ID = undefined; //replace with 'amzn1.echo-sdk-ams.app.[your-unique-value-here]';

5.  A minimum of 20 items in the content catalog is recommended to get started, about 100 is a good number to keep users engaged. The more the better. Try to imagine as many items as you can. You want your users to be successful when they request your skill.

6.  Be sure to SAVE your lambda function, when you are done. Note: we will do more testing in the Developer Portal, not in our Lambda function (AWS).

7.  Log back into your AWS Management Console and upload the changes you have just made. First, you will need to zip up the files into a new archive. You can do this by selecting the three files that you need (AlexaSkill.js, recipe.js and your updated index.js) into a new archive. Be sure that those are the only three files in your archive file. Note: a common mistake is to zip the entire folder, which will fail to work. Instead, just select the files and compress only those files. You can usually find the option to compress or archive files in the context menu of your file explorer.

8.  Select your Lambda function and on the Code tab, select “Upload” to add the archive you just created.

9.  Once you have successfully added the archive file you will see it on the screen, then select “Save”.

10.  Repeat the tests you performed earlier to ensure your changes are functioning properly. See Step 4 for a review of how to perform functional tests. We will not be submitting to certification until we have sufficiently tested this customized skill. You can review the latest testing guidelines here.

Step 7 – Publish Your Skill

Now we need to go back to our Developer Portal to test and edit our skill and we will be ready for certification.

1.  In your skill's Test section, enter all of your Utterances into the Simulator to make sure everything is working with your new items. You can use the voice simulator for these tests. Notice the small play button, you can press that to hear how Alexa will respond. An Echo, Dot, Tap or Fire TV can be used for testing as well, though this is not required.

2.  Some more things to think about:

• Does every item sound correct?
• Do you need to change any words to make them sound correct?
• Would punctuation help with the cadence of Alexa's speech?
• In the Voice Simulator, type in each item that you are using to test how Alexa will respond. Use additional punctuation or possibly SSML if you need to better control how Alexa responds. You can find out more about SSML here.
• Have you added in YOUR ApplicationID as per the previous instruction?

3.  Select the Description area of your skill next:

a.  Spend some time coming up with an enticing, succinct description. This is the only place you have to attract new users. These descriptions show up on the list of skills available in the Alexa app.

b.  IMPORTANT:  The example phrases you list in the publishing information must match the sample utterances in the interaction model. Double check this for each example you provide. If this is not correct, your skill may not pass certification. Remember, there are built-in intents such as Help and Cancel. You can learn more about built-in intents here. You can also find a list of supported phrases to begin a conversation here.

c.  Next we need to add icons that can be used to identify our skill in the store. Be sure you have the rights to whatever icons you are uploading – you will need to provide both 108x108px and 512x512px images. If there is any question about copyright, your skill may not pass certification.

4.  Once you have uploaded your icons, you should see a success message at the bottom of the screen.

5.  IMPORTANT: Add the text “#Template #HowTo” to the Testing Instructions section. This alerts the certification team of your submission using this standardized template, smoothing the road to a faster publish. Finally, select Next.

6.  Privacy and Compliance. On the Privacy and Compliance section, select ‘No’ for spending real money and collecting personal information. Privacy and Terms URL’s are optional. Choose to certify that your skill can be imported to and exported from the US.

a.  Select “Save” and then select “Submit for Certification”.

b.  Finally, confirm your submission.

c.  Select “Yes” to submit your skill.

Congratulations!

You have successfully submitted your skill for publication. You will receive progress e-mails and possibly other suggestions from the team on how you can make your skill even better. You can update your skill at any time.