Alexa skill tutorial: How to write your first voice-assistant app

“Alexa, what’s the weather forecast?” “Alexa, when is the next New York Giants game?”

There are thousands of things you can find out by asking Alexa, the voice service behind Amazon’s popular Echo, Dot, and other hardware. And, if there’s not already a “skill” that does what you want, it’s not that hard to build your own. In this tutorial, I show you how to create a staff directory so Alexa can look up members of a team.

Defined: What is an Alexa skill

In some ways, an Alexa skill is similar to a web application: There’s a front end and a back end. When interacting with a skill, users speak to Alexa-enabled hardware as the front end instead of typing into a browser. Alexa developers create code for a skill’s voice user interface in Amazon’s developer console, as opposed to in HTML and CSS on a web server.

How to set up Alexa skills

But the front end is just setup. To make Alexa respond appropriately to requests, back-end code is needed as well. A skill’s back end can be hosted on pretty much any HTTPS web service. However, when first starting out, it’s simplest to use a software development kit (SDK) or framework to write the code and then host it on AWS Lambda. Amazon’s Alexa Skills Kit SDK is available for Node.js (JavaScript) and for Java. There’s also a non-Amazon-created Python framework, Flask-Ask. In addition, AWS Lambda supports C# for Alexa skills.

Amazon offers a $100/month AWS credit for public skills, and I’ve yet to incur a charge for my still-in-development skills. So unless you create the Angry Birds of Alexa skills, odds are you can use AWS Lambda for free to host your skills.

Step 1: Start with an Alexa skills template

The easiest way to write your first skill is to use a template and then tweak it so it does what you want.

One of the most universally useful templates Amazon has published so far is its team-lookup skill. The skill lets you request things like “Find me an Alexa evangelist in Boston” and “What is Amy’s Twitter handle?” But you can easily customize it to make other corporate directories.

And because skills can remain private, usable only by Alexa devices connected to your Amazon account, you can also use the template to create a personal Alexa phone directory at home. Or, you could create an internal department directory in your office for devices set up to access the same corporate account.

This tutorial’s Amazon team-lookup skill is written for Node.js and AWS Lambda. Here’s how to implement it.

Step 2: Set up developer and AWS accounts

Your next step is setting up accounts at both the Amazon developer console and Amazon Web Services if you don’t have them already. Both are free, but you do need to enter credit-card information for the AWS account.

If you’re not JavaScript developer and thus don’t have Node.js on your computer, you’ll probably want to download and install it from the Node.js site. The current installation should also include Node’s package manager, NPM. It’s not required for most basic skill-writing and setup like this directory, but it will be necessary if you work on more-complex skills.

Step 3: Download Alexa skills template code

Next, download the team-lookup code from Amazon’s GitHub repository. You can do this with git clone https://github.com/alexa/skill-sample-nodejs-team-lookup.git if you’ve got Git installed on your system. (If not, download Git from GitHub.)

If you used Git, you should see a new directory named skill-sample-nodejs-team-lookup. (If you unzipped the team-lookup code manually, you’ll know where you unpacked it). Move to that directory, where you’ll see two important subdirectories: speech-assets and src. There’s also a step-by-step folder that you can refer to for help with setting up the skill.

The speech-assets folder has code for your front end. It has one file, interaction-model.json, that describes what people can say to Alexa to make requests when using the skill. You need to enter this code into Amazon’s developer console.

The src folder contains back-end code that handles users’ requests, and you will upload it to AWS Lambda later.

Step 4: Start your Alexa skill in the developer console

Log into the Amazon developer console, click the Alexa option on the top navigation bar, and choose the Get Started button for the Alexa Skills Kit. (There’s a second option, Alexa Voice Service. You don’t want that.)

Next, click the Add a New Skill button at the top right of the page. This starts the process of setting up a new skill. Keep the Skill Type as the default for Custom Interaction Model. For language, choose American English, British English, or German.

You’re then asked for a Name and an Invocation Name. What you enter for Name is how this skill appears in Amazon’s skills directory if published and in users’ Alexa apps. Invocation Name specifies what a user says to trigger the skill, such as “Ask invocation name for whatever” or “Get whatever from invocation name.” The skill name and invocation name can be the same, but they don’t have to be.

