How to Build Your First Alexa Skill: 5 Steps to Get Started

Jedidiah Esposito Sep 04, 2018

Alexa enables customers to interact with technology in the most natural and intuitive way—with their voice. Today, developers can build voice-driven Alexa capabilities, called skills, to engage and delight their customers. Using the Alexa Skills Kit, which is a collection of tools and templates, anyone can leverage Amazon's pioneering work in conversational artificial intelligence (AI) and natural language understanding to build voice experiences faster and easier.

With voice, it doesn't matter whether you've written best-selling mobile apps or have never written a line of code. With the Alexa Skills Kit, you can start building for voice today. To help you get started, here's an overview of the skill-building process and the five steps you can follow to design, build, and publish an Alexa skill.

Step 1: Design Your Voice Experience

After you've created your Alexa developer account, you may be tempted to start tinkering with the Alexa Skills Kit. While it's great to have your account up and running, the first step to build a skill doesn't actually require any tools at all! That's because you should design the experience before you build it.

The more thought and effort you put into developing your voice idea and designing the experience, the more successful it will be. The design process can take a few hours or a few weeks—it depends on the scale and complexity of your vision.

First, make sure your idea is a good fit for voice. The best voice ideas are those that naturally lend themselves to conversation. Litmus test your idea with the following criteria:

  • Be adaptable. Will the skill make life easier for users by allowing them to speak naturally?
  • Be personable. Will the skill remember the user's preferences in order to help them more quickly?
  • Be available. Will the skill allow users to lead the interaction?
  • Be relatable. Will the skill cooperate with the user, working with them to accomplish something?

For example, a skill that navigates through a slide presentation sounds fantastic, but depending on implementation, it may or may not meet these criteria. Will the user simply be “clicking” through menus with their voice? Or will the skill allow them to ask to see specific slides in the same way they might ask a colleague?

Next, identify your users. You should have a clear understanding of who will be using your skill and how your skill meets a specific need or objective they have. Consider what your users want. These "wants" will become your skill's intents. How will your users converse with your skill? Are they teenagers immersed in the latest pop culture? Or are they sailors used to maritime metaphors? You'll need to know ahead of time so that you can anticipate the language they'll use (their utterances) and tailor the experience.

When thinking through who's going to use your skill, ask the following

  • What are these people like? (background, interests, motivations, etc.)
  • What do they want from my skill?
  • When are they most likely to use my skill?
  • Will they be using slang or jargon of any kind?

Then next part of the design process is writing a script. Scripts show the conversation between the user and Alexa, like in a movie or play, and are a great way to determine how conversation will flow. When writing, you're essentially scripting an entire conversation, which can go in almost any direction. It can be difficult to anticipate every possible direction a conversation could take, so we recommend starting with “the happy path,” which is the best-case script in which Alexa responds exactly how the user wants and creates a delightful user experience.

After you've written your script, grab a friend and read out the dialog to make sure it sounds natural and conversational. As you read, take note of the situations in which your friend wanted to go off script or to say something unexpected. Check out the voice design guide for more tips on writing scripts and sample dialogs.

The last part of the design step is to use your script to identify the language that will define your voice interaction. These language elements include:

  • Intents, which represent what users can ask your skill to do. It's important to think of these less as “what your skill can do” and more “what users intend to get from your skill.” Your skill might help users to plan a trip, get a status, tell a joke, or attack a monster—these are intents.
  • Utterances, which are the sentences a person says to Alexa. They're made up of keyword commands and natural speech sounds like filler words.
  • Slots, which allow people to specify variable parts of an utterance, for example city or date. Slots are common in task and information-focused skills.

Check out the voice design guide for more information about writing intents and utterances.

Step 2: Build Your Voice User Interface in the Alexa Developer Console

After you've designed the experience, it's time to start building. You’ll use the Alexa Developer Console to create the voice user interface model, or VUI. This is also known as your front end interface or what your users will interact with when they use your skill.

You will construct your VUI using the intents, utterances, and slots you uncovered during the design work you did in step 1. Take a look at the Tech Docs: Create Utterances, Intents, and Slots to learn more.

While it's definitely one of the most flexible and powerful tools available, the developer console isn't the only way to build your VUI. If you're a seasoned developer you may prefer, to use the Alexa Skills Kit Command-Line Interface. With this tool you can create the basic architecture for your skill locally, work on both the front-end and back-end code, and then deploy to the developer console and AWS Lambda with a few simple commands.

If you're new to coding, you can start with Blueprints to familiarize yourself with the basics before graduating to the template tutorials we provide on GitHub. The voice model for each template can be found within [models/{region}.json]. You can actually copy and paste this JSON directly into the developer console to get started faster!

Step 3: Build Your Back End to Power Your Skill

When you use a website or an application, there's a lot going on in the background that you can't see. The front-end interface is separate from, but connected to, a back end that the user only experiences indirectly. Most of the utility of the site or app actually happens in the back end and is then shown or delivered in the front end.

Your Alexa skill will work in much the same way. Your back end will receive information from the user as they interact with the front end you created in step 2. Once the information arrives, it's up to you to decide what your back end should do with it and how to respond to users. There are a few different places your back end can live, and a few different tools and programming languages to choose from when building it.

