Create and Manage Alexa-Hosted Skills Using the ASK CLI

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

You can use the Alexa Skills Kit (ASK) Command Line Interface (CLI) to create and manage Alexa-hosted skills as described in this documentation. For an overview of hosted skills, see About Alexa-hosted Skills.

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

You can create an Alexa-hosted skill by using the Alexa developer console.
You can create an Alexa-hosted skill by using the developer console and importing a skill project from a public Git repository.
You can create an Alexa-hosted skill by converting an existing Alexa skill.

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 Amazon Web Services (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 branch, named dev, which corresponds to the skill code in the Code tab of the developer console.
The branch, named master, which corresponds to skill code running on the development-stage AWS Lambda endpoint.
The branch, named prod, which corresponds to skill code running on the live AWS Lambda endpoint, if your skill is already live.

If the dev branch gets out of sync with the developer console, use the following commands to fix the issue:

$ git checkout dev
$ git pull --rebase
$ git merge master
$ git push --no-verify

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 five 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 the master branch 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 is equivalent to clicking Deploy in the Code tab of the developer console and allows you to test your changes before you promote to live.
Merging the master branch 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 Submit Skills for Certification in the Alexa Developer Console.

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 the master branch, 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 five 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

To save your changes, push your quick fix to the master branch. 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:

To deploy your skill with ASK CLI v1.x, run the ask deploy command.
To upgrade the ASK CLI to v2.x, run npm update -g ask-cli.
To create a profile with the ASK CLI v2.x, run the ask configure command.
From your project's root directory, run the ask util upgrade-project command with the profile you created in the previous step. This command changes the v1 project structure to the v2 structure.

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 v2 requires a git push to the remote Alexa-hosted skills master branch to deploy. The ask deploy command has no effect for Alexa-hosted skills. For details about ASK CLI migration, see the ASK CLI v1 to v2 Migration Guide.

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 branch, named dev, which corresponds to the current saved skill code shown in the developer console.
The branch, named master, which corresponds to skill code running on the development-stage AWS Lambda endpoint.
The branch, named prod, 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)

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 the dev branch, merging the dev branch into the master branch, and then pushing to the master branch corresponds to clicking Deploy on the Code tab of the developer console.
Merging the master branch into the prod branch, and then pushing to the prod branch 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:

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

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

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

git checkout prod
git merge master
git push

To save your changes, merge your quick fix to the dev and master branches. 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.

Was this page helpful?

Provide feedback

Last updated: May 01, 2024