Tip: When picking an invocation name, think short and easy to say. For example, “Boston guide” might be a good invocation name. “Boston events calendar,” less so because users may tire of having to say “Ask Boston events calendar.”

Invocation names have to be at least two words (one of which can’t be something like “the”), and they definitely can’t include important Alexa launch words like “ask” or “tell.” If you’re running into problems creating an acceptable invocation, check out Amazon’s full Alexa skill-naming guidelines.

IDG

Click Save and then Next to choose whether to use the new, more graphical Skill Builder Beta or the older format where you have to cut and paste code into a few form fields. I suggest trying the new Skill Builder Beta, because it also includes a code editor.

IDG

[The article continues after the following sidebar]

Step 5: Set up Alexa skill’s voice-interface variables

Open the interaction-model.json file (it’s in the speech-assets folder) with the text editor or IDE of your choice. You’ll see a JSON file with more than 300 rows that defines intents and slots, including some acceptable values. You may need to customize some of these to make this JSON file usable for your own real-world skill instead of for looking up Alexa evangelists.

When using a template, though, it’s a good idea to first set it up exactly the way it’s initially written and make sure it runs properly before you start tweaking code. Here’s how to set up the team look-up skill to find Alexa evangelists:

1. Click the Code Editor (in the left navigation). Delete all the default text.

   IDG

2. Copy all the text in the interaction-model.json file, and paste it into the code editor, or just drag and drop the file into the drag-and-drop area. Click the Apply Changes button at the top right, and then the Save Model button in the top navigation bar at the left.
3. After saving, click the Build Model button right next to the Save Model button. Building the model may take a minute or two. (If you get an error message, try again. An Amazon developer told me that the beta is still occasionally buggy).
4. Click the Dashboard link on the left navigation (just above the Code Editor option). You should see that you’ve got 12 intents (seven built-in and five custom) as well as six slot types (two built-in and four custom).

Step 6: Connect the Lambda back end for your Alexa skill

After you’ve saved and built your model, click the Configuration option in the upper navigation bar. That exits the Skill Builder Beta and brings you back to a configuration page for your skill in the Developer console. This is where you start setting up the back end and connecting it to your skill definitions.

Head to aws.amazon.com in a new browser tab (you’ll want to keep your Amazon Developer Console tab open as well) and sign into your console by clicking Sign-in at the top right.

In the black navigation bar at the top right, next to your account name, you should see a geographic area such as N. Virginia; that indicates the datacenter that will host your Alexa skill. Because most AWS datacenters don’t yet handle Alexa skills, make sure to se the US East datacenter (the N. Virginia option).

Select the Lambda service, then click the Create Function at the top right of the page. When asked to select a blueprint, choose alexa-skill-kit-sdk-factskill. Search for “Alexa” if you have trouble finding that blueprint.

IDG

If you see a warning about a function containing external libraries, don’t worry about it: Your function should contain an external library (the Alexa SDK); the blueprint won’t overwrite what you need.

Note: The interface for creating a Lambda trigger can be a little confusing. You need to click on the dashed, empty square to get a dropdown list. Choose Alexa Skills Kit from that dropdown and then click Next at the bottom right.

IDG

Enter a name for your function, which sets the title for the back-end logic behind your skill. You don’t have to include the name of your skill in the name of the function, but doing so can be helpful for finding it again if you end up coding many skills. Leave the default at whatever Node.js version appears.

Below that is the area for your Lambda function code, prepopulated with default code. Delete all that code. Replace it with the function code from the Team Lookup template. To get that function code, head back to those files on your local system and open the index.js file in the src subdirectory of the skill-sample-nodejs-team-lookup directory.

You’ll see several areas in that file marked “TODO.” Those are some of the areas that you’ll need to change to make the skill work with your own data (although not necessarily all). First, though, get the skill running with the default data.

Copy the index.js code and paste it into the Lambda function code box, leaving Edit Code Inline as the code-entry choice.

Before this code can work, it needs permission to execute functions. If this is your first Alexa skill, you need to set up a role for Alexa. Scroll down to the Lambda Function Handler and Role section. Leave the Handler as index.handler. Under Role, choose Create a Custom Role. A new window should open for you to create the new Identity and Access Management (IAM) role.

IDG

Leave defaults for the IAM role as lambda_basic_execution and Policy Name as Create a New Role Policy, then click the Allow button below. You can reuse that IAM role for other skills, too.

