Boilerplate for creating an Alexa skill using the Amazon Skills Kit SDK. Includes a simple http server and tunnel to allow local testing via the Alexa Skills Kit (ASK) Developer Console.

alexa-skill-boilerplate
├── README.md
├── index.js
├── models
│   └── en-US.json
├── package-lock.json
├── package.json
├── src
│   ├── handlers
│   │   ├── AmazonCancelStop.js
│   │   ├── AmazonFallback.js
│   │   ├── AmazonHelp.js
│   │   ├── BasicIntentHandler.js
│   │   ├── Error.js
│   │   ├── SessionEnded.js
│   │   └── index.js
│   └── utils.js
└── support
    ├── devserver.js
    ├── start.js
    └── tunnel.js

This README file

Defines and exports the skill's main handler

Directory of interaction models for the skill, by locale

Directory of intent handlers

A collection of helpful utilities for building the response

HTTP server used in local development

Startup script for local development

Helper script to open the ngrok tunnel

To start, clone or fork this repo. You will also need to go through the process of creating a skill via the Alexa Skills Kit (ASK) Developer Console.

The interaction model defines the different intents that the skill will handle. Each intent has a name, a samples array containing sample utterances a user might use to invoke the intent, and an optional slots array. Slots can be used to define arguments to an intent that give Alexa more information about that request.

The code for creating the skill is found in index.js which exports the main handler function.

Handlers are located in src/handlers/ and are broken out by the intent request that they handle. Add custom handlers here.

Follow these steps to use the ASK Developer Console to test the skill locally.

$ npm start

The start command will first create an HTTPS tunnel to our localhost on port 3000, using ngrok. Next, it will set the NGROK_URL environment variable to the tunnel URL. Finally it will start a simple koa server listening for POST requests on port 3000. The server will automatically restart when changes are detected.

The local dev server will serve any files in the src folder. This can be useful if your handler needs to access local assets. Combine this with the NGROK_URL environment variable to create a path to the required file. For example, if your skill response includes a card with an image, you can use something like https://578b08d6.ngrok.io/assets/logo.png as the URL and it will serve that image from your local src/assets folder.

Head back to the ASK Developer Console and click on Endpoint in the sidebar. Selecte HTTPS as the Service Endpoint Type, then paste the tunnel URL into the Default Region box. Be sure to set the dropdown to "My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority." and then click Save Endpoints.

If all goes well you should now be able to use the ASK Developer Console simulator to generate requests that will be handled by your locally running server.