Create and Manage Alexa-hosted Skills Using the ASK CLI

You can use the Alexa Skills Kit Command Line Interface (ASK CLI) to create and manage Alexa-hosted skills as described in this documentation. For details about hosted skills, see Build a Skill End-to-end Using an Alexa-hosted Skill.

You can also create an Alexa-hosted skill in the following alternate ways:

Overview

When you create an Alexa-hosted skill by using the ASK CLI, you manage your skill in a GitHub project. The structure of a project that you create by using the ASK CLI v2 looks like the following:

├── ask-resources.json
├── infrastructure/
├── lambda/
│   ├── index.js
│   ├── package.json
│   └── util.js
└── skill-package/
    ├── interactionModels/
    │   └── custom/
    │       └── en-US.json
    └── skill.json

Your project contains the following files and folders:

  • skill-package/ — Contains resources such as the skill's manifest and any associated interaction models, in-skill products, and image assets. For details, see Skill Package API Reference.
  • infrastructure/ — If your skill uses AWS CloudFormation the template is in this folder.
  • lambda/ — Contains the source code for your skill.
  • ask-resources.json — The JSON configuration file for your skill.

ASK CLI v2

Create an Alexa-hosted skill with the ASK CLI v2

To create a new Alexa-hosted skill with the ASK CLI V2, use the new command, and then select either Node.js or Python for the programming language supported by Alexa-hosted skills. Finally, select Alexa-hosted skills as the hosting solution. This action creates a new Alexa-hosted skill in the development stage for your Amazon developer account, and clones the skill to your local computer.

To clone an existing Alexa-hosted skill to your local computer, use the init command with the skill ID:

$ ask init --hosted-skill-id <hosted-skill-id>

When you clone an Alexa-hosted skill, the ASK CLI V2 creates a folder that contains the Git repository with the code and skill package for your skill. The CLI configures the repository with the following branches:

  • The master branch, which corresponds to skill code running on the development-stage AWS Lambda endpoint.
  • The prod branch, which corresponds to skill code running on the live AWS Lambda endpoint, if your skill is already live.

Deploy changes to your Alexa-hosted skill (ASK CLI v2)

If you change the voice interaction model for your live skill, you must submit your skill for recertification. If you change only your AWS Lambda code, recertification isn't required, but Amazon validates your update by running automated security tests when you push your changes to the prod branch. These tests take up to 5 minutes to complete. When the tests complete successfully, your updated code replaces the live version. If a test fails, Amazon notifies you of the reasons by email. You can address the issues and resubmit your code.

You deploy development-stage changes to your Alexa-hosted skill by your git push activity:

  • Pushing to master pushes the code on your local computer to the development-stage AWS Lambda endpoint for your skill. In addition, it deploys any updates to the interaction model, skill manifest, and in-skill products in the skill-package directory. This action allows you to test your changes before you promote to live.

  • Merging master into prod, and then pushing to prod is equivalent to clicking Promote to live in the Code tab of the developer console. This action replaces the live code for your published skill, affecting the live behavior of the skill.

After you have tested your changes, use the developer console to start the process of publishing your skill to the Alexa Skills Store. For details, see Test and Submit Your Skill for Certification.

Update your Alexa-hosted skill quickly (ASK CLI v2)

If you already published your skill and you must release a quick fix to your production code, you can promote your changes to live. After you edit your skill code, push to master, and then merge the master branch to prod. This action is equivalent to clicking Deploy to live in the Code tab of the developer console. Deploying your updated code directly to live affects all customers that use your skill. When you push your updated code to prod, automated security tests run against your skill. These tests take up to 5 minutes to complete. When the tests complete successfully, your updated code replaces the live version. If a test fails, Amazon notifies you of the reasons by email. You can address the issues and resubmit your code.

Deploy live-stage changes to your Alexa hosted skill as follows:

$ git checkout prod
$ git merge master
$ git push

Make sure that you push your quick fix to the master branch to ensure that your changes aren't lost. Your quick fixes are otherwise overwritten when you have a skill that's in the development stage go live; for example, when the skill passes certification, or when you promote changes to live. These actions deploy the code in the master branch and replace the code on the prod branch by a forced merge.

Migrate your Alexa-hosted skill from ASK CLI v1 to ASK CLI v2

