I’ve built and published a simple Amazon Alexa skill. It’s called Brighton Tide, and it tells you the time of the next low tide in Brighton, UK.

These are the notes and links I’ve collected.

Most of the notes are from (and follow the structure of) the Amazon Alexa Workshop, 7 December 2017, Brighton, taught by Andrea Muttoni, @muttonia.

Much of this is remembering the order to punch buttons, and probably will be out of date already.

Orientation: About Echo, Alexa, and Skills

The Echo devices have 7 microphones: “beam forming” means the microphone that best picks up your voice is used to listen; the others isolate out sound. Mute button physically disconnects microphone.

Alexa Skills Kit (ASK) is how you build for Echo.

Skills are things you “teach” Alexa to do.

Skills have to be invoked. E.g.,“Alexa, ask National Rail to check my commute”. That invokes a National Rail skill.

There are 3 types of Skill:

Custom Skills, E.g., “…ask Foo…”. You can do anything, but you have to name the skill to invoke it.
Flash Briefing. An RSS feed of information (text or audio). This is about customer engagement, and gathers various sources for a customer.
Smart Home Skill: limited subset of intention (turn off, turn on, …) related to smart home control. Alex routes this for you e.g., to your Philips Hue Skills. Can use named lights to control which service.

Skill are Json => Json services. A text “card” (read out, or raw audio if you want) for Echo; can be graphical to phone.

Hello World

In the class we built “Brighton Guide”, so we could say: “Ask Brighton Guide for some restaurants”. This is effectively customizing a standard fact blueprint example.

Step 1. Create skill

From developer.amazon.com you can name, create, publish, skills.

NB: Regarding your Dev account and AWS account (e.g., where you registered your echo): if they have the same email address they are registered. See alexa.amazon.com for this. This is also where you can see card output

The steps are:

Click Skills Kit.
Click “Add New Skill”.
Name is what users see when browsing for a skill.
Invocation name is what user’s have to say. Multiple skills have have the same invocation name, and it is up to the user to activate the one they prefer. Default is the most popular.
Save… and go to the “interaction model”.

Step 2. Interaction model

Skills work with intents. These are what a user can do with your skill.

A developer provides sample utterances such as “where’s good to eat?”.

NB: “what’s a good Italian?” is different and uses slots (food type). Use them in utterances with {}. Slots need a slot type. They are like utterances for slots. Some are built in—such as date and time.

Launch Skill Builder (beta!) to create an interaction model. It seems bits of the developer site are being modernisied. At the time of doing the course, the Skills Builder looked radically different to the rest of the site, but that will probably be different now.

We used an existing sample: Sample Nodejs City Guide.

We pasted in the interactionmodel.json from the Git repository into the code editor and hit “save” model (deprecation warning expected) to build the model.

Building it places it into the Alexa knowledge graph…you’ll get a notification when it is built. Takes a few seconds.

Step 3. Configuration

(Back to the old interface)

Configuration is about defining what code gets called. In the class we build using AWS Lambda.

NB: Alex only works with N. Virginia or Ireland regions.

We created a function from the alexa-skill-kit-sdk-factskill blueprint. You have to:

give the Lambda a name
role: create custom, touch nothing, and allow lambda_basic_execution
Click create function
Add trigger… select Alexa Skills Kit, which requires configuration.
Click “add”

I found the interface a little confusing: What you click at the top, controls what you see at the bottom. E.g., you can switch between configuring the lambda and the trigger. Pressing “save” at the top of the interface saves the whole Lambda.

We pasted in src/index.js from Github example and saved.

The Blueprint includes the Alexa API Javascript library. The Lambda code handler registers our intent handlers. Intent handlers are a 1-to-1 match to intents. The handler services the voice intent, and sends back a card.

To complete the configuration we copy the ARN for the Lambda into the Skill. This is in configuration, select AWS Lambda, paste in the ARN to “default”). And save.

This now enables the Test section of the site.

Step 4: Test

If you have an Echo connected to your developer account, you can use it now. E.g., say “Alex, Open Brighton Guide”.

If you modify and save the Lambda or interaction mode, it’s live for your developer account.

To test without a device, select Service Simulator, enter Text and type “Ask Brighton Guide (whatever you want)”.

The service request will show the result of language decoding:

E.g., for “Where can I get coffee?” you’d maybe see:

"request": {
   "type": "IntentRequest",
   "requestId": "EdwRequestId.e7f7105a-be3d-4899-89cb-879ead461f19",
   "intent": {
     "name": "CoffeeIntent",
     "slots": {}
   },

Tip: when debugging Lambda-side create a test, where the input is the (e.g., above) JSON created during service test.

You can also try Echo in the browser: echosim.io (login, and change language in the drop down).

The end result of the day was: https://gist.github.com/muttoni/c702010f05c667ff08900b5c8bb190b1

Best practice and other notes

Tricks to help build conversations:

Choose invocation name carefully. Once activated, you don’t need to use it in subsequent command if the skill is listening for more.
Be strict in taking turns. When prototyping voice experiences, if role playing, put a visual barrier between you during simulation. Or: the only person who can speak is the one holding the tennis ball.
Sketch out the happy path.
Allow multiple slots in responses.
Be Brief (1 breath test)
Present definitive choices.
Write for ears (expect variety, bored by same thing over and over) not eyes (which like uniformity, patterns, differences)

Other notes

Delegation

for required slots, can delegate to utterances.
if you give additional information, that can fill both slots.

…see SDK Readme for an example. You can emit a :delegate for missing fields.

Account linking….

Can be enabled, to login via OAuth to get customer identity.

Publication

Certification of a Skill takes 2-3 days and you cannot change anything other than your lambda after publication. i.e., interaction model is locked. Go into developer mode, which will create a clone of your skill.

Alex for Business

can have private skills
in beta.

Alexa Skills Basics