Set up Skill Flow Builder as a Developer

With Skill Flow Builder, you can use a metadata format to create content for games and stories including interactive fiction, role-playing games, and adventure games. The suite provides the following items:

  • A standard format for games and stories.
  • Built-in extensions to add game logic, and hooks to implement custom functions and instructions within your game.
  • A virtual Alexa emulator that provides simulation, with features for you to save and load the current state of the game or story.
  • A graphical user interface (UI) to edit and test your content.
  • A command-line interface (CLI) for developers.

As a developer you can use Skill Flow Builder to integrate content from writers or designers into language Alexa can understand.

Get started

You must install several software packages before you can install and use Skill Flow Builder.

To get started with Skill Flow Builder

  1. Install the latest version of Git.
  2. Install the latest version of the Amazon Web Services (AWS CLI).
  3. (Windows only) Install the latest version of the windows-build-tools module.
  4. Install Python. On Windows, use Python version 2.7.14. Skill Flow Builder doesn't run correctly on Windows with the latest version of Python. On the Mac, use Python version 2.7.14 - 2.7.16.
  5. Install Node.js version 10.15 or later.

Install and set up Skill Flow Builder CLI

You can set up the Skill Flow Builder CLI globally so that you can run commands for the Skill Flow Builder from any directory. Or you can set up the alexa-sfb package locally.

To install and set up Skill Flow Builder CLI globally

  • Open a command prompt or terminal, enter the following code, and then press Enter.
  npm install --global @alexa-games/sfb-cli

To install and set up the Skill Flow Builder CLI locally

Alternatively, instead of globally setting up the CLI, you can set it up locally.

  1. Change the directory to the one where you want to set up the alexa-sfb package locally.

  2. Open a command prompt, enter the following code, and then press Enter.

   npm install @alexa-games/sfb-cli

Run the Skill Flow Builder CLI

You can run the Skill Flow Builder CLI globally or locally.

To run the CLI globally

  • Open a command prompt, enter alexa-sfb, and then press the Enter key.

To run the CLI locally

  • Open a command prompt, change the directory to the local directory, enter the following code, and then press Enter.
  npx alexa-sfb

Install and set up the Visual Studio Code Extension

Amazon has optimized Skill Flow Builder for Visual Studio Code. Install a language extension for Visual Studio Code to provide syntax highlighting, error diagnostics, and definition jumps.

To install Visual Studio Code Extension

  1. Install the latest version of Visual Studio Code.

  2. Open a command prompt, and at the root folder for your project, enter the following code, and then press Enter.

   npx alexa-sfb vscode

In Visual Studio Code, use definition jump to jump to the file and line that defines a scene. For example, if your content contains the instruction -> myscene, click myscene and then press F12 or right-click and select Go to Definition to go to the line that defines the scene.

Create the skill project

After you've installed and set up your Skill Flow Builder software, you're ready to create your skill project for your new game or story.

To create your skill project

Open a command prompt, enter npx alexa-sfb new and then enter a path to the folder where you want to store the files or your game or story, for example:

npx alexa-sfb new my_best_story

Debug skill content using the simulator

You can run the simulator to play through your content and verify the behavior of the content. The simulator tests the runtime execution of the content, not the skill.

To preview content with the simulator

  • Open a command prompt, enter the following code, and then press Enter.
  npx alexa-sfb simulate <your_project_path>

Deploy your Alexa skill

After you have debugged your content with the simulator, complete the following steps to deploy your game or story as an Alexa skill.

Step 1: Set up your ASK profile

Set up your Alexa Skills Kit (ASK) profile with your developer account, and link your AWS account.

To begin to deploy your Alexa skill

  • Open a command prompt, type the following code: ask init, and then follow the prompts.

To use an ASK profile other than "default

Open <your_project_path>/abcConfig.json and then edit the attribute "ask-profile-name" to specify the profile you want to use.

  1. To specify the profile you want to use, open /abcConfig.json, and then edit the attribute "ask-profile-name". You must provide a working AWS account with AWS account security credentials set up for your user.
  2. If you don't have an IAM user with credentials, open the AWS Management console.
  3. Click the IAM tab, click Add User, and then create a new user name.
  4. Select the check box for programmatic access, and then grant a policy with the following structure.

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Sid": "SFB Developer",
                 "Effect": "Allow",
                 "Action": [
                     "iam:AttachRolePolicy",
                     "iam:CreateRole",
                     "iam:GetRole",
                     "iam:PassRole",
                     "lambda:AddPermission",
                     "lambda:CreateFunction",
                     "lambda:GetFunction",
                     "lambda:ListFunctions",
                     "lambda:UpdateFunctionCode",
                     "logs:DescribeLogStreams",
                     "logs:FilterLogEvents",
                     "logs:GetLogEvents",
                     "s3:GetObject",
                     "s3:PutObject",
                     "s3:PutObjectAcl",
                     "polly:SynthesizeSpeech"
                 ],
                 "Resource": "*"
             }
         ]
     }
    

