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

This step-by-step developer guide show you how to customize an Amazon Alexa skill to make your own directory or phone book.

Executive Editor, Data & Analytics, InfoWorld |

Alexa skill tutorial: Build your own team directory — Thinkstock

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

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.

[The article continues after the following sidebar]

Understanding voice-interface terms

The initial Skill Builder Beta screen may look a little confusing if this is your first time creating a skill. What’s an intent? What’s a slot type? But once you’re clued into the jargon, it’s fairly straightforward:

Intent: Basically, this is what a user wants Alexa to do. If you ask your Echo, “What’s the weather forecast?”, getting the forecast is an intent. Intents need what are called sample utterances, so Alexa knows what phrases and sentences correspond to a particular request. “What is the weather forecast?” should trigger a different intent (tell me the forecast) than “What time is it?” (tell me the current time).

Amazon has created some built-in intents, such as launch (open the skill), help (respond with a help message), and stop (exit the skill). To do anything interesting, you’ll usually create some custom intents, too. Each custom intent needs at least three sample utterances—what a user can say so Alexa knows they are asking for that intent. For weather, sample utterances could be “What is the weather forecast?”, “What will the weather be?”, and “Tell me the forecast.”

Slot: This is what many programming languages call a variable. If the user asks, “What’s the weather forecast for Boston?”, city would be a slot. “What’s the weather forecast for Boston on Saturday?” has two slots: city and forecast date. So, you might now think of the intent as “What is the forecast for city on forecast date?”

Slot type: This defines acceptable values for a slot, similar to a class in some programming languages. Amazon has multiple built-in slot types—not just lower-level choices like numbers or dates, but also options such as corporations, airlines, foods, and US and British cities. There are currently 87 built-in character slot types and five for dates and numbers. The date slot type recognizes common-language words such as “tomorrow,” “Saturday,” and “next week,” and it turns them into dates or date ranges for you. You can also define your own slot types with a list of permitted values.

On the back end, intent handlers determine when a particular intent has been triggered by a user’s words. Once that happens, function code for that intent implements the user’s intent and send back results, such as generating and returning a weather forecast.

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:

Click the Code Editor (in the left navigation). Delete all the default text.
IDG
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.
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).
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.

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.

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.

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

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

1 2 Page 1 Next

Page 1 of 2