Steps to Create a List Skill

A list skill has access to list and skill events, allowing a richer and more responsive customer experience. 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 ASK CLI 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. For details, see the sample list 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 your 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 set up permissions in the developer portal.

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

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

  • If using an AWS Lambda function for your skill service, configure your AWS Lambda function endpoint with an Alexa Skills Kit trigger. You can do this in the AWS Console, as described in Configure the trigger for a Lambda function.

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 these steps:

  • Edit the skill manifest to enable it to obtain Lists Read and Lists Write permissions from the customer. Refer to the List Skill Manifest With No Custom Component example to see how to use 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 SkillId, ClientId and ClientSecret to obtain the consent token for your skill. Follow this process to see these.

  • Refer to the list of skills in the developer console, and find your list skill in the titles. Under the skill name, click Copy Skill ID and copy the SkillId. Click the skill name. Click Build > Tools > Permissions. Scroll to the bottom of the screen and click SHOW to view the ClientId and ClientSecret. Copy the ClientId and ClientSecret.

Alternatively, you can get the credentials by using one of these methods:

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 update-account-linking subcommand. For details about account linking, see Understand Account Linking.

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 the Custom Skill Manifest example.

Sample code