MoustASK - Moustache Templates for Alexa Skills Kit

This powerful tool enables you to create Alexa skill projects and all their files as Moustache templates to deploy them with customized settings on the fly. No more need to replicate resources you'd want to share across many Alexa skills.

Moustache is a logic-less template syntax. It can be used for HTML, config files, source code - anything. Alexa Skills Kit ASK is a set of tools to build capabilities, or skills, that make Alexa smarter. MoustASK however is just a tiny shell script that combines both worlds and establishes a very effective way of creating and maintaining the project repositories for many Alexa skills that work on a shared set of resources.

Alexa Skill Templating powered by Moustache

Context
Step by Step Guide
- Prerequisites
- Input
- Output
  - Generate Alexa skill variants
  - Deploy Alexa skill variants
Best Practices
Example

What is this for?

This tool is made for a scenario where you got several configuration settings for one or many Alexa skills that share most of their resources (i.e. code files, skill metadata, interaction model) with only a few pieces of individual configuration (i.e. invocation name, skill title etc.). A good example are bulk skills as well as stage environments for just one single Alexa skill project.

Why do I need it?

The official ASK CLI tool is not designed for the above described scenarios as it takes static file input (i.e. from skill.json and interaction model schema files) and it does not allow you to ingest settings from external configuration. In order to deploy multiple skills using the same schema, code or metadata you'll need to create individual resource files or modify them manually before you "ask deploy". One good example is the invocation name which is baked into the JSON model files. If you want two skills with different invocation names to share the same interaction model you are required to replicate the model files and put in the respective invocation name. Moreover, those files cannot just exist side by side in one project. The reason is that ASK CLI requires a static file structure (i.e. a US interaction model needs to sit in /models/en-US.json) and there is no option to point ASK CLI to another file location.

What it does

The main idea is to replace individual settings in any files of your skill project with placeholders. This could be in your skill code, in the skill.json file, .ask/config file or interaction model files. You can then go and create different configuration profiles to resolve these placeholders in your source files right before you´d want to deploy a skill. Using Moustache as a template system makes it very flexible to work with placeholders in source files as it goes way beyond just ingesting single values. It could even contain conditional and formatting logic. Learn more about Moustache

How it works

0) Prerequisites

The tool is using Moustache with Moustache CLI. npm install them and you´re good to go.
Store the moustask.sh shell script in the root folder of your skill project.

1) Create configuration profiles

Create a new folder called templates in your skill project root. In it, you should create one to many JSON profiles that store all invididual configuration settings for the skill variants and that should not be stored in your generalized skill project files (aka Moustache templates). There is no fixed format. You'll define the format and refer to it in your source files.

{
    "skillid": "amzn1.ask.skill.b440f3d5-2a08-47ab-b21d-49xxxxxxxxx",
    "functionName": "space-facts",
    "title": { "en": "Space Facts", "de": "Weltraumfakten" },
    "invocation": { "en": "space facts", "de": "weltraumfakten" }
}

2) Turn your skill resource files into Moustache templates

Assume you have an interaction model you´d want to share across many Alexa skills. Instead of entering the invocation name you are putting in a placeholder.

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "{{invocation.en}}",
      "intents": [
      ]
    }
  }
}

The invocation name is also contained in your Alexa skill metadata. You'll use the same placeholder and another one for the skill title to set up your skill.json file.

{
    "manifest": {
      "publishingInformation": {
        "locales": {
          "en-US": {
            "examplePhrases": [
              "Alexa open {{invocation.en}}",
              "Alexa ask {{invocation.en}} for a fact"
            ],
            "name": "{{title.en}}",
            "description": "This is the fancy {{title.en}} skill. Get started with 'Alexa open {{invocation.en}}'"
          }
        }
      }
    }
  }

Output speech may also contain individual information like the skill title. Put some more placeholders in your Alexa skill code.

const LaunchHandler = {
  handle(handlerInput) {
    return handlerInput.responseBuilder.speak('Welcome to the {{title.en}} skill.').getResponse();
  }
};

Last but not least you may want to host all skills that share these resources in separate AWS Lambda functions. Put in another placeholder in the ask config file.

{
  "deploy_settings": {
    "default": {
      "skill_id": "{{skillid}}",
      "merge": {
        "manifest": {
          "apis": {
            "custom": {
              "endpoint": {
                "uri": "ask-skill-lambda-{{functionName}}"
              }
            }
          }
        }
      }
    }
  }
}

3) Add individual resources for a configuration profiles

Sometimes skill variants ship with their own file resources as well (i.e. images and audio files). Create a folder in the templates folder which got the same name as the json configuration profile for a skill variant and store any files you need in it.

Your project should now look like the following.

/my_skill_project/
│ 
└───/.ask/
│   └───/config
│   
└───/lambda/ ...
│ 
└───/models/
│   └───/en.US.json
│ 
└───/templates/
│   └───/profile1/
│   │   └───/jingle.mp3
│   │
│   └───/profile1.json
│   └───/profile2.json
│
└───/moustask.sh
└───/skill.json

The templates folder contains at least JSON files with the configuration profiles and optionally custom resources like sound files per profile. All your skill resources like models, lambda code, skill.json and config files contain placeholders later being fulfilled by the configuration profiles. Last but not least, there´s the moustask.sh shell script which does all the magic.

4) Generate skill variants

Now execute the shell script.

bash ./moustask.sh

It picks up all configuration profiles in the templates folder and does the following for each:

It clones the entire Alexa skill project with all its files and puts them into a new _dist folder in your project.
It then looks for Moustache placeholders in those files and resolves them given your inputs from the configuration profiles.
Finally it looks for custom resources in the templates folder and copies them into the _dist folder as well.

5) Deploy Alexa skill variants

Let´s first have a look at the resulting project files below. There´s a new _dist folder which contains the replicated skill project - one per configuration profile. The settings from the configuration profiles were injected in the derived skill files. Pay attention to the jingle.mp3 file which is a custom skill resource for profile1 and is now part of the skill variant.

/my_skill_project/
│   
└───/_dist/
│   └───/profile1/
│   │   └───/.ask/
│   │   │   └───/config
│   │   └───/lambda/
│   │   └───/models/
│   │   └───/jingle.mp3       
│   │   └───/skill.json    
│   │   
│   └───/profile2/ ...
│     
└───/.ask/ ...
└───/lambda/ ...
└───/models/ ...
└───/templates/ ...
└───/moustask.sh
└───/skill.json

Deploying the skill is very simple. Navigate to the skill variant folder (i.e. /_dist/profile1) and deploy with ASK CLI ("ask deploy"). You could as well give shell commands to the moustask.sh directly. It will execute for you.

bash ./moustask.sh "ask deploy"

Best Practices

There are a few things you should consider:

Never change or modify anything in the _dist folder as all changes will be overridden the next time you execute moustask.sh. This folder and all its contents should also make it into your .gitignore list. If you want to change something you should do it in the original skill resources (including file operations like rename or delete) and rerun moustask.sh. This way you also make sure all your skill variants stay consistent.
If you´re deploying a skill variant for the first time a new skill is created in the Alexa database unless you ingest a skillid into the global .ask/config file. The resulting skill id is populated to the dist/profile/.ask/config file. Copy this skill id and put it into your configuration profile (i.e. profile1.json) and add a placeholder for the skillid property in the global _.ask/c

Moustask

Install / Use

README