Steps to Create a List Skill

You can create a list skill when you choose the custom voice interaction model, or you can create a list skill without an interaction model. You update the skill manifest to include the appropriate settings to enable list and skill events.


Follow the ASK CLI Quick Start to install the ASK CLI.

You can create a list skill with a customer voice interaction model or, you can create a list skill without an interaction model. For details about custom skills, see Understand Custom Skills. You can create your skill by using the developer console or the CLI. For details about creating a skill with the CLI, see Create a new skill project.

Create a list skill

To create a list skill, you edit the skill manifest to include the appropriate apis object and the appropriate permissions and events objects.

Complete the following steps to edit the skill.json file.

  1. To subscribe to List events, add the householdList in the apis object.
    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.
  2. Set up your skill to prompt the customer to grant the appropriate permissions so that the skill service can "see" these events. Include a permissions object. The permissions 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.
  3. Include an events object which to describe 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 doesn't include custom in the apis object, a custom interaction model is optional.
  4. Update the manifest for a skill by using the update-skill-manifest CLI command.

If you have an Amazon Web Services (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.

Use list and skill events in your list skill to make your skill responsive

Use list events and skill events 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 isn't in a session with the skill. For example, the customer might be listening to the news or playing a game, when the customer adds an item to their Alexa lists.

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. The following example shows a permissions object that enables the skill to ask the customer for read and write access to their Alexa lists:

    "permissions": [
        "name": "alexa::household:lists:read"
        "name": "alexa::household:lists:write"

After the customer enables the skill, the customer receives cards in the Alexa app that allow the customer to grant or refuse permissions.

Your skill requires the SkillId, ClientId and ClientSecret to obtain the consent token. Complete these steps to obtain these IDs.

  1. Sign in to the Alexa developer console.
  2. From the skill list, locate your custom skill, and then, under the skill name, click Copy Skill ID.
  3. In the dropdown under ACTIONS, select Edit.
  4. Click Build > Tools > Permissions.
  5. To view the ClientId and ClientSecret, scroll to the bottom of the screen, and then click SHOW.
  6. Copy the ClientId and ClientSecret.

Or, you can get the credentials by using one the ASK CLI get-skill-credentials SMAPI subcommand: ask smapi get-skill-credentials -s {skill-id}

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 requires 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