If you created your Alexa-hosted skill with ASK CLI v1.x, do the following to upgrade your project:

  1. With ASK CLI v1.x, run the deploy command.
  2. To upgrade the ASK CLI to v2.x, run npm update -g ask-cli.
  3. To create a profile with the ASK CLI, run the configure command.
  4. From your project’s root directory, run the util upgrade-project command with the profile you created in the previous step.

The upgrade removes the local dev branch and merges your previous changes on the dev branch into the master branch. The master branch becomes your default branch.

ASK CLI v1

Create an Alexa-hosted skill with the ASK CLI v1

To create a new Alexa-hosted skill with the ASK CLI, use the create-hosted-skill command. This action creates a new Alexa-hosted skill in the development stage for your Amazon developer account, but it doesn't clone the skill to your local computer by default. To clone an Alexa-hosted skill to your local computer, you can do one of the following:

  • Use the --auto-clone true option with the create-hosted-skill command, which creates a new Alexa-hosted skill and clones it to your computer with one command.
  • Use the clone command to clone an Alexa-hosted skill that you have already created.

When you clone an Alexa-hosted skill, the ASK CLI creates a folder that contains the Git repository with the code for your skill, as well as the interaction model and skill manifest. The CLI configures the repository with the following branches:

  • The dev branch, which corresponds to the current saved skill code shown in the developer console.
  • The master branch, which corresponds to skill code running on the development-stage AWS Lambda endpoint.
  • The prod branch, which corresponds to skill code running on the live AWS Lambda endpoint, if your skill is already live.

Deploy changes to your Alexa-hosted skill (ASK CLI v1)

If you change the voice interaction model for your live skill, you must submit your skill for recertification. If you change only your AWS Lambda code, recertification isn't required, but Amazon validates your update by running automated security tests when you push your changes to the prod branch. These tests take up to 5 minutes to complete. When the tests complete successfully, your updated code replaces the live version. If a test fails, Amazon notifies you of the reasons by email. You can address the issues and resubmit your code.

You deploy changes to your Alexa-hosted skill by your git push activity:

  • Pushing to the dev branch corresponds to clicking Save on the Code tab of the developer console.
  • Pushing to dev, merging dev into master, and then pushing to master corresponds to clicking Deploy on the Code tab of the developer console.
  • Merging master into prod, and then pushing to prod corresponds to clicking Promote to live on the Code tab of the developer console.

The following procedure shows how to use the deploy command. This procedure runs commands on the dev and master branches to push the code on your local computer to the development-stage AWS Lambda endpoint for your skill.

To use the ASK CLI to deploy changes to your Alexa-hosted skill:

  1. Make changes on the dev branch:

    1. <Make changes>
    2. <Navigate to the root directory for the Git repository>
    3. git add <file names>
    4. git commit
  2. Run the deploy command, which merges the dev branch into master, and then pushes your local dev branch to the remote dev branch, and your local master branch to the remote master branch.

After you have tested your changes, use the developer console to start the process of publishing your skill to the Alexa Skills Store. For details, see Test and Submit Your Skill for Certification.

Update your Alexa-hosted skill quickly (ASK CLI v1)

If you already published your skill and you must release a quick fix to your production code, you can promote your changes to live. After you edit your skill code, push to master, and then merge the master branch to prod. This action is equivalent to clicking Deploy to live in the Code tab of the developer console. Deploying your updated code directly to live affects all customers that use your skill. When you push your updated code to prod, automated security tests run against your skill. These tests take up to 5 minutes to complete. When the tests complete successfully, your updated code replaces the live version. If a test fails, Amazon notifies you of the reasons by email. You can address the issues and resubmit your code.

Deploy live-stage changes to your Alexa hosted skill as follows:

git checkout prod
git merge master
git push

Make sure that you merge your quick fix to the dev and master branches to ensure that your changes aren't lost. Your quick fixes are otherwise overwritten when you have a skill that's in the development stage go live; for example, when the skill passes certification, or when you promote changes to live. These actions deploy the code in the master branch and replace the code on the prod branch by a forced merge.

Troubleshooting issues with the AWS CodeCommit credential helper (ASK CLI v1)

If you have an older version of Git installed and you have configured an AWS CodeCommit credential helper, you might see an error, such as unable to access or the requested URL returned error: 403. To fix this issue, update Git to version 2.9 or later.