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

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).

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


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.

  1. Export the skill package by using the ASK CLI.
  2. Decompile ACIR files to ACDL files.
  3. Download your skill code.
  4. Initialize the skill project.
  5. (Optional) Compile the skill artifacts.
  6. (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

  1. Log in to the Alexa developer console.
  2. 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.
  3. On your computer, create a folder to hold the code for this skill.
  4. In your skill folder, open a command line.
  5. 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

  1. In the Alexa developer console, go to your skill list.
  2. Select your skill from the list.
  3. At the top, click the Code tab.
  4. From the grey menu bar, click Download Skill.
  5. Click Continue.
  6. Save the zip file to your computer.
  7. Unzip the file anywhere but in your skill folder.
  8. 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

  1. In your skill folder, create a folder called lambda.
  2. Go to the AWS Lambda page in the AWS Management Console.
  3. From your list of Lambda functions, select the Lambda function of the skill you want to export.
  4. At the top right, click Actions, and then click Export function.
  5. Click Download deployment package.
  6. Save the zip file to your computer.
  7. 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

  1. From your skill folder, enter the following command.
    ask init
  2. At the prompt, enter your skill ID.
  3. For the skill package path, press enter to accept ./skill-package.
  4. For the Lambda code path, press enter to accept ./lambda.
  5. For Use AWS CloudFormation to deploy Lambda, enter Y or N. If you're unsure, enter Y.
  6. Click enter to accept the Lambda runtime and Lambda handler defaults.
  7. 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.

To deploy the skill

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

Was this page helpful?

Last updated: Jan 19, 2024