Step 2: Update the skill configuration

You can create and deploy your skill without changing any configuration.

To update the skill configuration

  • Open <your_project_path>/abcConfig.json, and then update the following information in the skill configuration file:

    • "ask-skill-directory-name": The name of your skill as used by the ASK CLI. Your AWS Lambda function name and the skill name derive from this value. You can use contain upper and lowercase letters (A-Z, a-z), numbers (0-9), underscores (_), and dashes (-).

    • "skill-invocation-name": Defines how users invoke your skill. For more information, see Understand How Users Invoke Custom Skills.

    • "publish-locales": A list of Alexa-supported locales where you can publish the skill.

Step 3: Finish the skill deployment

Finish the skill deployment from the command prompt. You might encounter errors and need to run the script as an administrator.

To finish the deployment of your skill

  1. Open a command prompt, enter the following code, and then press Enter.

     npx alexa-sfb deploy <your_project_path>
    
    
  2. If your skill fails to publish with the error "AccessDenied: User: arn:aws:iam::... is not authorized to perform: iam:CreateRole on resource: ..., in the AWS Management Console, go to IAM, and then verify that your user has the policy described in Step 1: Set up your ASK profile.

Step 4: Set up the AWS IAM role

After you create the skill in your developer account and create the AWS Lambda function, you need to add permissions.