You should now be back to your previous page. Select an existing role and the new lamba_basic_execution as your role. Leave everything else as is (no need to change any of the advanced settings), and click Next. You’ll see a summary of your new Lambda function options. Scroll down to the bottom and click the orange Create Function button.

At the top right, you’ll see an ARN (Amazon Resource Name) number. (I’ve blacked mine out in the screen below.)

IDG

Copy that, starting with the arn:aws through the name of your function (but not with the ARS - before it). Then switch back to the Amazon developer console. (If you see another warning about external libraries, once again ignore it.)

Under Global Fields where it says Endpoint and Service Endpoint Type, click the radio button next to AWS Lambda ARN (Amazon Resource Name), the recommended option. Paste the ARN string into the Default group. You can also provide a geographic option—North America for the N. Virginia datacenter you selected earlier—and then paste that ARN code into the text box that appears as well. Leave everything else at the default (this skill doesn’t need account linking or any other extra permissions), then click Save and Next.

Step 7: Test the default Alexa skill

You should now be at your skill’s test page. There are a few ways you can test:

• If you have an Alexa device nearby that’s connected to the same Amazon account you used to develop the skill, the directory skill should already be available on your device. Say “Open “ and the name of your skill, and it will tell you what to do.
• If you want to voice test but don’t have Alexa hardware handy, you can try a web-based third-party testing tool at Echosim.io. You’ll need to connect your Alexa account to the service. There’s also a separate, third-party app called Reverb available for MacOS, iOS, and Android. However, if there’s a problem with your skill, you won’t know if the problem is the third-party platforms being flaky or something wrong with your code.
• You can do text-based testing on this Amazon developer console test page, which is your best way to track down errors. Scroll down to the Service Simulator and type in something the user would say after your skill is opened. help is often a good starting point, just to see if it’s working at all. The help text will give you a suggested command to try, which you can type into the Enter Utterance box (replacing help).

IDG

With the Service Simulator, you’ll see the code that’s sent to your Lamba function and the code that’s returned. If you click the Listen button below the returned code, you’ll hear how the response sounds if Alexa speaks it. Next, try typing in the suggested query who is paul cutsinger. And so on.

If your skill isn’t working, you’ll usually see a generic warning “The remote endpoint could not be called, or the response it returned was invalid.” For more helpful information about what went wrong, first copy all the code in the Lambda Request box. Then head back to your skill’s Lambda function in your AWS console.

Under Actions, choose Configure test event. For the sample event template, pick Alexa Start Session (there are a lot of possible sample events; you may need to use the search box). Delete the default code and paste in the code you copied from the Lambda Request box between the existing braces ({}) in that box. Click Save and Test. If there’s still an error, you should see a Details dropdown, hopefully with more information that will help you debug. There should also be a link to a cloud log, which may have more information still.

Step 8: Customize the Alexa skill

It’s pretty straightforward to keep everything the same in this skill except for using your own data and tweaking some phrases that Alexa says to the user.

Many Node.js skill templates (including this one) hard-code data in the index.js file. Using your own data means swapping in your data in JSON format. Make sure to use the same exact category names as the original data, including whether they’re uppercase or lowercase. If the sample data values are all lowercase, make sure yours are as well—that can matter (and in fact does matter for this skill).

For data that changes often, hard-coding in the index.js file isn’t very practical. Amazon has some examples of how to read in data from a static file on its S3 storage service or NoSQL database DynamoDB.

You’ll find text for Alexa’s response messages in the index.js file. Doing a text search for “message” may help you locate most of them. This particular skill has Alexa talking about finding “evangelists,” something that you’ll probably want to change. Search for those words in the index.js file.

If you want to change the structure of a skill template, such as creating a directory with phone and email information but not LinkedIn or GitHub, I advise first cataloging all the features of the skill as it exists. Go to the Developer Console and write down all the slots (variables) and intents you see, and next to each whether you will keep it as is, change it, or delete it. For the intents you’re keeping, check whether the sample utterances work for your use case or if you need to add or delete some.

If you are adding a slot, you need to assign it a slot type, either built-in or custom. If you’re adding an intent, it needs sample utterances and may need slots.

