Your Alexa Dashboards Settings

Steps to Create a List Skill

A list skill has access to list and skill events, allowing a richer and more responsive customer experience.

In order to create a list skill, you can create or update a skill through ASK CLI (Alexa Skills Kit Command-Line Interface), and edit the skill manifest to include the appropriate apis object and the appropriate permissions and events objects.

To create a list skill:

Follow the Quick Start to install ASK CLI and create a new skill.

Edit the skill.json file, which contains the skill manifest file, as follows:

  • Your skill manifest can be either a skill manifest with householdList in the apis object, or a custom skill manifest with an additional householdList field in the apis object. See the sample manifests in Skill Manifest.

  • Set up your skill to prompt the customer to grant the appropriate permissions so that the skill service can “see” these events. Your skill.json file should include a permissionsInfo object, as described in Update Skill Definition to Include Events. The permissionsInfo object enables the skill to ask the customer for read or write permissions to the Alexa lists. This achieves the same result as if you [configure permissions in the developer portal][access-the-alexa-shopping-and-to-do-lists#permissions-setup].

  • Your skill manifest must include an events object which includes your subscriptions to events, as seen in Skill Manifest. Include only those events that are required by your skill.

  • If your skill manifest includes an events object and it does not include custom in the apis object, then a custom interaction model is optional.

  • If using an AWS Lambda function for your skill service, ensure that your AWS Lambda function endpoint is configured with an Alexa Skills Kit trigger. You can do this in the AWS Console, as described here.

If your skill is a custom skill that does not use events, you can continue to manage it through the Amazon Developer Portal, and it is not considered a list skill even if it interacts with lists.

However, if your skill include a householdList component to subscribe to List events, you must manage it through ASK CLI and the skill will no longer be available to edit in the Amazon Developer Portal.

Use List and Skill Events in Your List Skill to Make Your Skill Responsive

The purpose of using list events and skill events is to create a skill that can respond immediately to the customer’s top-level utterances, such as “Alexa, add bananas to my shopping list”, even if the customer is not currently in a session with the skill. For example, the customer may be listening to the news or playing a game, when the customer adds an item to their Alexa lists.

To add this functionality to your list skill, which you created as described in the previous section, follow tehse steps:

  • Edit the skill manifest to enable it to obtain Lists Read and Lists Write permissions from the customer. Refer to the list manifest to see an example of the permissions object in the skill. Here is a sample permissions object that will enable the skill to ask the customer for read and write access to the customer’s Alexa lists:
    "permissions": [
      {
        "name": "alexa::household:lists:read"
      },
      {
        "name": "alexa::household:lists:write"
      }
    ],

When the customer enables the skill, the customer will receive cards in the Alexa app that allow the customer to grant or refuse permissions.

You will require the ClientId and ClientSecret to obtain the consent token for your skill. To see these, refer to the list of skills in the developer portal, and find your list skill. Click the Skill Id and Client Secret link, as shown in the following figure.

Get Skill Id and Client Secret
Get Skill Id and Client Secret
  • Implement account linking to associate customers who enabled your skill with their identity within your app. Your skill manifest must include an account linking object, which you can add to the manifest with the create-account-linking subcommand. See Linking an Alexa User with a User in Your System for general information.

  • In the skill service, implement handlers to respond to list events.

  • Use the Skill Messaging API to access lists when the customer is out of the skill session, as described in Skill Messaging API Reference.

  • If you want your skill to have additional functionality besides syncing lists, add an intent model to your skill. If you also want your skill to include a custom component, it will require a custom interaction model, and you must include a custom object nested in the apis object, as shown in List Skill Manifest With Custom Component.

More Resources to Create List Skills

For more information about using list events in your skill, see List Events in Alexa Skills.

To update an existing skill to include list events, see Add Events to Your Skill with SMAPI.