Tutorial: Convert an Alexa Conversations Skill to Alexa Conversations Description Language

Note: Sign in to the developer console to build or publish your skill.

Note: Alexa Conversations Description Language (ACDL) is offered as a beta and may change as we receive feedback and iterate on the feature.

You can export a skill from the developer console so that you can edit it by using the Alexa Skills Kit Command-Line Interface (ASK CLI).

Important: Currently, if you migrate your skill to the upgraded developer console experience, you can no longer export the skill and work with it in the ASK CLI.

This tutorial assumes that your skill code is in AWS Lambda. Export capability is currently available only for en-us.

Note: Version 2.29 of the Alexa Skills Kit Command Line Interface (ASK CLI) is now available. This single tool lets you work with all Alexa skills, including Alexa Conversations Description Language (ACDL) skills, interaction model skills, and skills that use both. You can continue to use the current ASK CLI for ACDL, but it will no longer be updated. To get the latest supported features and functionality, use version 2.29 or later.

Prerequisites

Before you do this tutorial, you must do the following:

Install and configure a version of the ASK CLI that supports Alexa Conversations. For details, see Set up the ASK CLI to Use ACDL.
Successfully deploy your skill by using the developer console at least once.
Make sure that your ASK CLI version is version 2.29.0 or later to work with ACDL skills.
- To determine your CLI version, run ask --version
- To upgrade to the latest version, run npm install -g ask-cli
Install @alexa/acdl, the compiler toolchain for ACDL skills. It includes an acc command for compiling and decompiling skills.

npm install -g @alexa/acdl

Steps to convert a skill

Complete the following steps to convert an Alexa Conversations skill to ACDL by using the ASK CLI.

Important: After you deploy the converted skill by using the ASK CLI, you can no longer edit the Alexa Conversations skill artifacts by using the developer console.

Export the skill package by using the ASK CLI.
Decompile ACIR files to ACDL files.
Download your skill code.
Initialize the skill project.
(Optional) Compile the skill artifacts.
(Optional) Deploy the skill.

Step 1: Export the skill package by using the ASK CLI

In this step, you export the skill package by using the ASK CLI.

To export the skill package

Log in to the Alexa developer console.
Get the ID of your skill by doing the following:
1. Go to your skill list.
2. Under the name of the skill you want to convert, click Copy Skill ID, and then paste the skill ID on your computer somewhere you can find it later.
On your computer, create a folder to hold the code for this skill.
In your skill folder, open a command line.
Enter the following command, where <skillId> is the ID you copied in step 1, and <stage> is either development or live.

ask smapi export-package -s <skillId> -g <stage>

Your skill folder now contains a folder called skill-package. For a description of the contents, see Understand the Directory Structure of the ACDL.

Step 2: Decompile ACIR files to ACDL files

In this step, you decompile Alexa Conversations Intermediate Representation (ACIR) files to ACDL files.

To decompile ACIR files

From your skill folder, enter the following command.
npx acc decompile

Step 3: Download your skill code

In this step, you download your skill code to the directory that you created. The way you download the code depends on whether you created your skill as an Alexa-hosted skill, or whether you chose to provision your own code.

Download Lambda code for an Alexa-hosted skill

In the Alexa developer console, go to your skill list.
Select your skill from the list.
At the top, click the Code tab.
From the grey menu bar, click Download Skill.
Click Continue.
Save the zip file to your computer.
Unzip the file anywhere but in your skill folder.
From the unzipped files, copy only the lambda folder into your skill folder, on the same level as the skill-package folder.

Download Lambda code for a skill not hosted by Alexa

In your skill folder, create a folder called lambda.
Go to the AWS Lambda page in the AWS Management Console.
From your list of Lambda functions, select the Lambda function of the skill you want to export.
At the top right, click Actions, and then click Export function.
Click Download deployment package.
Save the zip file to your computer.
Unzip the zip file and move the contents of the zip file to the lambda function you created.

Step 4: Initialize the skill project

In this step, you initialize the Alexa skill project to generate ask-resources.json.

To initialize the skill project

From your skill folder, enter the following command.
ask init
At the prompt, enter your skill ID.
For the skill package path, press enter to accept ./skill-package.
For the Lambda code path, press enter to accept ./lambda.
For Use AWS CloudFormation to deploy Lambda, enter Y or N. If you're unsure, enter Y.
Click enter to accept the Lambda runtime and Lambda handler defaults.
For Does this look correct?, enter Y.
The command line should display the message Success! Run ask deploy to deploy your skill.

(Optional) Step 5: Compile the skill artifacts

In this step, you compile the skill artifacts.

To compile the skill artifacts

From your skill folder, enter the following command.
npx acc compile

(Optional) Step 6: Deploy the skill

In this step, you deploy the skill artifacts to the Alexa service, and the skill code to AWS Lambda.

Note: After you deploy the converted skill by using the ASK CLI, you can no longer edit the Alexa Conversations skill artifacts by using the developer console.

To deploy the skill

From your skill folder, enter the following command.
ask deploy
Enter y to the warning about ACDL skills not being compatible with the developer console.

Was this page helpful?

Provide feedback

Last updated: Jan 19, 2024