Step-by-Step Guide to Build a How-To Skill

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.

The template leverages AWS Lambda, the Alexa Skills Kit (ASK), and the ASK SDK, while providing the business logic, multiple language support, 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.

This tutorial will walk first-time Alexa skills developers through all the required steps involved in creating a skill using this how-to skill template, called ‘Minecraft Helper’. This post assumes you have some familiarity with JavaScript/Node.js (or a similar programming language) and the Alexa Skills Kit.

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 tutorial, you’ll 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 parameter-based skill using a template called ‘Minecraft Helper’.
• Understand the basics of VUI design - 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 to create a skill - 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 completed your skill, this tutorial will guide you through testing your skill and sending your skill through the certification process, making it available to be enabled by any Alexa user.

Let's Get Started

Step 1. Setting up Your Alexa Skill in the Developer Portal

Skills are managed through the Amazon Developer Portal. You’ll link the Lambda function you created to a skill defined in the Developer Portal.

1. Navigate to the Amazon 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 signed in, navigate to Alexa and select "Getting Started" under Alexa Skills Kit.

3. Here is where you will define and manage your skill. Select "Add a New Skill"

4. Select an initial language you want to support, and then optionally add additional languages later if needed (in Step 7). Make sure the radio button for the custom interaction model is selected for “Skill Type”. Add the name of the 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. Add the invocation name. Since we are using the sample, type “minecraft helper”. We will not use Audio Player for this skill, select "No". Note: "Global Fields" information apply to all languages supported by the skill. Finally, select Next.

5. Now, notice you're in the Interaction Model section.

6. Next, 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. Note: You will need to define both custom slot type values and sample utterances in language that matches current language tab.

• Review the intent schema below. This is written in JSON and provides the information needed to map the intents we want to handle programmatically. Copy/Paste the intent schema in the GitHub repository here to Intent Schema section in Developer Portal.

• You will 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.

• 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".

{
  "intents": [
    {
      "intent": "RecipeIntent",
      "slots": [
      {
        "name" : "Item",
        "type": "LIST_OF_ITEMS"
      }
     ]
    },
    {
      "intent": "AMAZON.RepeatIntent"
    },
    {
      "intent": "AMAZON.HelpIntent"
    },
    {
      "intent": "AMAZON.StopIntent"
    },
    {
      "intent": "AMAZON.CancelIntent"
    }
  ]
}

