Alexa skill development done right: Basic setup

Doing your alexa skill setup right can not only save you a ton of time but also makes you more flexible and less error prone. In this article we will setup a new skill completely based on code, so that you will have everything — from the developer console to the lambda function — in your local repo.

The example skill we will setup will be a trivial “Hello World” skill, as this article only cares about the setup and not the skill itself. The article will also assume that you have understood the essential parts of what you need to make a skill run.

Check out the repo with the finished project on Github

1. Skill configuration: Developer Console

The developer console is used to manage all the skills information like the invocation name, intents to the skills store description. However, managing all that information in the developer console has a few disadvantages:

  • The information is not versioned, which means changes you are doing cannot be undone. Also, if you are in a team, you do not know who did the changes.
  • The information is away from your skills code. Although both is tightly bound together, it’s not in your repo. Doing changes to your model that may affect your code can easily break something, like typos in your intent.

To tackle these problems we will use the ask cli. The ask cli offers us to store all information in json files and deploy it via commands. Therefore, we have everything (code and skill information) in one place and versioned. So let’s setup the project:

  1. Install and login the ask cli. Also set your AWS credentials as described here (you don’t have to do the profiles stuff, just do the quick setup)
  2. Create a new skill with ask new --skill-name basic-setup-cat-facts. This will create a new folder on our local machine with all necessary files. Afterwards move into the created folder.

There are now 3 files where the skills information and configuration is saved:

  • .ask/config: Contains the skill id and lambda ARN. Should not be published respectively commited in your repo.
  • models/en-US.json: Contains the invocation name, intents and slots.
  • skill.json: Contains publishing information for the skill store, like description and example phrases.

As we use the serverless framework for the code deployment we will have to change the configuration a little bit and reorder some files to make it more convenient to work with:

  1. Open the skill.json file and remove the "apis" object. Then go to the .ask/config file and change the value of the "uri" variable to arn:CHANGE_LATER. This will prevent the ask cli to deploy our skill.
  2. Move the index.js file from /lambda/custom into a /src folder and the package.json and package-lock.json into the projects root folder. Then delete the /lambda folder.

We can now execute ask deploy to push the model and skill information to the developer dashboard.

The current ask cli doesn’t support updating the models json when you changed it with the skill builder. It can only clone the complete project and overriding the current one. A workaround after doing some stuff with the skill builder would be to clone the project into a new folder and then copy&paste the models json into the current project.

2. Code: Lambda function

To define and deploy our skill function and infrastructure we will use the serverless framework. Serverless is the market leader in deploying and operating serverless architectures. The direct advantage to the ask cli is that we can not only deploy our code but also define the AWS infrastructure. This allows as for example to add a database, s3 or other stuff we might use in our skill later on. So let’s start deploying our function:

  1. Install serverless
  2. Create the serverless configuration for the skill. This is done within a serverless.yml file:
Minimal serverless configuration for an alexa skill

3. Deploy the function with serverless deploy

4. When the deployment is finished you can display the ARN (unique skill qualifier on aws) with serverless info --verbose. Copy the ARN and replace the arn:CHANGE_LATER value in your .ask/config file with it. This will link the skill configuration on the developer dashboard with your lambda function

5. Update the skill configuration with ask deploy

The skill setup is now finished. You can now go to the skill store and activate your own skill.

3. Conclusion

With this setup we are now able to change the skill configuration, lambda function and deploy the updates with one command each. Also everything is versioned and in one project folder.

Additionally, we can do some polishment and save the ask cli and serverless package as dev dependency into our package.json. Thereby all tools come with the project. We also put all commands we use in there. In this way we just have to remember a few easy commands. If you want to see everything in detail, checkout the repository:

Up next: Alexa skill development done right: Advanced setup

Happy skill development :)