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

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.

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

For details about the skill manifest, see Skill Operations (Skill Management API).

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

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

  1. 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 api list-skills

    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 Skills Kit developer console.

  2. 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 api get-skill -s YOUR_SMART_HOME_SKILL_ID > my-sh-skill.json

  3. Repeat the get-skill command for your custom skill, saving the skill manifest to a separate new file named "my-custom-skill.json":

    ask api get-skill -s YOUR_CUSTOM_SKILL_ID > my-custom-skill.json

  4. 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.

  5. Update the Smart Home skill with the custom skill, and upload the modified JSON file:

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

    The skill manifest is now updated.

  6. 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 api get-skill -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

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

    ask new

  2. 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.

  3. Edit the skill manifest to include the smart home and custom components that you want.

  4. In the skill project files, edit the interaction model and account linking schemas to match what you want for this skill.

  5. Update the skill with the following command. Specify the file name that you used for this skill schema:

    ask api update-skill -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 Amazon Developer Portal, as shown on the Privacy and Compliance tab 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 may not provide default answers or values on behalf of the customer.

FieldCorresponding question from Amazon Developer Portal
allowsPurchases Does this skill allow users to make purchases or spend real money?
usesPersonalInfoDoes this Alexa skill collect users' personal information? This includes anything that can identify the user such as name, email, password, phone number, birthdate, etc.
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?

isExportCompliantCheckbox: 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.
containsAdsDoes this skill contain advertising?
privacyPolicyUrlPrivacy 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.
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

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)
  • alexa::household:lists:read (read the customer's Alexa lists)
  • alexa::household:lists:write (write to the customer's Alexa lists)
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