Upgrade to a Multi-capability Skill (MCS) in the ASK CLI

Note: Sign in to the developer console to build or publish your skill.

The skill manifest is the JSON representation of your skill, and provides Alexa with all required metadata. The interaction model and account linking schemas are separate.

Note: All images referenced in a skill manifest must be in PNG format.

For details about the Alexa Skills Kit Command Line Interface (ASK CLI), see Alexa Skills Kit Command Line Interface and Alexa Skill Management API Overview.

For details about the skill manifest, see Skill Manifest REST API Reference).

How to use ASK CLI to update or create a skill with multiple models

The following sections explain how to combine existing skills or create a new skill that combines the features of a Smart Home skill with a custom skill.

Update an existing skill to include smart home and custom features in the ASK CLI
Create a new skill with smart home and custom features in the ASK CLI

Update an existing skill to include smart home and custom features in the ASK CLI

If you have an existing Smart Home skill and custom skill that you want to merge, modify the Smart Home skill manifest file to include the manifest information from the custom skill.

To update an existing skill to include smart home and customer features

Install ASK CLI, set up the AWS user account if appropriate, and initialize ASK CLI, as described in Quick Start Alexa Skills Kit Command Line Interface (ASK CLI).

At the command prompt, type:

ask smapi list-skills-for-vendor

The command output lists all skills in your Amazon developer account. Scroll through the list, and find both skill IDs for the Smart Home skill to modify and for the custom skill you're adding to the Smart Home skill. These skill IDs are also shown in the list of your Alexa skills in the Alexa developer console.
Enter the following command to return the Smart Home skill schema and save the schemas to a new file named "my-sh-skill.json":

ask smapi get-skill-manifest -s YOUR_SMART_HOME_SKILL_ID > my-sh-skill.json
Repeat the get-skill-manifest command for your custom skill, saving the skill manifest to a separate new file named "my-custom-skill.json":

ask smapi get-skill-manifest -s YOUR_CUSTOM_SKILL_ID > my-custom-skill.json
Edit the skill manifest (my-sh-skill.json in this example) to include both the smart home and custom apis entries, as shown in this sample skill manifest.
Update the Smart Home skill with the custom skill, and upload the modified JSON file:

ask smapi update-skill-manifest -s <smart home skill ID> -f my-sh-skill.json

The skill manifest is now updated.
Confirm the update by downloading the skill manifest for the updated skill, and then outputting the combined manifest to a new .json file named "my-skill-multi.json":

ask smapi get-skill-manifest -s YOUR_SKILL_ID > my-skill-multi.json

You should see the changes that you made in the original skill manifest in this new skill manifest file.

Your skill must provide the code to handle the smart home and custom requests, and you must manage the interaction model and account linking schemas for this combined skill. For details, see Handle Requests Sent by Alexa and Steps to Build a Smart Home Skill.

Create a new skill with both smart home and custom features in the ASK CLI

In addition to updating existing skills, you can also create new skills that combine smart home and custom features.

To create a new skill with both smart home and custom features

At the command prompt window, create a new skill with this command:

ask new
Type your new skill name when prompted, such as My-Smart-Home-Custom-Skill.

The ASK CLI creates a new directory with the specified skill name. This directory contains the files for your skill project.
Edit the skill manifest to include the smart home and custom components that you want.
In the skill project files, edit the interaction model and account linking schemas to match what you want for this skill.
Update the skill with the following command. Specify the file name that you used for this skill schema:

ask smapi update-skill-manifest -s YOUR_SKILL_ID -f my-skill.json

Sample skill manifests

Choose the skill manifest for your skill type. For each skill type, adhere to the privacy and compliance requirements.

If you're creating a skill that combines both a smart home and a custom model, you must provide an ARN (Amazon Resource Name) for each skill type in the endpoint field. Also, your skill manifest must include all required objects for both the smart home and custom portions of the skill. Use only the required objects for the new skill.