To setup the AWS IAM

  • Add permissions for DynamoDB, Amazon S3, and Amazon Polly to the IAM role created for your AWS Lambda function.
      The name of the default role created for your skill is `ask-lambda-"your skill project name"``
    
      There should already be a managed policy for the role `AWSLambdaBasicExecutionRole` for running the skill code on AWS Lambda.
    

To add a new policy so that AWS Lambda function can access DynamoDB

  • In the AWS Management Console, add the following policy:

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "SFB Lambda",
                  "Effect": "Allow",
                  "Action": [
                      "dynamodb:CreateTable",
                      "dynamodb:PutItem",
                      "dynamodb:DeleteItem",
                      "dynamodb:GetItem"
                  ],
                  "Resource": "*"
              }
          ]
      }
    
      To add further permissions to the above policy, see the section [Set up Amazon Polly voices (Optional)](#polly).
    
      <div markdown="span" class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> You might need to change some of the default AWS Lambda settings. In the AWS console, find your AWS Lambda function and change the following settings:
      * Verify the runtime environment is Node.js 8.10
      * Verify the timeout is set to at least 15 seconds</div>
    

Step 5: Launch your skill

As the final step to deploying your skill, you need to launch your skill by saying the wake word and invocation name.

To launch your skill

  1. On your Alexa device, test your skill by saying the wake word, followed by the invocation name. For example, say, "Alexa, open the Hi Low Game."

  2. Wait about 15 seconds for the AWS Lambda function to create the DynamoDB table, and then say the wake word, followed by the skill invocation name. For example, say, "Alexa, open the Hi Low Game."

Skill Flow Builder project structure

The following output shows the directory story structure of Skill Flow Builder projects and a brief description of what they are.

├── content
│   ├── en-US (locale specific resources)
│   │   └── resources
│   │       ├── public (public resources uploaded to S3)
│   │       │   ├── audio
│   │       │   ├── images
│   │       │   └── vo
│   │       │
│   │       ├── ProductISPs.json (ISP configuration)
│   │       ├── SlotTypes.json (Slot Type configuration)
│   │       └── apl-templates.json (APL template configuration)
│   │
│   ├── languageStrings.json (used/updated by 'build')
│   ├── MANIFEST.json (define .abc include rule)
│   └── story.abc (starting story file)
│
├── code
│   ├── extensions
│   │   └── ExtensionLoader.ts
│   │
│   ├── package.json
│   ├── tsconfig.json
│   └── index.ts
│
├── abcConfig.json (SFB configuration)
├── .gitignore
├── .deploy (deployment payload, generated on 'build')
├── baked ("compiled" content, generated on 'build')
└── metadata (deployment configuration, generated on 'deploy')

Project code (Typescript)

Skill code generated by Skill Flow Builder uses ASK SDK for Node.js. The ASK SDK integrates the business logic of Skill Flow Builder as a request handler. You have a full visibility and control over how the core Skill Flow Builder functionality is added to your code. For more information, see the code/index.ts file, which is the entry point for requests coming to your skill's Lambda function.

Project content

The Skill Flow Builder packages up the following resources and content in content to generate artifacts that are used for driving the skill:

  • content/en-US - A directory that contains content resources such as assets, ISP, and slot types. You can create your own configuration at this level and access the configuration in your code by using the instance of ConfigAccessor which is available in code/extensions/ExtensionLoader.ts. If you want to add different locales, simply create the same directory structure with the locale name replacing the "en-US". For example, if you decide to add "de-DE" as your new locale, you would create a copy in content/de-DE.

  • content/languageStrings.json - A file that contains the extracted string from your story written in *.abc files. During the build step, localizable strings from used .abc files are extracted to create the file. The build logic uses the publish-locales field of the project's abcConfig.json file to decide in which locales the files should be generated, and used in.

For all of the newly added locales, the content is copied from the source (.abc). Once the strings are generated for locales other than en-US, the skill will always use the strings defined in the languageStrings.json file since there is no way to tell if the translation has occurred or not. To generate the strings for other locales, you can delete the strings you want to regenerate for the given locale, or you can delete the entire file.

  • content/MANIFET.json - A rule to define the .abc files that are included in the skill. You can add to the include field, or you can define it using a wild-card character *. You can add .abc files in subdirectory within the content directory. Adding the files this way can be useful when you try to organize a large skill by splitting up the content flow into multiple .abc files in organized directories.

  • content/story.abc - This is an example of a branching content file for Skill Flow Builder. For more information, see Use Skill Flow Builder to Create Your Content.

Skill Flow Builder life cycle

The Skill Flow Builder life cycle consists of the build life cycle and the skill run-time life cycle.

Build life cycle

The following is a lifecycle for Skill Flow Builder project when the build process is executed by running alexa-sfb build.

  1. Code Build: Install dependencies and run compile script for code directory.

  2. Pre-Import: Run extendSourceContent() on content source (included *abc files) for the attached ImporterExtension.

  3. Import: Translate *.abc story content into StoryMetadata object.

  4. Post-Import: Run extendImportedContent on resulting StoryMetadata for all attached ImporterExtension, and write the result to baked/en-US(or relevant locales)/baked_story.json.

  5. Staging: Generate .deploy and create a deployment payload with ask new command, then copy built code, imported story, and assets from content/{locale}/resources to the resulting deployment payload directory. If metadata exists copy skill.json and ask_config from the metadata directory for appropriate stages.

  6. Deploy (if you are running deploy command): Run ask deploy on the deployment payload.

Skill runtime life cycle

The following steps show the runtime life cycle when requests come in to your Skill Flow Builder skill's lambda.

  1. ASK SDK pre-request handler: The request and event object are enveloped by ASK SDK, and persistent skill state is retrieved with attached PersistenceAdapter.

  2. Skill Flow Builder Request Handler: ASK SDK's HandlerInput is passed to SFBRequestHandler for processing, then the handler calls SFBDriver with current skill state and incoming request.

  3. Skill Flow Builder Driver Pre Run: Run pre() for all attached instances of DriverExtension. Default DriverExtension like AlexaExtension would parse the request in to UserInput object at this step.

  4. Skill Flow Builder Driver Run: The core logic for taking the incoming user input, StoryMetadata, and current skill state, is executed at this step along with running custom instructions defined in attached InstructionExtension.

  5. Skill Flow Builder Driver Post Run: Run post() for all attached instances of DriverExtension. Default DriverExtension like AlexaExtension would generate an Alexa skill response given the post run state at this step.

Create a custom extension

Similar to the Skill Flow Builder life cycle, there are few opportunities to extend the functionality of your Skill Flow Builder project by building custom extensions. While you create your content, you might need to create a custom command to run your own code during a particular scene, or you might want to run an analytical script before or after every request.

You can implement one of the three extensions interfaces from the sfb-f module to customize and add features and functionalities to your Skill Flow Builder built skill. The three extensions are:

  • ImporterExtension - Applied before or/and after importing a source content as a StoryMetadata.
  • DriverExtension - Applied before or/and after the request has been applied for the story run.
  • InstructionExtension - Applied during the story run to handle custom instructions within the content.

ImporterExtension

Import this interface from @alexa-games/sfb-f module to implement. The following example shows the usage of ImporterExtension.

interface ImporterExtension {
    extendSourceContent(sourceHelper: SourceContentHelper): Promise<void>;

    extendImportedContent(metadataHelper: StoryMetadataHelper): Promise<void>;
}

Details

  • Implement ImporterExtension is used to add custom logic for the content import step.

  • extendSourceContent is invoked right before the raw text of the source file is imported as a StoryMetadata.

  • extendImportedContent is invoked after the importing is finished. Typically, it's implemented to modify some components of the resulting StoryMetadata.

DriverExtension

Import this interface from @alexa-games/sfb-f module to implement. The following example shows the interface.

interface DriverExtension {
    pre(param: DriverExtensionParameter): Promise<void>;

    post(param: DriverExtensionParameter): Promise<void>;
}

Details

  • Implement DriverExtension is used to add custom logic for before and/or after driver execution.

  • pre is invoked before the driver runs. Typically, it is implemented to customize the request parsing logic before the driver runs.

  • post is invoked after the driver runs. Typically, it is implemented to customize the response construction logic.

InstructionExtension

To use InstructionExtension, import this interface from the @alexa-games/sfb-f module. The following example shows the InstructionExtension interface.

interface InstructionExtension {
}

You can also implement the InstructionExtension interface to add custom instructions for your content writers. For example, you can add a new instruction called setupForCombat, where all of the variables required for a combat are set.

The following example shows what that extension class might look like.

import { InstructionExtension, InstructionExtensionParameter } from '@alexa-games/sfb-f';

export class CombatInstructionExtension implements InstructionExtension {
    async public setupForCombat(param: InstructionExtensionParameter): Promise<void> {
        param.storyState.health = 100;
        param.storyState.energy = 0;
        param.storyState.enemyHelath = 100;
        param.storyState.enemyEnergy = 100;
    }
}

After you build your project with this extension, whenever you use the instruction setupForCombat the method of the same name in your extensions is invoked.

The following example shows what your .abc file might look like.

    abc
@start combat
    *say
        rawr starting combat
    *then
        setupForCombat // your custom instruction will run when the story reaches here.
        -> next turn in combat

You might need to pass in parameters from your story to the extension. The following example shows how you can pass in parameters.

    setupForCombat person='player' map='garage'

When this instruction is executed by Skill Flow Builder, the framework creates a key, and a value pair map using the left-hand side of the equal sign (=) as the key and the right-hand side as the value as seen in the following example.

{
    "person": "player",
    "map": "garage"
}

You can access the parameters from your code by using the instance of InstructionExtensionParameter. The following example shows how your file might look if you use InstructionExtensionParameter.

    async public setupForCombat(param: InstructionExtensionParameter): Promise<void> {
        // the value should be "player" for this example.
        const person = param.instructionParameters.person;

        // the value should be "garage" for this example.
        const map = param.instructionParameters.map;
    }

You can return values by injecting variables into the story state object. The story state object is a key-value pair mapping of variables assigned and used within the story. The following example shows an implementation of the extension.

    async public doSomething(param: InstructionExtensionParameter): Promise<void> {
        param.storyState.result = "win"
    }

The variable named result will be assigned with the value "win". The following example shows the return value of custom instruction doSomething.

@result routing
    *then
        doSomething
        if result == 'win' {
            -> win scene
        }

        -> lose scene

Common objects

Most of the parameter objects passed as an argument to different extensions include two common objects, storyState and driver.

The storyState is the user state of your skill. It is the key-value pair map representing the variables used in the story. You can inject variables or read variables to change the state of your skill. This state is saved and loaded using the PersistenceAdapter on every request for the requesting user. Some of the variables in the story state are used by Skill Flow Builder logic. You can access and manipulate some of the system level state variables by using the StoryStateHelper utility class. You can import the utility class from the @alexa-games/sfb-f module.

The driver objectis an instance of the SFBDriver that is processing the story for the current request. The object has some helpful functions for properties that you can read to perform complex logic.

Add an extension to your project

  1. Open code/extensions/ExtensionLoader.ts. If this is an unmodified project, you should see four extensions already added within the class constructor.

         constructor(param: ExtensionLoaderParameter) {
             this.registeredExtensions = [
              // Alexa SFB extensions
             new AlexaExtension(),
             new AlexaAPLExtension(param.locale, param.configAccessor),
             new AlexaMonetizationExtension(param.locale, param.configAccessor),
    
             // sample custom extension
             new SampleCustomExtension()
         ];
     }
    
  2. To add your extension, add an instance of your extension as an item within this previous list of extensions.

Skill Flow Builder CLI reference

The alexa-sfb CLI provides several operations that you can use to deploy your skill and upload your skill's resources. Use the following pattern to execute options and commands: alexa-sfb [options] [command]. The following table shows the CLI options and commands, and the corresponding tasks you can perform.

Options and Commands Tasks
-V, -version This option will output the version number.
-v, -verbose This option will Increase verbose output.
-h, -help This option outputs usage information.
new Path to a new story. Use this command to create a new story project from a template.
deploy Path to a story. You can build and deploy a story to the developer portal and AWS Lambda.
deploy-metadata Path to a story. You can build and deploy updated metadata (skill manifest and voice model), but can’t deploy to AWS Lambda. This option is useful when the Lambda function code is large or when you upload the Lambda function through an S3 zip file linked to S3.
deploy-via-zip Path to a story. You can build and deploy a skill using a zip-file transfer to S3 and AWS Lambda Use this option when you are on a slow remote connection (you upload to S3 is faster than the aws update-function command) or when you exceed the command-line 69905067 byte limit.
build Path to a story. You can build a story without deploying.
simulate Path to a story. Use this command to simulate a story.
clean Use this command to clean out the .deploy, code .dist folder, and any extra node_modules folders for the given story. Run this command when you initially create a new stage or locale to force the creation of a new skill ID.
upload Path to a story. Upload public resources to S3.
vscode Install the vscode extension for Skill Flow Builder editor support.

new command

The new command creates a new local directory containing a fresh Skill Flow Builder project. You can specify which starter template you would like to use by specifying the --template option. You can then open this project folder in the Skill Flow Builder Editor or edit with VSCode or any text editor, and then deploy by using the command line.

To create a new project named "MyAdventure" using the "adventure" template, run the following command.

    alexa-sfb new --template adventure MyAdventure

Usage of the command

  • new [options] story- Path to new story. You can use this command to create a new story project from a template.

Options for the command

  • -t, --template [templateName] - The template name to use for new skill. The options are example_story, tutorial, adventure, and quiz.
  • -h, --help - This will output usage information.

deploy commands

To deploy your Skill Flow Builder skill, use one of the deploy commands. The standard deploy command takes a story root folder as its main parameter. If you run the command from inside your story root folder you can use a '.'.

For example, if you have created a project named 'MyAdventure', run the following command.

    cd MyAdventure
    alexa-sfb deploy .

The command deploys the skill, creating it the first time by using the Alexa Skills Kit CLI, then the command builds and deploys your skills voice model, skill manifest, and Lambda function code.

Full usage details for deploy are described as follows.

Usage of the command

  • deploy [options] story - Path to a story. You can build and deploy a story to developer portal and AWS Lambda.

Options for the command

  • -o, --override - Use this option to override version check.
  • -s, --stage [stageName] - Use stage to deploy (i.e. dev, test, beta, prod).
  • -l, --locale [localeName] - Use locale to deploy (i.e. en-us, en-gb, fr-fr, etc.) when using different Lambda functions for each locale.
  • -h, --help - This option will output usage information.

If you want to deploy only the metadata for your skill, you can use the deploy-metadata {#deploy-metadata-command}. This will build your skill information and deploy manifest or voice model changes, but not upload your Lambda function code.

    alexa-sfb deploy-metadata .

If your Lambda function code is too big or too slow to upload by using the standard deploy command you can use the deploy-via-zip {#deploy-via-zip-command} command.

This command uses the command line zip function on Mac or Linux and the application 7z on Windows, which must be in your path. The command then uploads your code to the S3 bucket that you specified for your skill, and then uses an update-function-code command to update your Lambda function by using this zip file. On slow connections, using a zip file for deploying your skills is often faster than the standard deploy command.

    alexa-sfb deploy-via-zip .

Create multiple deployment stages

If you want to create a beta stage and a prod stage for your skill, you must create two separate skills in the developer console. To create the two skills you can use the --stage argument with the previously mentioned deploy commands.

To create a stage other than the default stage, run a deploy command similar to the following example.

    alexa-sfb deploy --stage beta .

This command creates a new metadata directory to hold additional ASK skill manifest and deployment files for your skill. You can see these files stored in your projects directory in the "metadata" folder.

    MyAdventure\metadata\ask_config
    MyAdventure\metadata\skill.info
    MyAdventure\metadata\beta\ask_config
    MyAdventure\metadata\beta\skill.info
    MyAdventure\metadata\prod\ask_config
    MyAdventure\metadata\prodskill.info

If --stage isn't passed in your deploy command, your skill will use the top ask_config and skill.info files when deploying your skill. If you specify a stage, the corresponding subdirectory will be used.

Use stage-specific config settings

To use stage specific configuration values at deployment, you can use the previously mentioned--stage option. To use stage specific settings at run time, you need to set the "stage" environment variable on your Lambda Function to the name of your stage.

For example, you may have a default stage, as well as a specified beta, and prod stage for your project, each with its own lambda function. On the non-default stages, you should set an extra environment variable in the Lambda Function named "stage" with the value of either "beta" or "prod".

To set a stage specific variable, edit the abcConfig.json file to add overrides for the specific stage. Any values not found in the stage specific settings revert to using the default settings.

For example, to set different story names, database tables, and invocation names for your project for beta and prod stages, add the following code into your abcConfig.json file.

    "prod": {
        "story-title": "My Adventure",
        "skill-invocation-name": "my adventure",
        "dynamo-db-session-table-name": "myAdventureAttributes-prod",
        "s3-bucket-name": "my-adventure-prod",
        "story-id": "prod-my-adventure",
        "ask-skill-directory-name": "prod-my-adventure"
    },
    "beta": {
        "story-title": "My Adventure - Beta Stage",
        "skill-invocation-name": "my adventure beta",
        "dynamo-db-session-table-name": "myAdventureAttributes-beta",
        "s3-bucket-name": "my-adventure-beta",
        "story-id": "beta-my-adventure",
        "ask-skill-directory-name": "beta-my-adventure"
    }

When you use stage overrides, you can more easily deploy and maintain multiple stages of your skill, each with its own project specific AWS settings.

build command

The build command generates your skills voice model and code locally, but does not deploy them. You can view the output in the ".deploy" folder inside of your project.

simulate command

The simulate command first builds the latest version of your skill's content or code, then starts the command line simulator. You can then type commands into the command line simulator to test your story without requiring a full deployment. The simulator is helpful to quickly testing recent changes you have made to your content.

    alexa-sfb simulate .

By default, the simulator prints out all of the scene instructions executed during the run. If you want to more easily see your own logging, you can run the simulator in a quiet mode:

    alexa-sfb simulate . -q

This command runs the simulator in quiet mode, which suppresses all debugging logs generated by the simulator, and you can only print your own logs.

clean command

The clean command removes the auto-generated parts of your project that are used by deployment. These parts can include the ".deploy" directory and the "clean" build script on your code directory. The command doesn't delete any actual parts of your source content.

upload command

This command uploads the contents of your locale specific resources to S3 for public usage via your skill. Only content within the "public" folder is uploaded to S3. The list of folders to upload is in the abcConfig.json file under the property "public-resource-folders". The S3-bucket used is specified in the same config file with the property "s3-bucket-name".

The following example shoes how to run the command.

    alexa-sfb upload .

The alexa-sfb upload . - command would then upload the following files to S3 for your skill to use.

    MyAdventure\content\en-US\resources\public\audio\trumpet_1.mp3
    MyAdventure\content\en-US\resources\public\images\sample_image.png
    MyAdventure\content\en-US\resources\public\vo\a-fairy-tale.mp3

In the following examples, you can see how you can reference the URL of one of the previous uploaded files from the .abc file, and use the special string "$SNIPPET_S3_RESOURCES_URI" in a snippet in your ABC content.

Snippets.json

{
    "sfx": "<audio src='$SNIPPET_S3_RESOURCES_URI/audio/$1'/>"
}

Story.abc

    *say
        [sfx trumpet_1.mp3]

After you run the code, you receive the following output.

    *say
        <audio src='https://<...your projects s3 url and path>/audio/trumpet_1.mp3'/>

Set up Amazon Polly voices (Optional)

By default, you can use Amazon Polly voices with Alexa SSML without further setup of Amazon Polly. You must perform Additional setup only if you want to use advanced voice-mixing features like background music.

Step 1: Set up AWS IAM role

  • Add the following permissions to your custom IAM policy called "SFB Lambda" that is used by the IAM role for your AWS Lambda function:

    • s3:GetObject for storing and caching the generated sound files.
    • s3:PutObject for storing and caching the generated sound files.
    • s3:PutObjectAcl for storing and caching the generated sound files.
    • polly:SynthesizeSpeech for using the Amazon Polly service to generate the sound file using the Amazon Polly voices.

Example:

    "s3":"GetObject"
    "s3":"PutObject"
    "s3":"PutObjectAcl"
    "polly":"SynthesizeSpeech"

Step 2: Set up Amazon S3 bucket

  • When you create and set up the bucket, make sure to clear the following public access options:

    • Block new public ACLs and uploading public objects. When you clear this option you can add objects that you customers can see. The sound files used by the skill must be public-readable.

    • Remove public access granted through public ACLs. When you clear this option your customers can access the public objects.

Step 3: Configure your skill

The default Alexa SSML syntax supports voice tags. With the tags you can use custom Amazon Polly voices in your skill without additional setup.

Example:

To use Amazon Polly to mix voices with background music,
you need to set up  a few configurable properties.  Otherwise, you can use Amazon Polly voices alone while leaving ```

