Tutorial: Create an Alexa Conversations Skill with the ACDL

You can use the Alexa Skills Kit Command-Line Interface (ASK CLI) to create an Alexa Conversations skill from a quick-start weather bot template. This process takes about 20 to 60 minutes, depending on the number of languages for which you configure your skill. Templates like the weather bot and pizza bot use the Alexa Conversations Description Language (ACDL). This section helps you understand the skill creation and deployment sequence and related details.

The weather bot skill directory includes the source code, interaction model, and Alexa Conversations artifacts. This template is a sample skill, so it reports the weather for a fixed set of cities and always uses today's date. To get real weather forecasts from a wide range of cities, you can extend this skill to invoke any public weather API.

Prerequisites

Install and configure the ASK CLI

Before you begin this tutorial, install and configure the ASK CLI to use ACDL.

Steps to create a skill

To create an Alexa Conversations skill using an ASK CLI template, follow these steps.

  1. Create a skill based on a template
  2. Configure the skill for multiple languages
  3. Compile the skill artifacts
  4. Deploy the skill
  5. Test the skill
  6. Redeploy the skill

Step 1: Create a skill based on a template

In this step, you create your skill from the weather bot template.

To create an Alexa Conversations skill by using the ASK CLI

  1. Create a folder to hold your weather bot skill code.
  2. Navigate to your skill code folder and open a command line.
  3. To open the project wizard, enter the following command.

    askx new

  4. From the list of programming languages, choose Node.js.
    Node is currently the only programming language that supports the ASK CLI weather bot template.
  5. Choose AWS Lambda as the method to host your skill's backend resources.
    AWS Lambda is currently the only hosting method that supports the ASK CLI weather bot template.
  6. Choose the Weather Bot (Beta) template.
  7. Enter a skill name or press enter to select the default skill name.
  8. Enter a folder name or press enter to select the default folder. The default is the folder in which you created the skill.
    The command line displays a message such as the following.
    Project for skill "weather_bot" is successfully created at C:\<folder>\weatherbot
    Project initialized with deploy delegate "@ask-cli/lambda-deployer" successfully.
    

Step 2: Configure the skill for multiple languages (optional)

A customer might interact with your skill in more than one language, so it's important to offer a consistent experience. Supporting multiple languages increases your customer base, too.

Each language is associated with at least one geographic location or region. Language and country codes are combined to create locale codes, such as de-DE for the German language in Germany (Deutschland) and en-UK for English in the United Kingdom.

Alexa Conversations template skills, such as the weather bot, are configured to deploy en-US. However, you can use any language or combination of languages Alexa supports.

To configure your template skill for other locales

  1. From your weather bot skill folder, enter the following command.
    askx skill add-locales
    
  2. Use the arrow keys to scroll through the list of languages. To make a selection, press the spacebar.
Selection of locales in the ASK CLI

Step 3: Compile the skill artifacts

To compile the skill artifacts

From your weather bot skill folder, enter the following command.

askx compile

Step 4: Deploy the skill

In this step, you'll deploy your skill. Deployment is a 20- to 60-minute process that occurs in two stages for each locale: Light Build and Full Build. Each stage takes a few minutes to complete as the skill is generated and configured to route requests to the right AWS Lambda function. A status message appears each time a light build or full build succeeds for a given locale.

Alexa Conversations ASK CLI deployment notifications

A new build can, however, launch before the last one is finished. In other words, several builds can be in progress at the same time. The result, as shown in the accompanying image, isn't necessarily a linear sequence from one locale to the next.

To deploy the skill

  1. From your weather bot skill folder, enter the following command.
    askx deploy
    
  2. Enter y to the warning that ACDL skills are incompatible with the developer console.
Alexa Conversations ASK CLI deployment notifications

Step 5: Test the skill

A final notification indicates that the full build of your skill is complete in all locales. This notice includes the skill number you need in order to test your skill. If you like, however, you can begin testing as soon as the first light build succeeds. To do so, find your skill ID in the JSON file.

To find the skill ID

cat .ask/ask-states.json | grep skillId | awk '{print $2}'

Locate the skill ID in the JSON file, enter it into the ASK CLI, and follow the accompanying instructions to run your skill.

To run the skill

  1. After your skill deploys, copy the skill ID from the Deploy Skill Metadata. (Alternatively, you can begin testing early by finding the skill ID in the .ask/ask-states.json file, as explained earlier.)

  2. To run your skill in the Alexa simulator, enter the following command.

    askx dialog -s <your-skill-id> -l en-US -g development

  3. At the User > prompt, enter Open my weather bot, and then engage in a conversation similar to this one. Because the conversation is AI driven, Alexa might phrase the questions differently or ask for the city and date in reverse order.

    User > Open my weather bot

    Alexa > Welcome to the weather bot. I can give you the weather report. To get started, just say "What's the weather?"

    User > What's the weather?

    Alexa > For which city?

    User > Seattle.

    Alexa > For what date?

    User > Today.

    Alexa > In Seattle today you can expect a high of 65 degrees and a low of 50 degrees, with partly cloudy skies and a slight chance of rain.

  4. To exit the conversation, enter .quit, or press ctrl+c (Windows) or cmd+c (Mac).

Step 6: Redeploy the skill

If you need to, you can make changes after you initiate the deployment process. The most recent deployment will replace any model build that's in progress. You can continue to test as your skill model builds.

To redeploy a skill

  1. Update your code as necessary.
  2. Recompile the code.

    askx compile

  3. Submit a new build.

    askx deploy

  4. Enter y when the compatibility warning appears.

Troubleshooting

The following are possible resolutions for common issues related to this tutorial.

Issue: The weather bot template isn't an option

Symptoms When you type askx new and the ASK CLI guides you through skill creation, you don't see weather bot in the list of available templates.

Try this Make sure your version of the ASK CLI supports Alexa Conversations. To get the correct version, follow the steps in Set up the ASK CLI to Use ACDL.

Issue: Status message appears mutiple times

Symptoms When you resize the window during deployment, the status message looks like the one in the following image.

Repetitive message generated when screen is resized during deployment

Try this Either wait for deployment to finish or end this build and begin again. To end the current deployment, press ctrl+c (Windows) or cmd+c (Mac).

This issue is a known bug. For now, avoid resizing the terminal window during deployment.