Amazon Alexa Tutorial: Build Your Own Skill

The Alexa Skills Kit (ASK) allows developers to leverage Amazon’s knowledge and pioneering work in the field of voice design to create custom solutions that can be used with Amazon devices such as the Echo and Dot.

To assist the development community Amazon has created a collection of self-service APIs, tools, documentation, and code samples they dubbed the Alexa Skills Kit (ASK) that makes it fast and easy for you to create your own custom skills. Skills are equivalent to apps for Amazon’s voice-powered platforms.

Today we will focus on building your first custom skill that you can run on your favorite Alexa device. We’ll be working from this GitHub repository where you will be able to copy and paste code to make things easier.

The result

Alexa’s magical mindreader that will amaze and entertain. This tutorial will cover how to get a custom Amazon Alexa skill up and running. You’ll be introduced to the tools, learn how to configure a new skill and and how to tie the skill to your custom function you set up on AWS Lambda. Most of all you’ll see how fun and addicting building Alexa skills can be.

What you’ll need

The steps we’ll be walking through all involve using your browser. You will want to create three browser tabs. One for each of the following:

At first glance, the below steps look quite lengthy and indeed there are quite a few things to do to get up and running. However, carefully following the steps will save you tons of time compared to venturing on your own. The steps below typically take only about 30 minutes. So settle in for short while, carefully follow the steps and at the end you’ll be much further ahead than if you spent the whole day hacking your way through by yourself.

Step 1: Define your skill at developer.amazon.com

We start by defining our new skill on the Amazon developer site. Go to developer.amazon.com and click the Sign In link on the top right. When you’re asked to sign in you should use your Amazon login credentials. That way, the skills you build will automatically be available to your Alexa devices (if you have any).

If you don’t have a developer account yet you will be asked to fill out some information before proceeding. Finish filling out the required information and then click on the Alexa tab.

Next, click on the Alexa Skills Kit Get Started button.

Then on the following page click the Add a New Skill button on the right towards the top.

Now we can begin filling out information about the skill we are going to create. There are three skill types to choose from. We are going to completely control the skill so select Custom Interaction Model. The other options, Smart Home and Flash Briefing, gives you less control over the user’s experience with a trade off of development simplicity but are very specific in nature. In our case, we don’t want to control a home device or create a news briefing, we want to create an amazing mind reading skill. So let’s name our skill “mindreader”. A user will activate the skill by referencing it when speaking to Alexa. For example:

“Alexa, load Mindreader”
- OR -
“Alexa, start Mindreader”

Hit Next once you fill in the form.

Step 2: Define your “Intents” and “Utterances”

An intent represents an action that is called based on what the user says or “utters”. Essentially, intents are functions. Intents can optionally have arguments called slots. We specify all of our intents in a JSON structure called the intent schema. Go to the github repository and copy the code from the intents.txt file. Paste the code into the Intent Schema box.

We will ignore the Custom Slot Type values for now and move down to Sample Utterances.

Utterances are the words or phrases our users will speak that we want to map to our intents. For our mindreader skill we are going to keep things simple and instruct the user to only say “ok” or “again”. We are going to tell Alexa to run the intent called “ok” when the user says “ok” and run the intent “again” when the user says “again”.

The way we tell Alexa what action to take based on user’s spoken words is by defining utterances. When we define an utterance we first identify the intent followed by a space and then the word or phrase we expect the user to say. For example, we might have an intent called playagain and maybe we expect the user to say “please play again”. The utterance would look like this: playagain please play again. For our mindreader skill we have two intents, again and ok. Let’s keep things simple and instruct the user to simply say “ok” and “again”. So in the Sample Utterances box you can simply enter:

again again
ok ok

Or you can copy the text from the github repository and paste it in.

After entering the utterances, click the Next button.

Now we are going leave developer.amazon.com and create the function, or API, that Alexa will call when our mindreader skill is invoked.

Step 3: Create and host your skill’s code at aws.amazon.com using AWS Lambda

Next, we need to configure the storage location for our skill. When a user speaks to an Amazon device and says “Alexa, load mindreader” an event is triggered to call the configured API for the skill. The easiest way to build your cloud-based API is by using AWS Lambda, an Amazon Web Services offering that runs your code only when it’s needed and scales automatically, so there is no need to provision or continuously run servers.

