Set up a Skill for a Gadget

To create a skill that works with your gadget, follow the steps to build a custom skill and, in the skill configuration, add the Custom Interface Controller as a supported interface. In your skill details, you must also include a description that explains how the gadget and the skill interact, including whether the gadget is required or optional. This topic describes these steps in more detail.

When you write your skill code, you use the Custom Interface Controller to send custom directives to, and receive events from, the gadget. That is, the Custom Interface Controller is what you use on the skill side to send and receive the custom directives and events that you defined in your Custom Interface.

For more details about creating custom skills, see the custom skill quick reference.

• Add the Custom Interface Controller interface
• Write a complete detailed description
• Write skill code that sends the gadget directives and/or receives gadget events

Add the Custom Interface Controller interface

To enable your skill to send directives to, or receive events from, a gadget, you must add support for the Custom Interface Controller to your skill. You can add interfaces to your skill by using the Alexa Skills Kit developer console or the Alexa Skills Kit Command-Line Interface (ASK CLI), as described next.

• Using the developer console – Find your skill in the list, and then under Actions, select Edit. On the left side, select Interfaces. In the interface list, select Custom Interface Controller.
• Using the ASK CLI – To add support for the Custom Interface Controller to your skill by using the ASK CLI, you edit the skill manifest. The skill manifest is a file that contains the JSON representation of your skill metadata. Add CUSTOM_INTERFACE to the list of interfaces that the skill supports, such as in the following example.

  {
    "manifest": {
      "publishingInformation": {
       "locales": {
        "en-US": {
          "summary": "Short description of the skill.",
          "examplePhrases": [
            "Alexa, open sample custom skill."
          ],
          "keywords": [
            "Descriptive_Phrase_1",
            "Descriptive_Phrase_2",
            "Descriptive_Phrase_3"
          ],
          "smallIconUri": "https://smallUri.com",
          "largeIconUri": "https://largeUri.com",
          "name": "Sample custom skill name",
          "description": "This description must describe how the skill interacts with the gadget."
        }
      },
      "isAvailableWorldwide": false,
      "testingInstructions": "1) Say 'Alexa, open sample custom skill'",
      "category": "SOME_CATEGORY",
      "distributionCountries": [
        "US"
      ]
    },
    "apis": {
      "custom": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        },
        "interfaces": [
          {
            "type":"CUSTOM_INTERFACE"
          }	  
        ],
        "regions": {
          "NA": {
            "endpoint": {
              "sslCertificateType": "Trusted",
              "uri": "https://customapi.sampleskill.com"
            }
          }
        }
      }
    },
    "manifestVersion": "1.0",
    "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"
         }
       }
     }
   }
  }
  

  There are two ways to get the skill manifest:

  • New skill – When you create a new skill by using the ASK CLI new command, a simple skill manifest is created for you. This file is called skill.json and it is in the root of the skill project directory that the ASK CLI created on your computer.
  • Existing skill – You can get the skill manifest of an existing skill by using get-skill.

  After you get the skill manifest, you can open and edit the file with a text editor. After you edit it, you can upload it using update-skill or deploy.

Write a complete detailed description

In the detailed description of your skill, which you specify in the developer portal under Distribution > Detailed Description, you must describe how the skill interacts with the gadget. For example, "This skill is designed to work with [gadget name]." You must also mention whether the gadget is required or optional to use the skill. The detailed description appears on the skill's detail page in the Alexa Skills Store.

Write skill code that sends the gadget directives and/or receives gadget events

To interact with a gadget, you add skill code to send directives to the gadget, receive events from the gadget, or both. For more information, see the following topics:

• Send a Gadget a Custom Directive from a Skill – Custom directives enable your skill to create long-running interactions between Alexa and the gadget. The user might participate in the interactions, watch the interactions, or both. For example, you might use custom directives to trigger device behavior based on skill content, support implicit commands from the user, support explicit, but more complex commands from the user, and so on.
• Receive a Custom Event from a Gadget – Custom events enable your skill to process and act on information from the gadget. For example, you might use custom events to trigger an immediate skill response such as voice or audio, report a gadget's status, collect and apply business logic to one or a set of events, and so on.