How to Set Up Alexa Step-by-Step: A Beginner’s Guide to Creating Your First Skill

Have you ever wondered how to create your own voice-activated applications for Amazon Alexa? It might seem like a complex task reserved for seasoned developers, but the reality is surprisingly accessible, even for beginners. This step-by-step guide will walk you through the process of setting up Alexa to run your very first custom skill. Inspired by a simple math game built for a first-grader to learn number combinations, we’ll explore the fundamental steps to get your own Alexa project off the ground.

Step 1. Accessing the Amazon Developer Portal: Your Gateway to Alexa Skills

The first step in your Alexa skill creation journey is to access the Amazon Developer Portal. This portal is your central hub for managing and building Alexa skills.

1. Navigate to the Amazon Developer Portal by visiting https://developer.amazon.com/home.html.

2. Log in using your Amazon account credentials. If you don’t have an account, you can easily create one.

3. Once logged in, you’ll be greeted by the developer console. Look for “Alexa Skills Kit” and click on “Add a new skill” to begin creating your skill.

Navigating to the Alexa Skills Kit within the Amazon Developer Portal to initiate skill creation.

Step 2. Defining Your Skill’s Identity: Skill Information

After initiating the skill creation process, you’ll encounter the Skill Information section. Here, you define the basic identity of your Alexa skill.

1. Skill Name: Enter a descriptive name for your skill. This name is primarily for your own organization within the developer portal. For our example, we can use “Math Game Tutorial.”

2. Invocation Name: This is crucial. The Invocation Name is the phrase users will speak to Alexa to initiate your skill. Choose a name that is easy to pronounce and remember. For example, you could use “math tutor game.” Users will say something like, “Alexa, open math tutor game.”

3. Click “Next” to proceed to the next step.

Configuring the Skill Information tab, specifying the Skill Name and, importantly, the Invocation Name that users will use to start the skill.

Step 3. Building the Brains of Your Skill: Interaction Model

The Builder Model section is where you define how users will interact with your skill. This involves setting up “intents,” which represent what a user wants to do.

1. In the Builder Model, select “Custom” as the skill type. This provides the most flexibility for creating custom interactions.

2. Amazon provides a user-friendly interface for setting up intents. By default, you’ll see pre-built intents like “CancelIntent,” “HelpIntent,” and “StopIntent.”

3. For our math game, we need to create custom intents to handle user interactions:

   • AnswerIntent: This intent will be triggered when the user provides a numerical answer to the math question.
   • YesIntent: To handle affirmative responses, like “yes” when Alexa asks if the user is ready to play.
   • NoIntent: To handle negative responses, such as “no” or “stop” when the user wants to quit.

4. To create a new intent, click “Add Intent.” For each intent (NoIntent, YesIntent, AnswerIntent), you will need to provide “Sample Utterances.”

   • NoIntent Sample Utterances: Enter phrases users might say to indicate “no” or “stop,” such as “stop,” “no,” “cancel,” “exit,” “quit.” Alexa’s machine learning will learn to recognize similar phrases.

   • YesIntent Sample Utterances: Enter affirmative phrases like “yes,” “ok,” “sure,” “let’s play,” “start game.”

   • AnswerIntent Sample Utterances: For this intent, we want Alexa to recognize any number as a potential answer. Use the built-in slot type for numbers by entering {number} in the Sample Utterances field. This tells Alexa to trigger the AnswerIntent whenever it hears a number.

5. After defining your intents and sample utterances, click “Save Model” and then “Build Model.” Building the model trains Alexa to understand the intents you’ve defined based on your sample utterances.

Defining custom intents such as AnswerIntent, YesIntent, and NoIntent and providing sample utterances to train Alexa’s understanding of user requests.

Step 4. Connecting Your Skill to Code: Configuration and Endpoints

Now that you’ve defined the interaction model, you need to configure how Alexa will connect to the code that powers your skill. This is done in the “Configuration” section.

1. In the “Configuration” tab, you’ll see options for “Service Endpoint Type.” You have two main choices:

   • AWS Lambda Function: Hosting your skill’s code on AWS Lambda, Amazon’s serverless compute service.
   • HTTPS: Hosting your skill’s code on your own HTTPS server or using a service like Ngrok for local development.

2. For this beginner’s guide focused on local setup, we’ll use the HTTPS option and Ngrok.

3. Why Ngrok? Ngrok is a powerful tool that creates a secure tunnel from a public HTTPS URL to your local machine. This allows Alexa, which runs in the cloud, to communicate with code running on your computer, even if it’s behind a home network firewall. This is invaluable for development and testing.

Step 5. Setting Up Ngrok to Expose Your Local Server

To use Ngrok, you need to download and run it on your local machine.

1. Download Ngrok from https://ngrok.com/download and follow the installation instructions for your operating system (Windows, macOS, Linux).

2. Once installed, open your terminal or command prompt.

3. To start Ngrok and forward traffic to your local server (assuming your Flask app will run on port 5000, a common default), run the command: ./ngrok http 5000 (on macOS/Linux, you might need to navigate to the directory where you extracted Ngrok). On Windows, it might be ngrok.exe http 5000.