`polly-config` disabled. The configuration file for the Skill Flow Builder is at
`<your_project_path>/abcConfig.json`.

To configure your skill set up the following configurable properties:

* `"s3-bucket-name"`: Name of the Amazon S3 bucket to store the generated
sound files.

* `"s3-domain-name"`: Name of the domain where your Amazon S3 files are served.
Usually "s3.amazonaws.com" for all global buckets, but if using a regionalized
bucket, you need to provide the correct value.

* `"polly-config -> enabled"`: If true, calls Amazon Polly instead of using
    the built-in `<voice>` tag functionality provided via Alexa SSML.

* `"polly-config -> combineAudioTags"`: If true, combines multiple audio
files into a single .mp3 file.

* `"polly-config -> dontUseCache"`: If true, calls the Amazon Polly
service for every request. If false, the skill tries to use the previously
generated sound files if already generated.

* `"default-narrator -> enabled"`: If true, the narrator's voice is changed
to the Amazon Polly voice instead of Alexa's default voice.

* `"default-narrator -> name"`: Amazon Polly name of the default narrator's voice
as shown in the [voice list](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html).

* `"default-narrator -> pitch"`: Pitch shift of the default voice. Set to
"+0%" to use the default pitch.

* `"default-narrator -> rate"`: Rate/speed shift of the default voice.
Set to "+0%" to use the default rate.
```

Troubleshoot your setup

Windows installation

On Windows, if the error "MSBUILD : error MSB4132" occurs, the windows-build-tools module might be missing. In a PowerShell window with administrator permissions, enter the following code, and then press Enter.

  npm install --global windows-build-tools

Payload

To verify the payload package created by the publish script, find the skill payload at <your_project_path>/.deploy/{your-ask-skill-directory-name}.

To build the payload without performing a deployment, open a command prompt, enter the following code, and then press Enter.

  npx alexa-sfb build <your_project_path>

New package version

When you pull a new version of the Skill Flow Builder package to an existing project, clean the workspace to apply the changes to your project.

  1. Open a command prompt, enter npm install and then press Enter.

  2. To reinstall alexa-sfb enter the following commands.

  cd <your_project_path>
  npm upgrade

Alternatively, if you installed the Skill Flow Builder CLI globally, complete the following procedure.

  • Open a command prompt, and enter the following command, and then replace <sfb> with the full path.
  npm --global upgrade <SFB>/lib/moduleSrc/alexa-sfb

  • On Mac OS add the sudo prefix:

  sudo npm --global upgrade <SFB>/lib/moduleSrc/alexa-sfb

Uninstall the Skill Flow Builder

The Skill Flow Builder package doesn't install additional packages outside of the scope of the project folder.

To remove all traces of the project

  • Remove the directory that contains the project.

On Windows

npm uninstall -g @alexa-sfb/sfb-cli

On Mac

sudo npm uninstall -g @alexa-sfb/sfb-cli