To get started, open a new tab in your browser and go to aws.amazon.com. Click on the “Sign In to the Console” button in the top right.

Use the same email or mobile number and password you used in step 1to log in.

Once you are logged in you will land on the “services” page. Here you want to click on “Lambda”.

We are going to create a Lambda function that will contain the code for our mindreader skill. Part of configuring this function is to identify the trigger, or source, of the API request. In our case the trigger will be from Alexa. In order to have Alexa as a trigger option you must set your your region to one that supports Alexa. Currently there are only two that support Alexa. Click the region dropdown in the top right nav bar next to your name and select either US East (N. Virginia) or EU (Ireland).

Now click the “Create a Lambda function” button.

You will be presented with a list of templates in the form of boxes. Click on “Blank Function”.

Here is where you identify the trigger, or where the request will be coming from. First click the dotted box, then select “Alexa Skills Kit”. After selecting “Alexa Skills Kit”, click the “Next” button.

Now we will name our Lambda function. I prefer to name my function the same as the name of the skill I created in step 1. In our case, the skill name is mindreader so let’s name our function the same. And then at least put the name of the function in the description field as well if you don’t feel like being more descriptive. For runtime, select Node.js. It will probably be defaulted to the latest version offered which at this time is 6.10.

Next we will identify the code for our function. If your code is simple and doesn’t include any external packages you can use the inline editor to either write your code from scratch or copy and paste your code in. In our case, we are going to use an external module called “alexa-app” that we will import into our code. So we want to select “Upload a .ZIP file” from the dropdown.

Now open a new browser tab and go to the github repository and download the mindreader.zip file to your computer. When complete, go back to the AWS console tab in your browser.

Click the “Upload” button and upload mindreader.zip from your computer.

Scroll down and enter “mindreader.handler” in the “Handler*” text box. An important note here, the name of the handler must match the name of the zip file.

For the “Role*” dropdown, select “Create a custom role”.

A new screen will display. It should look like the screenshot below. Just click the “Allow” button to accept the new role.

Now your screen will look something like this. Click “Next”.

The next page will summarize the selections you just made. At the bottom of the page click the “Create function” button.

Getting your Amazon Resource Name (ARN)

Your new function will be created and will be assigned a unique identifier called the Amazon Resource Name or ARN. At the top right, copy the unique ARN to your clipboard.

Step 4: Link your Alexa Skill to your Lambda Function

Go back to your developer.amazon.com tab in your browser. You should be on the “Configuration” page. This is where you will link your skill to your function. Select the “AWS Lambda ARN (Amazon Resource Name)” radio button. Check the “North America” check box and paste your ARN that you copied from your Lambda function into the text box under “North America”.

Click the “Next” button in the bottom right and your changes will be saved and you will be taken to the Test page.

Step 5: Test your new skill with the Service Simulator

Congratulations, your new skill is configured and ready for testing. You are now on the “test” page where you can simulate interacting with an Alexa device.

Go down to the “Service Simulator” section and type “load mindreader” in the Enter utterance text box and then click the “Ask mindreader” button. Doing this simulates a user speaking to an Alexa device and saying “Alexa, load mindreader”. After clicking the button you will see code show up in the Lambda Request and Lambda Response boxes.

Click Listen in the bottom right of the Lambda Response box to hear how Alexa will respond to the user. Follow the instructions you hear from Alexa and type “ok” in the Enter Utterance text box. Again, click the Ask mindreader button to simulate a user speaking to Alexa. Click Listen to hear Alexa’s response. Repeat until you have gone through all of the skill’s instructions.

Step 6: Try it out on your Alexa device

Now you’re ready to give it a try on your Alexa device. Just begin by saying “Alexa, load mindreader”. Show off your new Alexa skill to your friends and family, they’ll be amazed how Alexa can read their mind.

Conclusion

You now have the foundation setup for building your own Alexa skills. Next, you’ll want to learn all there is to know about writing javascript for your skill: what’s required, how to maintain state with session variables, how to incorporate audio, what SSML is and how to use it, error handling, debugging tools and more. To get started have a look at index.js. Stay tuned for the next tutorial that digs into the code where you will learn the techniques to create your own custom skill.

Useful Links

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.