Steps to Create a List Skill
A list skill has access to list and skill events, allowing a richer and more responsive customer experience.
- Use List and Skill Events in Your List Skill to Make Your Skill Responsive
- More Resources to Create List Skills
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 theapis
object, or a custom skill manifest with an additionalhouseholdList
field in theapis
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 apermissionsInfo
object, as described in Update Skill Definition to Include Events. ThepermissionsInfo
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. -
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 includecustom
in theapis
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 samplepermissions
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. Click the View SkillId and ClientSecret link under the title. Copy the SkillId. In the figure below, Battle Seattle is a list skill.

- Go to https://developer.amazon.com/home.html. Select Settings > Security Profiles. In this list, search for the same SkillId that you copied. Click on this SkillId, and select Web Settings. Copy the ClientId value.

-
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 Understand Account Linking 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 theapis
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.