Combined smart home and custom skill manifest

{
  "manifest": {
    "manifestVersion": "1.0",
    "publishingInformation": {
      "locales": {
        "en-US": {
          "name": "Sample skill name.",
          "summary": "This is a sample Alexa skill.",
          "description": "This skill has basic and advanced smart devices control features.",
          "smallIconUri": "https://smallUri.com",
          "largeIconUri": "https://largeUri.com",
          "examplePhrases": [
            "Alexa, open sample skill.",
            "Alexa, blink kitchen lights."
          ],
          "keywords": [
            "Smart Home",
            "Lights",
            "Smart Devices"
          ]
        }
      },
      "distributionCountries": [
        "US",
        "GB",
        "DE"
      ],
      "isAvailableWorldwide": false,
      "testingInstructions": "1) Say 'Alexa, turn on sample lights'",
      "category": "SMART_HOME"
    },
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "usesPersonalInfo": false,
      "isChildDirected": false,
      "isExportCompliant": true,
      "containsAds": false,
      "locales": {
        "en-US": {
          "privacyPolicyUrl": "http://www.myprivacypolicy.sampleskill.com",
          "termsOfUseUrl": "http://www.termsofuse.sampleskill.com"
        }
      }
    },
    "apis": {
      "smartHome": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "uri": "arn:aws:lambda:us-west-2:010623927470:function:sampleSkillWest"
            }
          }
        }
      },
      "custom": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "sslCertificateType": "Trusted",
              "uri": "https://customapi.sampleskill.com"
            }
          }
        }
      }
    }
  }
}

publishingInformation object

Field	Description	Type
distributionCountries	Array specifying distribution country/region strings in ISO 3166-1 alpha-2 format, for example, US, GB or DE. This array should only contain values if `availableWorldwide` is false.	string array
isAvailableWorldwide	`true` to specify the skill is available worldwide; otherwise, false. If false, list countries for `distributionCountries`.	boolean
testingInstructions	Indicates any special instructions for testing the skill, such as a test account.	string
category	Indicates the filter category for the skill in the Alexa app, such as NEWS or SMART_HOME. Any combination of models that include smart home must use the SMART_HOME category. For details, see Category enumeration.	string
locales	Object that contains locale objects for each supported locale.	Object
locales.locale	Locale string. For each supported locale, include an object with the appropriate locale string. The supported values include `en-US`, `en-GB`, and `de-DE`.	object
locales.locale.summary	Summary description of the skill, which displays when viewing the list of skills.	string
locales.locale.description	A full description explaining the core functionality of the skill and any prerequisites for use (such as additional hardware, software, or accounts). For Flash Briefing, you must list the feeds for the skill.	string
locales.locale.smallIconUri	URL to a small icon for the skill, which displays in the list of skills. (108x108px)	string
locales.locale.largeIconUri	URL to a large icon that represents this skill. (512x512px)	string
locales.locale.examplePhrases	Three example phrases that illustrate how to invoke your skill. For accuracy, these phrases must come directly from your sample utterances.	array of strings
locales.locale.keywords	Sample keyword phrases that describe the skill.	array of strings

privacyAndCompliance object

Field	Description	Type
allowsPurchases	`true` to specify that users are able to make purchases from this skill; otherwise `false`.	boolean
usesPersonalInfo	`true` to specify this skill uses customer information, otherwise `false`.	boolean
isChildDirected	`true` to specify the skill targets children under 13, otherwise `false`.	boolean
isExportCompliant	`true` to specify users can export the skill to any country/region; otherwise, `false`.	boolean
locales	Contains locale objects; each object contains the privacy and terms of use URLs for each supported locale	object
locales.locale	Locale string. For each supported locale, include an object with the appropriate locale string. The supported values include en-US, en-GB, and de-DE.	object
locales.locale.privacyPolicyUrl	URL to the privacy policy for the skill for the locale	string
locales.locale.termsOfUseUrl	URL to the terms of use for the skill for the locale	string

