Tutorial: Use the Developer Console to Build Your First Alexa Skill

With the following instructions, you can use the Alexa developer console to create a simple "Hello World" skill in about 20 minutes.

Prerequisites

To develop an Alexa skill, you need a free Amazon developer account. Your developer account gives you access to the tools and resources you need to build and publish Alexa skills. For details, see Create Your Amazon Developer Account.

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 skill, choose a quick-start template, and specify hosting for the skill. This configuration makes it easy for users and Alexa to recognize and interact with your skill.

To create a custom Hello World skill in the developer console

  1. Open the Alexa developer console and sign in.
  2. On the Skills tab, click Create Skill.
  3. On the Create a new skill page, enter Hello World in the box.
  4. Accept the default choices on the page, and click Create skill.
  5. On the Choose a template to add to your skill page, leave the Start from Scratch template selected.
  6. Click Continue with template.

Step 2: Choose your skill invocation name

In this step, you give your skill an invocation name. This enables users to open the skill in the Alexa App for Fire OS, Android, iOS, and desktop web browsers.

To assign a skill invocation name

  1. On the Build tab, in the left sidebar, click CUSTOM > Invocations > Skill Invocation Name.
  2. In the Skill Invocation Name box, replace the placeholder change me with the invocation name hello world.
  3. Click Save Model, and then click Build Model.
  4. On the Code tab, click Deploy.

Step 3: Test your skill

In this step, you test example phrases and check for utterance conflicts to verify that your skill responds correctly to user input. Users expect your skill to function reliably and smoothly.

To test your skill in the Alexa Simulator

  1. On the Test tab, in the upper-left corner, click the arrow next to Off, and select Development from the drop-down menu.
  2. In the Alexa Simulator, enter open hello world.
  3. One by one, enter hello, help, and cancel, but omit Alexa, from the string.
  4. If the skill doesn't perform as expected, see Troubleshooting.

To check your interaction model for utterance conflicts

  1. On the Build tab, in the left sidebar, click CUSTOM > Interaction Model > Utterance Conflicts (0).
  2. If any number other than (0) appears next to the term Utterance Conflicts, click the error message for details.
  3. Resolve the conflicts, and then press Ctrl+R to refresh your browser window.
  4. 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. Automated systems use metadata to categorize your skill and help interested users find your content. The skill description and logo appear on cards displayed in the Amazon Alexa App. For details and a card example, see Include a Card in Your Skill's Response.

To supply metadata for your skill

  1. On the Distribution tab, click Skill Preview > English (US), and enter Hello World in the Public Name box.
  2. In the One Sentence Description box, enter the following text.
    "Hello World" is a perfect way for users to try their first Alexa skill.
    
  3. 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.
    
  4. Leave the What's New box blank.
  5. In the Example Phrase 101 pane, click More.
  6. One by one, enter the following launch phrases.
    After each entry, click the plus sign (+) to start a new line.

       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 to appear in two sizes.

  1. In the Small Skill Icon box, upload a skill logo 108px square, formatted as a .png or .jpg file.
  2. In the Large Skill Icon box, upload a skill logo 512px 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, the free Alexa logo maker creates it for you in a few steps.

  1. In a new browser tab, open the Alexa logo maker.

  2. In the keyword search box, enter globe, and then click to select the tiny globe icon that appears in the lower-left corner.

  3. In the dialog box at right, click to open the color window.

  4. Click the square next to the Icon label.

  5. Click Solid color > Icon background, and then choose any color you like.

  6. Choose a border color and style, if any, and a shadow color and style, if any.
    You can remove the border and shadow altogether by moving the slider to the far left.

  7. Click Download.
    Alexa creates logo files for you in the correct sizes, and then stores them in a zip folder.

  8. In the developer console, open Distribution > Skill Preview.

  9. Unzip your images folder, and then drag each icon file into its designated space.

  10. Click Save and continue.
    Your finished logos look something like the following icons.

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

Step 5: Review privacy and security requirements

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

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

  1. On the Distribution tab, click Skill Preview > English (US).
  2. In the Privacy Policy URL box, enter a URL if you have a privacy policy, and leave the box blank if you don't.
    A privacy policy is optional unless your skill links to users' accounts or collects user information. This skill does not.
  3. In the Terms of Use URL box, enter a URL if you have a terms of use agreement, and leave the box blank if you don't.
    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.
  4. On the Distribution tab, click Privacy & Compliance.
  5. Answer No to each question.
  6. Select the Export Compliance checkbox.
  7. 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 your most common questions about using the developer console to build your first Alexa skill.

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

An invocation name is the name users say to launch your skill. Users can open the skill directly (User: Alexa, launch Pizza Bot), or they can make a request (User: Alexa, start an order with Pizza Bot), or they can just say the invocation name itself (User: Alexa, Pizza Bot). For details, including length requirements and other considerations, see Choose the Invocation Name for a Custom Skill.

Q: Can I offer my skill in other languages?

Yes. You can offer your skill in as many locales as your skill type supports. For details, see Offer a Custom Skill in Multiple Languages.

Q: Can I build my skill with the command line interface (CLI) instead of the developer console?

Yes. You can use the Alexa Skills Kit (ASK) Command Line Interface (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 are used to 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 like those listed below.

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 is used to accomplish 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, I get the following error message, and I can't deploy my skill.

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

Try this

On the right side of the message bar, click the link Use Alexa hosted endpoint. Then deploy your skill.

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

Symptoms

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

Try this

Currently, you can't override these other answer sources. To report the issue to Amazon, click the Feedback tab in the lower-left corner of the developer console.

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

Symptoms

On the Build tab, in the Errors and Warnings section at the bottom of the page, I 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. In the left sidebar, 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 the box below Sample Utterances, 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.