If you add or change slots and intents, the index.js back-end code needs to change as well. The second section of this skill’s index.js file warns: “CAUTION: Editing anything below this line might break your skill.” However, if you’ve changed category names, not editing code below that line will break your skill.

Each customization is different, but here’s some general advice: It’s a good idea to search for the name of every slot and intent within index.js, whether you’ve deleted it, changed it, or kept it as is. You can find some interesting things in the code that way. For example, if you are keeping github and didn’t search for it, you wouldn’t have seen this:

if (slots.infoType.value =="git hub"){
           infoTypeValue ="github";
           console.log(“resetting gith hub to github”);
      }

which changes spoken “git hub” to “github” (because Alexa might see “github” and assume it was pronounced “gith-ub” instead of “git-hub”). That’s useful code if you’re adding a slot that also has pronunciation problems.

Searching for each slot name also uncovered this code at the end of the index.js file:

function isInfoTypeValid(infoType){
      var validTypes = [“git hub”,”github”,”twitter”,”linkedin”];
      return isInArray(infoType,validTypes);
 }

You don’t have to be a JavaScript expert to see that the function is checking to ensure the infoType is git hub, github, twitter, or linkedin. If you added or changed an infoType without also updating this function, your new category will be deemed invalid and thus won’t work..

If you’re adding an intent and aren’t a Node.js expert, the best advice I can offer is to find a template with an intent that accomplishes a similar goal, then adapt it.

Step 9: Publish your Alexa skill

If you want to make your skill public, the Publishing Information page that comes after the Test page in the developer console has most of the information you need.

Published skills need info such as a short and long skill description, sample utterances, and small and large images. Note that when Amazon says it wants the small icon to be 108 by 108 pixels, that’s an exact requirement, not an estimate—I was rejected for being off by just a couple of pixels. You’ll also have to fill out the Privacy & Compliance page after the publishing info page. Submit and then wait to hear if you’re approved.

If you want to create private skills for within your organization, Amazon offers Alexa for Business, with enterprise features such as managing users annd device locations. Monthly pricing starts at $7 per enrolled user and $3 for shared device.

If you just want your skill to be private among some family and friends, you can go through the publishing process until actually submitting it for review — including adding an image — and then create a private beta test and invite users.

A different process for Alexa skills: command line

Finally, you may soon find it cumbersome to manually upload or copy and paste files to both the developer console and Lambda, not to mention having to switch between browser tabs for various tasks. That’s why Amazon recently released its Alexa Skills Kit Command-Line Interface (ASK-CLI) tool. Note: You’ll need Node.js to install it locally.

Resources for creating Alexa skills

This tutorial should have helped you get your own corporate directory or personal phone book up and running on Alexa. If you’d like to continue your skill-building journey, here are some more resources that can help:

Alexa skill voice design

• Amazon design tools: Advice and worksheets from Amazon on designing a voice interface.
• Voice design basics: A two-minute video from Amazon Alexa developers giving an overview of voice concepts.

Additional Alexa skill tutorials

• Developing Alexa Skills: Amazon teamed with tech instructors Big Nerd Ranch for a six-part video tutorial on building Alexa skills. (Note: If you’ve got an Alexa device in the room, turn off its microphone or put on headphones if you don’t want it to keep getting triggered from the video.)
• Python tutorial: Amazon’s quick start for Python.
• Amazon also has on-demand webinars and third-party training videos in its developer console (some of the external videos require payment to watch a full course).

Alexa skill templates

• Local recommendation guide:  Amazon uses this in some of its beginner “developer day” sessions. It features how to return random results from a group of acceptable responses.
• External calls: This is Amazon’s template for how to call a web API in an Alexa skill. Also see this non-Amazon example of pulling weather information from Weather Underground by engineering physicist Kevin Loeffler.
• Google calendar reader: Be warned that the Node.js iCal parser used in this skill (separate from Alexa-specific code) doesn’t handle repeating events.
• Trivia: This is a question-and-answer trivia skill, by Amazon.
• Quiz game: This keeps score in addition to asking trivia (or other) questions. It also uses speechcons, which give Alexa more expressive speech for some words.
• Help following a (cooking) recipe: The actual skill may not be that compelling, but this skill demonstrates how to save and access user state—people can stop using a skill and then pick up where they left off.
• Pet match: This skill prompts the user for multiple pieces of information and then tries to find the best match by using an API.