7. The next step is to build the utterance list.

   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 in use (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.

   Now it's time to add the utterances. Select and copy/paste the sample utterances from GitHub with your initial language. For example, if your select English (US) as initial language above, then you will need to copy/paste SampleUtterances_en_US.txt in previous link. An example of utterances is listed below. Once they are copied, the screen should look similar to the following image:

8. For a How-to skill, we should also add the custom slot. Select “Add Slot Type”. In "Enter Type" type in "LIST_OF_ITEMS". We will also copy the 516 acceptable values based on this sample from our GitHub sample. Go to GitHub and copy the list of values in your initial language. For example, choose LIST_OF_ITEMS_en_US for skill in English(U.S.).

9. Select Save. You should see the interaction model being built (this might a take a minute or two). If you select next, your changes will be saved and you will go directly to the Configuration screen. After selecting Save, it should now look like this:

   

Next we will configure the AWS Lambda function that will host the logic for our skill.

Step 2: Creating Your Skill Logic Using AWS Lambda

Installing and Working with the Alexa Skills Kit SDK for Node.js (alexa-sdk)

To make the development of skills easier, we have created the Alexa SDK for Node.js. We will be using this module to deploy the sample. The Alexa SDK is available on Github and can be deployed as a Node package from within your Node.js environment.

Create an AWS Account

1. Open aws.amazon.com and then choose ‘Create a Free Account’

• Follow the online instructions. Do not worry about the IAM role, we will do that later.
• You will need a Valid Credit Card to set up your account (note the AWS Free Tier will suffice however. You can find out more about the free tier here).
• Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.

2. Sign in to the AWS Console

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

Create an AWS 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, visit the Lambda Getting Started Guide.

1. IMPORTANT: For Regions (upper right), select US East (N. Virginia) for US skills and EU (Ireland) for UK/DE skills. These are the only two regions currently supported for Alexa skill development on AWS Lambda, and choosing the right region will guarantee lower latency.

2. Select Lambda from Compute services (upper left)

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

4. In the ‘Select Blueprint’ page, filter on 'Alexa', select “alexa-skill-kit-sdk-howtoskill”

5. Now, you need to configure the event that will trigger your function to be called. As we are building skills with the Alexa Skills Kit, click on the gray dash-lined box and select Alexa Skills Kit from the dropdown menu.

6. Choose Next to continue.

7. You should now be in the "Configure Function" section. Enter the Name, Description, and select "Node 4.3" as the Runtime for your skill as in the example.

8. Set your handler and role as follows:

   • Keep Handler as ‘index.handler’
   • Drop down the “Role” menu and select “Create a new custom role”. (Note: if you have already used Lambda you may already have a ‘lambda_basic_execution’ role created that you can use.) This will launch a new tab in the IAM Management Console.

9. You will 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. In the Role Summary section, select "Create a new IAM Role" from the IAM Role dropdown menu. The Role Name and policy document will automatically populate.

10. Select “Allow” in the lower right corner and you will be returned to your Lambda function.

11. Keep the Advanced settings as default. Select ‘Next’ and review. You should see something like below. Then select ‘Create Function’:

12. Congratulations, you have created your AWS Lambda function. Copy the ARN for use in the Configuration section of the Amazon Developer Portal.

Step 3: Add Your Lambda Function to Your Skill

1. Navigate back to developer.amazon.com and select your skill from the list. You can select the skill name or the edit button.

2. Select the Configuration section. Add the ARN from the Lambda function you created in the AWS Console earlier. Select the Lambda ARN (Amazon Resource Name) radio button and tick the corresponding region. Then, select “No” for account linking since we will not be connecting to an external account for this tutorial. Paste the ARN you copied earlier into the Endpoint field. Then select Next. Note: the region(s) here should match the region(s) of your Lambda function(s).

3. You have now completed the initial development of your skill. Now it's time to test.

Step 4: Testing Your Skill

1. 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 in the “Skill Information” section.

   • In the Service Simulator, type ‘how can I build a map’ and select “Ask Minecraft Helper”.

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 customize this output later.

3. (Optional) Testing with your device. This is optional as you can do all the testing in the portal. Assuming your Alexa device is on-line (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.

Not working (getting an invalid response)?

• Do you have the right ARN copied from your Developer Portal/Skill into your your Lambda function?
• 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 recipes for a good customer experience.

Step 5: Make it Yours

1. In the Skill Information section in the Developer Console, edit the Skill Information Tab to reflect your new helper skill:

• Provide a skill name that represents the new skill you are creating.
• Come up with a cool Invocation Name that users will use to invoke your skill
• Create a fun icon. Be sure you have the rights to whatever icons you are uploading – you will need to provide both 108x108px and 512x512px images. Need help finding an image? See PixelBay as a possible source for royalty-free images. Use an image editor (such as Paint on Windows or Preview on Mac) to change the size of the image.

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

2. Download your code from your Lambda function on aws.amazon.com. From the 'Actions' dropdown choose 'Download Code'. If you're using a mac, you may need to add a '.zip' extension to the downloaded file. Uncompress this file.

3. Open the source file for your Lambda function, index.js, in an editor of your choice. This is in the src directory of the repository you downloaded earlier. Look for corresponding locale strings in languageStrings object. "Ctrl-F" en for English and de for German. If there are different expressions between U.S. and U.K, we encourage you to specify them using en-US and en-GB while keeping a generic en for other countries. You can learn more about how language resources are looked up by visiting i18next's documentation. You will see all strings defined for current language in the Minecraft Helper example. Note: '%s' in the string represents code logic variable.

4. Change the SKILL_NAME variable to the name of your skill.

"SKILL_NAME": "Minecraft Helper"

5. 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. Look for corresponding language recipes by "Ctrl-F" RECIPE_EN_US for English(U.S.), RECIPE_EN_GB for English(U.K.) and RECIPE_DE_DE for German. In each language block, 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.

6. You will also want to make sure to change the “Minecraft Helper” references in your skill. You don’t have to edit them all, but the following reference changes are required for certification.

• Find this code in the WELCOME_MESSAGE, and change "a chest" to your custom words:

    "WELCOME_MESSAGE" : "Welcome to %s. You can ask a question like, what\'s the recipe for a chest? ... Now, what can I help you with.",

7. 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

8. Copy the Application Id into the value of the APP_ID variable in index.js.

var APP_ID = undefined;  // TODO replace with your app ID.

9. A minimum of 20 recipes is needed to get started, but about 100 is a good number to keep users engaged. The more the better.

10. Be sure to select SAVE when you are all done. Note: we test initially in the Developer Portal, not in our Lambda function (AWS).

11. Log back into your AWS 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 files that you need in the src directory (the node_modules directory and your updated index.js) into a new archive. Be sure that you compress the files in the folder, not the folder itself.

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

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

14. Repeat the tests you performed earlier to ensure your changes are functioning properly. See step 4 for a review of how to performs functional tests.

Step 6: Add Additional Languages (Optional)

You can use the Alexa Skills Kit to create skills in multiple languages. A skill can support a single language, or any combination of the available languages:

• English (US)
• English (UK)
• German

For more on developing skills in multiple languges, go here.

1. To add an additional language, simply select the Add New Language tab in Developer Portal and choose your second language. Choose and fill all necessary information like we did for the initial language of your skill. You will need to define Name and Invocation Name for the current language (e.g. German name for German skills). Then click Save to continue.

2. In the Interaction Model section, our skill shares the same intent schema and uses different sample utterances and custom slot type values in different languages. Copy intent schema from the intent schema in the GitHub repository here and change sample utterances into your second language. Custom slot type values should also be put in the new language for this skill. For Minecraft helper in German, go GitHub repository here for sample utterances and GitHub repository here for custom slot type values.

3. Open the source file for your Lambda function, index.js. In the languageString variable, look up the locale for your current language, edit the language strings, and other message like you did for your initial language. Also remember to edit recipes in recipes.js. Recipie names and recipies strings are supposed to be defined using your second language.

4. For better latency, deploying your code to different endpoints is recommended. Follow the Create Lambda Function instructions in Step 2 and be sure to select an appropriate Lambda region. Select US East (N. Virginia) for US skills and EU (Ireland) for UK/DE skills. Copy the ARN for use in the Configuration section of the Amazon Developer Portal.

5. Go back to skill Configuration section, which contains Global fields for all languages. Add an extra endpoint and paste your Lambda ARN. Save your skill configuration information.

6. Test your skill in the second language using Service Simulator or a device.

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 skills Test section, enter your Utterances into the Simulator to make sure everything is working with your new recipes.

2. Optionally, you can test with your Alexa-enabled device to make sure everything is working correctly. You may find a few words that need to be changed for a better user experience.

Some things to think about:

• Is every recipes pronounced correctly?
• Do you need to change any words to avoid poor pronunciations?

You can use the Voice Simulator in the Test section to simulate Alexa’s responses. In the Voice Simulator, type in each recipe that you are using to test how Alexa will say it. 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 Application Id as per the previous instruction?

3. Select the Publishing Information area of your skill next:

For Global fields, choose an proper category. IMPORTANT: Add the text “This is based on the How-to Skill Template” to the Testing Instructions section. This alerts the Certification team of your submission using this standardized template, smoothing the road to a faster publish. Also select the countries that you want your skill to be available in.

For other publishing information:

• 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.
• In your example phrases, be sure that the examples you use match the utterances that you created in the Interaction Model section. Remember, there are built-in intents such as help and cancel. You can learn more about built-in intents here. You can also review the list of supported phrases to begin a conversation. * 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 the Amazon certification team will fail your Alexa skill submission.

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

4. (Optional) For multi-language skills, once you finish and save publishing information for your initial language, you will need to do it again for your second language. Under your second language tab, select publishing infomation, and add additional publishing region(s) to the global fields and all other customer facing information in non-global fields.

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

6. Select “Save”. If your skill supports multiple languages, then you will need to complete Privacy and Compliance for each language before submission.

7. Select “Submit for Certification”

8. Finally, confirm your submission. 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 skills at any time.

Check out These Other Developer Resources

• Alexa Skills Kit (ASK)
• Alexa Developer Forums
• Knowledge Base
• Intro to Alexa Skills Kit - On Demand Webinar
• Voice Design 101 - On Demand Webinar
• Developer Office Hours
• Developing Skills in Multiple Languages