Tutorial: Build Your First Alexa Skill in the Developer Console

In the following tutorial, you use the Alexa developer console to create a simple Hello World skill that uses the custom voice interaction model. For an overview of this model, see Understand Custom Skills.

Prerequisites

Before you start, you need an Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.

Steps to build your first Alexa skill

  1. Create a new custom skill
  2. Choose your skill invocation name
  3. Test your skill
  4. Make your skill discoverable
  5. Review privacy and security requirements

Step 1: Create a new custom skill

In this step, you create your custom skill, choose a quick-start template, and then specify hosting for the skill. This configuration helps users and Alexa recognize and interact with your skill.

To create a custom Hello World skill in the developer console

  1. If you haven't already, create an Amazon developer account.
  2. Sign in to the Alexa developer console.
  3. On the Skills tab, click Create Skill.
  4. On the Create a new skill page, provide the following information:
    a. For Skill name, enter Hello World in the box.
    b. For Primary locale, choose English (US).
    c. For Choose a model to add to your skill, choose Custom.
    d. For Choose a method to host your skill's backend resources, choose Alexa-hosted (Node.js).
    e. In the upper-right corner, click Create skill.
  5. On the Choose a template to add to your skill page, leave the Start from Scratch template selected.
  6. In the upper-right corner, click Continue with template.

Step 2: Choose your skill invocation name

In this step, you give your skill an invocation name, build the custom voice interaction model, and deploy the sample skill code. The invocation name enables users to ask Alexa to start an interaction with the skill and to open the skill in the Alexa app.

To assign a skill invocation name

  1. On the Build tab, in the left pane, click CUSTOM > Invocations > Skill Invocation Name.
  2. For Skill Invocation Name, enter hello world.
  3. To save and build your model, click Save Model, and then click Build Model.
  4. To deploy your skill code, open the Code tab, and then, in the upper-right corner, click Deploy.

Step 3: Test your skill

In this step, to verify that your skill responds as expected to user input, you test example phrases and determine if any utterance conflicts exist. Users expect your skill to flow naturally and function reliably.

To test your skill in the Alexa Simulator

  1. Open the Test tab.
  2. To enable your skill for testing, locate Test is disabled for this skill, and then, from the drop-down list, select Development.
  3. To test with voice, in the Will you allow developer.amazon.com to use your microphone? pop-up, select Allow.
  4. In the Alexa Simulator pane, enter open hello world, but omit Alexa from the string.
    Or, to use voice, click and hold the microphone, and then speak an utterance.
  5. If the test is successful, Alexa says, "OK."
  6. Repeat steps 4 and 5 for the utterances hello, help, and cancel.
  7. If the skill doesn't perform as expected, see Troubleshooting.

To ensure that your interaction model has no utterance conflicts

  1. Open the Build tab.
  2. In the left pane, click CUSTOM > Interaction Model > Utterance Conflicts (0).
  3. If any number other than (0) appears next to the term Utterance Conflicts, click the error message for details.
  4. Resolve the conflicts, and then press Ctrl+R to refresh your browser window.
  5. Repeat until you see Utterance Conflicts (0).

Step 4: Make your skill discoverable

In this step, you supply metadata and, if you like, a Hello World logo. Amazon uses the metadata to categorize your skill and help interested users find your content. The skill description and logo appear on cards displayed in the Alexa app and in the Alexa Skills Store. For details and a card example, see Include a Card in Your Skill's Response.

To supply metadata for your skill

  1. Open the Distribution tab.
  2. On the English (US) Store Preview page, in the Public Name box, enter Hello World.
  3. In the One Sentence Description box, enter the following text. 
    Hello World is a perfect way for users to try their first Alexa skill.
  4. In the Detailed description box, enter the following text. 
    Hello World is a classic skill that introduces users to Alexa's text-to-speech capabilities.
  5. Leave the What's New box blank.
  6. In the Example Phrase 101 pane, click More.
  7. One by one, enter the following example launch phrases.
    After each entry, to add a new phrase, click the plus sign (+). 
       Alexa, open Hello World.
   Alexa, ask Hello World to start.
   Alexa, launch Hello World.
  1. In the Category box, choose Social > Communication.
  2. In the Keywords box, enter hello, greetings, introductions, and skills.

(Optional) To upload your own skill logo

If you have logo art of your own, you can upload it in two sizes.

  1. In the Small Skill Icon box, upload a skill logo that is 108 px square, formatted as a .png or .jpg file.

  2. In the Large Skill Icon box, upload a skill logo that is 512 px square, formatted as a .png or .jpg file.

  3. Click Save and continue.

(Optional) To create a skill logo

If you don't have logo art of your own, use the free Alexa Icon Builder to create it.

  1. In a new browser tab, open the Alexa Icon Builder.
  2. In the keyword search box, enter globe, and then click to select the tiny globe icon.
    Globe icon
  3. In the Icon menu at right, to open the color window, click the box next to Icon.
  4. To set the icon color, click Solid color, and then click to choose a color.
  5. Click anywhere to close the color selector.
  6. To choose a background color, click the box next to Icon background, click Solid color, and then click to choose a color.
  7. To choose a border color, click the box next to Icon border, click Solid color, and then click to choose a color.
    Or, to remove the border, move the slider to the left.
  8. To add an icon shadow, click the box next to Icon shadow, and then click to choose a color.
    Or, to remove the shadow, move the slider to the left.
  9. To download the icons in two sizes, click Download.
    Alexa creates logo files for you in the correct sizes, and then stores them in a .zip file.
  10. On your computer, unzip the images file.
  11. In the developer console, open Distribution > Skill Preview.
  12. Drag each icon file into its designated space.

  13. Click Save and continue, and then view your finished icons.

    Globe logo in two sizes (108 px and 512 px), created with the Alexa Icon Builder.

