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

You 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 select either Node.js or Python for the programming language supported by Alexa-hosted skills and then select Alexa-hosted skills as the hosting solution. This 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 repository is configured with the following branches:

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

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

You deploy 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. Also it deploys updates to interaction model, skill manifest and in-skill products if you make changes in skill-package directory and push them to master.

  • Merging master into prod and then pushing to prod is equivalent to clicking Promote in the Code tab of the developer console. This only deploys a quick fix to the code for your live skill, and does not deploy updates to the interaction model, like changes to slots, intents, and utterances. Interaction model changes will require a certification review.

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 your skill is already published and you need to release a quick fix to your production code, you can promote your changes to live in the developer console by clicking Promote to live, or you can make changes, push to master and then merge the master branch to prod by doing the following:

$ git checkout prod
$ git merge master
$ git push

This affects all customers that use your skill, and does not deploy updates to the interaction model like changes to slots, intents, or utterances. Please make sure you push your quick fix to master branch to ensure that your changes are not lost. Quick fixes are otherwise overwritten when a skill that is in development goes live, for example when the skill passes certification, or when you promote changes to live. In these situations, the code in the master branch is deployed and the code on the prod branch is replaced by forced merge.

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

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

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

After you upgrade, the local dev branch is removed, your previous changes in the dev branch are merged into the master branch, and 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 creates a new Alexa-hosted skill in the development stage for your Amazon developer account, but it does not 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 repository is configured with the following branches:

  • The dev branch, which corresponds to the current saved state shown in the developer console.
  • The master branch, which corresponds to what is deployed to the development-stage AWS Lambda endpoint.
  • The prod branch, which corresponds to what is deployed to 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 dev, then merging dev into master, 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 on the Code tab of the developer console. This only deploys a quick fix to the code for your live skill, and does not deploy updates to the interaction model, like changes to slots, intents, and utterances.

The following procedure shows how to use the deploy command, which 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, 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 your skill is already published and you need to release a quick fix to your production code, you can promote your changes to live in the developer console by clicking Promote to live, or you can merge the master branch to prod by doing the following:

git checkout prod
git merge master
git push

This affects all customers using your skill, and does not deploy updates to the interaction model like changes to slots, intents, or utterances. You should also merge your quick fix into the dev and master branches, to ensure that your changes are not lost. Quick fixes are otherwise overwritten when a skill that is in development goes live, for example when the skill passes certification, or when you promote changes to live. In these situations, the code in the master branch is deployed and the code on the prod branch is replaced by 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.