If you're not someone who codes, start small. We have a variety of templated tutorials on GitHub that contain both the front end (models/{region}.json) and back end (lambda/custom/index.js) information for basic skills. By following the steps, you can have a basic skill operational within an hour without changing the code much.

If you'd prefer not to code at all, that's okay. You can still build a skill! You can create personal skills or prototype rapidly without code using Blueprints. Or you can take advantage of third-party tools like Voice Apps that let you build skills quickly without writing code.

If you're comfortable with code or following one of our GitHub tutorials, the best place to start creating your back end is with AWS Lambda. You simply upload the code for your Alexa skill to a Lambda function and Lambda does the rest, executing it in response to Alexa voice interactions and automatically managing the compute resources for you. Learn more about hosting your code with AWS Lambda. You can also leverage our ASK Software Development Kits (SDKs) for Node.js, Java, and Python (beta) to make the development experience easier.

Of course you don't have to use Lambda or AWS at all. Your front end can be configured to connect with any HTTPS endpoint for your back-end logic.

Step 4: Test and Optimize

If you want your skill to be successful, you'll need to test it. There are two basic categories of testing: functional and user experience. Functionally, you'll need to put your skill through its paces. You'll want to do this both in preparation for publishing and over time after your skill is released to the world. For user experience testing, you'll want to observe and collect feedback on ways to improve the interaction between your skill and the people who are using it.

For both types of testing, the developer console should be your first stop. It provides tools that allow you to use your skill the way you expect customers to. Under the Test tab, you can type or use your voice to interact with your skill. For example, did you try voice and get a failure, but typing worked? Something may be wrong with your model. For each turn of an interaction in the testing tool, you can dig into the JSON requests to diagnose issues. If you like, you can even compose JSON requests from scratch to be dispatched to your back end.

Beta testing is another great way to get feedback on your skill before submitting it for publication. Getting real users in front of your skill before it is available to the public gives you an opportunity to collect feedback about what works, what doesn’t, and make improvements that ultimately lead to a better experience. With voice, especially, people are without question going to try interacting with your skill in ways you'd never expect. Depending on the situation, you may want to make changes based on what they do.

If you're using Lambda, you can test whether your back end code is executing (functional) correctly by modifying a built-in test event or creating one from scratch. You're also able to view Amazon CloudWatch metrics and logs for your Lambda function's execution. These are especially handy for tracking down errors and mistakes with any API calls your skill might make.

Once your skill is live, you'll want to run some checkups on a regular basis. Rather than waking up early every morning to run a battery of tests, you can leverage test automation. Here are a few resources on skill testing:

Step 5: Submit, Get Certified, and Publish

Like you, Amazon wants to ensure that the skills available to customers meet a certain quality bar. They should be engaging and work the way they say they will. To ensure this is the case, skills undergo rigorous testing and certification prior to being published to the Alexa Skills Store.

To make sure your skill is certified and available to customers as quickly as possible, there are a few key things you should focus on before submitting:

  • Make sure that your sample phrases accurately reflect the ways customers will interact with your skill. Customers will read these examples before using your skill. If they're wrong or even slightly wrong it's possible they'll simply move on.
  • Get your short and long descriptions right. The long description for your skill is where you can be descriptive. Explain to customers the problem your skill solves or what's fun about it. Think from the customer's perspective and make sure to use simple, clear language. The short description is also important to make your skill more discoverable. If customers want to do something that your skill is good at, but don't have it enabled, Alexa will actually leverage your short description to recommend your skill. For this to work well, the short description needs to make sense, and flow naturally as something Alexa might actually say.
  • Include keywords in your skill description that match the key phrases customers are likely to search when looking for your skill. We recommend doing thorough keyword research to understand which search terms your audience uses. More tips for writing a keyword-rich skill description here.
  • Ensure you include clear instructions for the certification team. If your skill has an interesting feature you'd like to call out or an in-skill product you'd like them to test purchase, let them know. You'll also need to include proof of rights to use any intellectual property your skill might include.

Once you've submitted your skill, the certification team will perform a battery of tests and double check all of the information you've provided for its listing in the Alexa Skills Store. If your skill doesn't pass certification immediately, don't get discouraged. Take the team's feedback and make corrections or adjustments they recommend. Their feedback will ultimately help you enhance your skill and deliver a better experience to your customers. Check out the certification guidelines in the tech docs here for more information.

Once your skill passes the certification requirements, it will be available for customers to engage with from the Alexa Skills Store. Next, we recommend promoting your skill to eager Alexa users to drive usage and traffic.

Give Your Vision a Voice

Whether your skill is something that redefines voice or something simple that solves a problem, publishing an Alexa skill is something to be proud of. Follow these steps and you'll be well on your way to reaching and delighting new audiences via voice. For more tips and guidance along the way, check out these additional resources:

Build Your First Skill, Get a T-Shirt

Bring your big idea to life with Alexa and earn perks through our milestone-based developer promotion. US developers, publish your first Alexa skill and earn a custom Alexa developer t-shirt. If you're not in the US, check out our promotions in Canada, the UKGermanyJapanFranceAustralia, and IndiaLearn more about our promotion and start building today.