Step 5: Review privacy and security requirements

In this step, you review the policies for your skill and supply the information Amazon needs to test the skill for certification. Your skill must comply with all applicable laws and regulations before it is made publicly available.

To supply privacy, terms of use, compliance, and availability data for your skill

  1. Open the Distribution tab.
  2. Click Skill Preview > English (US).
  3. In the Privacy Policy URL box, if you have a privacy policy, enter a URL, or if you don't, leave the box blank.
    A privacy policy is optional unless your skill links to users' accounts or collects user information. This skill does not.
  4. In the Terms of Use URL box, if you have a terms of use agreement, enter a URL, or if you don't, leave the box blank.
    A terms of use agreement is optional. If you do require consent to such an agreement, however, you must supply it separately for each locale.
  5. On the Distribution tab, click Privacy & Compliance.
  6. Answer No to each question.
  7. Select the Export Compliance check box.
  8. In the Testing Instructions box, enter the following lines. 
    System requirements: None
To begin, say "Alexa, open Hello World."
  1. Click Save and continue.

FAQ

The following frequently asked questions (FAQ) section answers common questions about building your first Alexa skill in the ASK developer console.

Q: What's an invocation name, and how do you choose one?

An invocation name is the name users say to launch your skill. Users can open the skill in one of three ways:

  1. Open the skill directly (User: Alexa, launch Pizzabot )
  2. Make a request to perform an action (User: Alexa, start an order with Pizzabot )
  3. Say the invocation name itself (User: Alexa, Pizzabot )

For details, including length requirements and other considerations, see Choose the Invocation Name for a Custom Skill.

Q: Can a skill be offered in other languages?

Yes. You can offer your skill in as many locales as your skill type supports. For details, see Develop Skills in Multiple Languages.

Q: Can skills be built with the command line interface (CLI) instead of the developer console?

Yes. You can use the Alexa Skills Kit Command Line Interface (ASK CLI) to build Alexa-hosted skills in Node.js, Python, or Java. For details, see Create and Manage Alexa-hosted Skills Using the ASK CLI and Alexa Skills Kit Command Line Interface (ASK CLI) Overview.

Q: What's the difference between a custom intent and a built-in intent?

An intent is an action or task you ask Alexa to complete. A custom intent consists of an intent name and a list of utterances users might say to invoke that intent. Custom intents accomplish specific tasks associated with your custom skill. For example, FindLocalCampsites is a custom intent that helps users locate nearby campgrounds. A user can invoke this intent with utterances such as the following examples.

User: Alexa, find campsites near me.
User: Alexa, where's the best camping spot around here?
User: Alexa, where's the nearest campground?

A built-in intent accomplishes general actions that are common to many skills. For example, you can use built-in intents to stop, start, cancel, or get help. For a list of built-in intents by category, see the Built-In Intent Library.

Q: What's the difference between a skill with a custom voice interaction model and a skill with a pre-built voice interaction model?

In a custom skill, you determine the words and phrases users can say to interact with your skill. In a skill with a pre-built voice interaction model, Alexa defines the utterances for each skill type. A pre-built interaction model, such as one that plays music or turns the lights on and off, is convenient and dependable. A custom interaction model, such as one for finding last-minute travel deals, offers greater flexibility and enables you to a carry out specific intents associated with your skill. The model you choose depends on your needs and the complexity of your skill.

Troubleshooting

Issue: The hosting changes during the build stage

Symptoms

On the Code tab, you get the following error message, and you can't deploy your skill.

Your default endpoint has changed and the code below is no longer hosted by Alexa.

Try this

Click the link Use Alexa hosted endpoint, and then deploy your skill.

Issue: Alexa responds in the Alexa Simulator, but the answer originates from a source other than your skill

Symptoms

You submit a test utterance to which Alexa should be able to respond with a text string from your skill. However, Alexa responds with an answer from another source, such as Amazon Music or another skill.

Try this

You can't override these other answer sources. To report the issue to Amazon, click the Feedback tab in the developer console. As a workaround, change the skill invocation name to something unique.

Issue: An error message says you need at least one custom intent

Symptoms

On the Build tab, in the Errors and Warnings section at the bottom of the page, you get the following error message.

Interaction Model does not include Custom Intents. Add a Custom Intent with at least one Sample Utterance to your Interaction Model.

Try this

  1. Click CUSTOM > Interaction Model > Intents.
  2. Next to the plus sign (+), click Add Intent.
  3. On the Add Intent page, under Create custom intent, enter HelloWorldIntent.
  4. Click Create custom intent.
  5. On the Intents/HelloWorldIntent page, in Sample Utterances box, add the following utterances one by one. 
    hello
how are you
say hello
hello world
hi
  1. Click Save Model, and then click Build Model.
  2. On the Code tab, click Deploy.

Last updated: Sep 08, 2022