When you create or modify a skill using a skill manifest, you must ensure that the customer meets the privacy and compliance requirements and the export compliance requirement. The requirements for the customer are the same as the customer must comply with if creating a skill on the Alexa developer portal, as shown on the Distribution tab in the Privacy and Compliance page when creating a skill on the portal.

The customer must answer the corresponding questions in order to set the values for the privacyAndCompliance object. If the customer answers Yes, set the value to true, and if the customer answers No, set the value to false. You must not provide default answers or values on behalf of the customer.

Skill manifest field	Corresponding question from Alexa developer portal
`allowsPurchases`	Does this skill allow users to make purchases or spend real money?
`shoppingKit`	Does this skill use Alexa Shopping Actions?
`usesPersonalInfo`	Does this Alexa skill collect users' personal information? Personal information includes any information that can be used to identify the customer, such as full name, email address, and phone number.
`isChildDirected`	Is this skill directed to or does it target children under the age of 13? Please indicate if this skill is directed to children under the age of 13 (for the United States, as determined under the Children's Online Privacy Protection Act (COPPA)). Not Sure? Please indicate if this skill is directed to children under 13. If you are distributing your skill in the United States, please refer to the Children's Online Privacy Protection Act (COPPA) and the FTC's COPPA Guidance and FAQs for more information. Factors to consider in determining if a skill that is distributed in the United States is directed to children include: Subject matter of the skill Presence of child-oriented activities and incentives Type of language used in the skill Music and other audio content in the skill How the skill is described and marketed Intended audience for the skill Failure to provide accurate information may result in termination of your developer account.
`containsAds`	Does this skill contain advertising? Checkbox: I certify that I have read and am in compliance with the Alexa Skills Advertising Policy found here.
`isExportCompliant`	Checkbox: I certify that this Alexa skill may be imported to and exported from the United States and all other countries and regions in which we operate our program or in which you've authorized sales to end users (without the need for us to obtain any license or clearance or take any other action) and is in full compliance with all applicable laws and regulations governing imports and exports, including those applicable to software that makes use of encryption technology.
`locale.privacyPolicyUrl`	Privacy Policy URL (Optional) Link to the privacy policy that applies to this skill. Note: Each locale requires a separate privacy policy URL, if one is provided.
`locale.termsOfUse`	Terms of Use URL (Optional) Link to the terms of use document for this skill. Note: Each locale requires a separate terms of use URL, if one is provided.

permissions object

An array of named permissions for the skill.

Field Description Type

name

Field	Description	Type
name	Contains an array of permissions, which might contain any combination of the following: `alexa::devices:all:address:full:read` (read the full address for the user from the Alexa app settings) `alexa::devices:all:address:country_and_postal_code:read` (read the customer's country and postal code entered from the Alexa app settings)	array

Contains an array of permissions, which might contain any combination of the following:

alexa::devices:all:address:full:read (read the full address for the user from the Alexa app settings)
alexa::devices:all:address:country_and_postal_code:read (read the customer's country and postal code entered from the Alexa app settings)

array

apis object

Field	Description	Type
apis	Array of api-type objects. Some combinations of api-type objects aren't supported.	array
apis.api-type	Includes `custom`, `smartHome`, `video`	enum
apis.api-type.endpoint	Contains the `uri` field	object
apis.api-type.endpoint.uri	Amazon Resource Name (ARN) for the skill's custom Lambda function or HTTPS URL	string
apis.api-type.regions	Contains an array of the supported region objects	array
apis.api-type.regions.region	Two-letter code for the geographic region such as `NA` or `EU`	enum
apis.api-type.regions.region.endpoint	Contains the `uri` and `sslCertificate` fields	object
apis.api-type.regions.region.endpoint.uri	Amazon Resource Name (ARN) for the custom Lambda function or HTTPS URL for the skill	string
apis.api-type.regions.region.endpoint.sslCertificateType	The SSL certificate type for the skill's HTTPS endpoint. Valid values are `Trusted` or `Wildcard`. Only valid for HTTPS endpoints, not for AWS Lambda ARN.	enum
apis.api-type.interfaces	An array of interfaces supported by the skill.	array
apis.api-type.interfaces.type	Includes `AUDIO_PLAYER`, `VIDEO_APP`, `RENDER_TEMPLATE`.	enum
apis.api.smartHome	Contains the smart home configuration for the skill	object
apis.api.smartHome.endpoint	Contains the `uri` field	object
apis.api.smartHome.endpoint.uri	Amazon Resource Name (ARN) for the skill's smartHome Lambda function	string
apis.api.smartHome.regions	Contains an array of the supported region objects	array
apis.api.smartHome.regions.region	Two letter code for the geographic region such as `NA`, `UK`, or `EU`	enum
apis.api.smartHome.regions.region.endpoint	Contains the `uri` field	object
apis.api.smartHome.regions.region.endpoint.uri	Amazon Resource Name (ARN) for the smart home Lambda function for the skill.	string
apis.api.smartHome.regions.region.endpoint.sslCertificateType	The SSL certificate type for the skill's HTTPS endpoint. Can be `Trusted` or `Wildcard`. Only valid for HTTPS endpoints, not for AWS Lambda ARN.	enum
apis.api.smartHome.protocolVersion	(Optional) Version of the Smart Home API. Default and recommended value is '3'. You may create a skill with version '2' for testing migration to version '3', but a skill submission using version '2' won't be certified.	String

Category enumeration values

This enumeration provides category values. The category determines how the Alexa app filters your skill for display. For any skill that includes a smart home model, the category enumeration must be SMART_HOME.

Enum Values
ALARMS_AND_CLOCKS
ASTROLOGY
BUSINESS_AND_FINANCE
CALCULATORS
CALENDARS_AND_REMINDERS
COMMUNICATION
CONNECTED_CAR
COOKING_AND_RECIPE
CURRENCY_GUIDES_AND_CONVERTERS
DATING
DELIVERY_AND_TAKEOUT
DEVICE_TRACKING
EDUCATION_AND_REFERENCE
EVENT_FINDERS
EXERCISE_AND_WORKOUT
FASHION_AND_STYLE
FLIGHT_FINDERS
FRIENDS_AND_FAMILY
GAME_INFO_AND_ACCESSORY
GAMES
HEALTH_AND_FITNESS
HOTEL_FINDERS
KNOWLEDGE_AND_TRIVIA
MOVIE_AND_TV_KNOWLEDGE_AND_TRIVIA
MOVIE_INFO_AND_REVIEWS
MOVIE_SHOWTIMES
MUSIC_AND_AUDIO_ACCESSORIES
MUSIC_AND_AUDIO_KNOWLEDGE_AND_TRIVIA
MUSIC_INFO_REVIEWS_AND_RECOGNITION_SERVICE
NAVIGATION_AND_TRIP_PLANNER
NEWS
NOVELTY
ORGANIZERS_AND_ASSISTANTS
PETS_AND_ANIMAL
PODCAST
PUBLIC_TRANSPORTATION
RELIGION_AND_SPIRITUALITY
RESTAURANT_BOOKING_INFO_AND_REVIEW
SCHOOLS
SCORE_KEEPING
SELF_IMPROVEMENT
SHOPPING
SMART_HOME
SOCIAL_NETWORKING
SPORTS_GAMES
SPORTS_NEWS
STREAMING_SERVICE
TAXI_AND_RIDESHARING
TO_DO_LISTS_AND_NOTES
TRANSLATORS
TV_GUIDES
UNIT_CONVERTERS
WEATHER
WINE_AND_BEVERAGE
ZIP_CODE_LOOKUP

Was this page helpful?

Provide feedback

Last updated: Jul 15, 2024