4. Ngrok will start and display a forwarding HTTPS URL in your terminal. It will look something like https://your-unique-ngrok-url.ngrok.io -> localhost:5000. Copy this HTTPS URL.

Ngrok terminal displaying the crucial forwarding HTTPS URL that will be used to connect Alexa to your locally running application.

Step 6. Linking Ngrok URL to Your Alexa Skill Configuration

Now, go back to the Alexa Developer Portal, specifically the “Configuration” tab for your skill.

1. Select “HTTPS” for the “Service Endpoint Type.”

2. In the “Default” endpoint field, paste the HTTPS URL you copied from Ngrok.

3. For “SSL Certificate,” choose “My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority.” This is generally the correct option when using Ngrok.

4. Click “Next.”

Configuring the Alexa Skill’s Configuration tab, pasting the Ngrok HTTPS URL to establish the connection between Alexa and the local development environment.

Step 7. Writing the Alexa Skill Code with Python and Flask-Ask

With the Alexa skill configured and Ngrok set up, it’s time to write the Python code that will power your math game skill. We’ll use Flask-Ask, a Python library that simplifies Alexa skill development with Flask, a lightweight web framework.

1. Install Flask-Ask: If you don’t have it already, install Flask-Ask using pip: pip install flask-ask. Also ensure you have Flask installed: pip install flask.

2. Python Code Structure: Create a Python file (e.g., math_game.py) and paste the following code, which is based on the original math game example, with explanations inline:

import logging
from random import randint
from flask import Flask, render_template
from flask_ask import Ask, statement, question, session

app = Flask(__name__)
ask = Ask(app, "/")
logging.getLogger("flask_ask").setLevel(logging.DEBUG)

@ask.launch
def new_game():
    welcome_msg = render_template('welcome') # Renders the 'welcome' message from templates.yaml
    return question(welcome_msg) # Sends the welcome message to Alexa and keeps the session open for a response

@ask.intent("YesIntent")
def next_round():
    question_number = randint(1, 9) # Generates a random number between 1 and 9
    round_msg = render_template('round', question_number=question_number) # Renders the 'round' message with the random number
    session.attributes['question_number'] = question_number # Stores the question number in the session
    session.attributes['answer_number'] = 10 - question_number # Stores the correct answer in the session
    print('finished ask.intent', question_number) # For debugging in the console
    return question(round_msg).reprompt("What's your answer?") # Asks the question and reprompts if no response

@ask.intent("NoIntent")
def no_intent():
    bye_text = "Ok, Thanks for playing."
    return statement(bye_text) # Sends a simple statement to Alexa and ends the session

@ask.intent("AnswerIntent", convert={'number': int}) # Expects a number from the user and converts it to an integer
def answer(number):
    print('starting answer-intent', number) # For debugging
    winning_number = session.attributes['answer_number'] # Retrieves the correct answer from the session
    if number == winning_number:
        msg = render_template('win') # Renders the 'win' message
    else:
        msg = render_template('lose') # Renders the 'lose' message
    return question(msg) # Sends the win/lose message to Alexa and keeps the session open for another game

if __name__ == '__main__':
    app.run(debug=True) # Starts the Flask development server on port 5000

3. Create templates.yaml: In the same directory as your Python file, create a file named templates.yaml and add the following content:

welcome: Hi Alice. Alexa here. Your dad programmed me to help you learn your math. I am going to give you a number and you need to tell me what other number added to it will add up to 10, are you ready?
round: ok, {{ question_number }} and what number equal ten?
win: Good job! Do you want to play again?
lose: Sorry, that's the wrong answer. Do you want to play again?

4. Run Your Flask App: Open another terminal or command prompt, navigate to the directory where you saved math_game.py and templates.yaml, and run python math_game.py. This will start the Flask development server, listening on port 5000.

Step 8. Testing Your Alexa Skill

With your code running and Ngrok tunneling to your local server, you can now test your Alexa skill.

1. Go back to the Alexa Developer Portal and navigate to the “Test” tab for your skill.

2. Ensure “Development” is selected in the dropdown at the top of the Test page.

3. In the test simulator, you can type or speak your invocation name, for example, “open math tutor game.”

4. If everything is set up correctly, you should see the “welcome” message from your skill in the simulator, and you can interact with the math game by responding with “yes” or numerical answers.

5. Alternatively, and more excitingly, you can test on a real Alexa-enabled device linked to your Amazon developer account. Simply say, “Alexa, open math tutor game” to your device and play your newly created skill!

Conclusion: You’ve Set Up Your First Alexa Skill!

Congratulations! You’ve successfully navigated the steps to set up Alexa and create a basic, functional skill. This guide walked you through the Amazon Developer Portal, intent creation, Ngrok setup, and writing a simple Python skill using Flask-Ask.

This is just the beginning. The Alexa Skills Kit offers vast possibilities for creating engaging and useful voice experiences. Explore further, experiment with different intents, expand your Python code, and unleash your creativity to build even more sophisticated Alexa skills. For the complete source code of the math game example, you can visit Github. Happy coding and skill-building!