Skip to content

Latest commit

 

History

History
121 lines (77 loc) · 5.94 KB

Alexa-Hosted-Skill-Commands.md

File metadata and controls

121 lines (77 loc) · 5.94 KB
Raw

CREATE SKILL - NEW COMMAND

ask new creates an Alexa hosted skill, clones the skill project, and provides a git-ready environment on the local machine. This replaces the ask create-hosted-skill command in CLI v1.

Using ask new, the Alexa hosted skill service will create a new AWS account, which owns a Git repository using AWS CodeCommit, and an AWS Lambda function centered back-end. This allows developers to either code on the portal editor or checkout the code using Git and code on local IDEs.

STRUCTURE OF NEW COMMAND:

ask new [-p | --profile <profile>] [--debug] [-h | --help]

OPTIONS DESCRIPTION:

profile: Optional. Profile name to be used. Uses default as the default profile name, if this option or the environmental variable ASK_DEFAULT_PROFILE is not set.

debug: Optional. Show debug messages.

WORKFLOW

Users will be asked the following questions to create a new skill:

  • Prompts user for programming language
    • Select programming language
      • AHS supports Python3.8 and Node16.x
  • Prompts user for a method to host your skill's backend resources
    • Select Alexa-hosted skills
  • Prompts user for skill name
    • Leave empty to use the default skill name hosted hello world
  • Prompts user for a folder name for the skill project
    • Leave empty to use the default folder name HelloWorldSkill

The user is not prompted for a skill template. The Hello World Skill is the only option for now.

DOWNLOAD SKILL - INIT COMMAND

ask init --hosted-skill-id <hosted-skill-id> -- download an existing Alexa-Hosted Skill to their local environment.

This command initializes Alexa Hosted Skills by cloning the project from the hosted skill service, downloading the latest Alexa skill package, and provide a git-ready environment. Developers can then checkout, pull from, and push to a remote Git repository from their local machines.

STRUCTURE OF INIT COMMAND:

ask init [--hosted-skill-id <hosted-skill-id>] [-p | --profile <profile>] [--debug] [-h | --help]

OPTIONS DESCRIPTION:

hosted-skill-id: Required. Skill-id for the Alexa hosted skill.

profile: Optional. Profile name to be used. Uses default as the default profile name, if this option or the environmental variable ASK_DEFAULT_PROFILE is not set.

debug: Optional. Show debug messages.

GIT CREDENTIALS

To access the CodeCommit repository, the Alexa hosted service uses git-credential along with ASK-CLI and SMAPI to automatically pass down temporary Git credentials.

Using ask util git-credentials-helper in the skill root directory can retrieve the username and password of the Git credentials.

UPGRADE PROJECT - UPGRADE COMMANDS

Skills created with CLI 1.x will need to update their project structure in order to deploy with the CLI v2. ask util upgrade-project command will attempt to perform the necessary changes.

STRUCTURE OF UPGRADE COMMAND:

ask util upgrade-project [-p | --profile <profile>] [--debug] [-h | --help]

OPTIONS DESCRIPTION:

profile: Optional. Profile name to be used. Uses default as the default profile name, if this option or the environmental variable ASK_DEFAULT_PROFILE is not set.

debug: Optional. Show debug messages.

UPGRADE STEPS

  1. Using ask-cli 1.x, deploy your skill:
  • $ ask deploy
  1. Install ask-cli:
  • $ npm install -g ask-cli
  1. Upgrade your skill project with ask-cli. From your project's root directory, run:
  • $ ask util upgrade-project
    • A hidden folder named ./legacy contains a copy of your v1 skill project.
    • The CLI v2 skill-package directory is downloaded to the working directory.
    • The CLI v2 ask-resources.json will be generated.
    • The dev branch is merged into the master branch. The dev branch is then removed.
  1. Commit upgrade changes:
  • $ git commit -m "upgrade project for CLI v2"

DEPLOY SKILL - GIT PUSH

$ git push deploys skill package resources and skill code. Unlike in CLI v1, running ask deploy on hosted skills will no longer trigger skill deployment in CLI v2. Instead, $ git push sends the latest source code to Lambda. It also deploys skill-package changes such as the interaction model, skill manifest and in-skill products.

DEPLOYMENT STEPS

  • Push to deploy skill code and resources:
    • $ git push
    • Pushing to master branch deploys "lambda" folder to user's development stage AWS Lambda function, and deploys "skill-package" folder as skill's JSON files
    • Pushing to prod branch deploys "lambda" folder to user's live stage AWS Lambda function, and deploys "skill-package" folder as skill's JSON files

Note: dev branch is only used to be displayed in the web console. You only need to push to dev branch if you want to sync version that is displayed in the web console.

When you receive the following warning: "The master branch of your skill is ahead of the dev version. To re-enable the code editor, you need to use the ASK CLI to merge the remote master branch to dev and push.", you need to use following steps to sync your master branch back to dev:

git checkout dev
git pull --rebase
git merge master
# fix any merge conflicts if you have
git push --no-verify

DEVELOPMENT CONSOLE, BRANCHES AND STAGES

  • dev branch corresponds to the code you see in the web console editor.
  • master branch corresponds to development stage. When you click "Deploy" in the web console, dev branch is merged to master (deployment to development stage).
  • prod branch corresponds to live stage. When you click "Promote to live" in the web console, master branch is merged to prod (deployment to live stage).

Git Pre-push Hook

CLI v2 supports Alexa Hosted skill, a git-native service, to track deployment states using the pre-push hook. When $ git push executes, the pre-push hook prints the skill portal URL to allow users to track deployment states.