Create and Publish Private Skills (ASK CLI)

You can use the Skill Management API (SMAPI) and the Alexa Skills Kit Command Line Interface (ASK CLI) to mark a skill as private. A private skill is published live, but is not available in the Alexa skill store. A private skill is different from a skill that is in a [beta test][skills-beta-testing] with a set of selected customers.

You can start a skill in the developer portal or create it with the ASK CLI. You then use the ASK CLI and the skill Id to mark the skill as private, and publish it to an Amazon Web Services (AWS) Alexa for Business account.

You can also use the developer console to publish and manage private skills directly, without the need for the ASK CLI. See Create and Publish Private Skills (Developer Console).

Prerequisites to build and publish a private skill

These prerequisites include:

  • An Amazon developer account
  • Node.js 4.5 or higher and Node Package Manager (npm) to install the ASK CLI. Run $ node --version at the command prompt to determine your current version of Node.js. Refer to Node.js Downloads if you need to install Node.js.
  • A skill Id for a skill that is under development
  • The ARN for an AWS Alexa for Business account

Step 1: Install the ASK CLI

Set up ASK CLI as described in Quick Start Alexa Skills Kit Command Line Interface.

Step 2: Download skill manifest

To download the skill manifest for an existing skill, run the following command:

ask smapi get-skill-manifest <-s|--skill-id {skillId}> <-p|--profile <profile>> <--debug>

Options:

--skill-id, -s
Required. Skill ID for the skill for which you want to download the manifest. This value is in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--profile, -p
Optional. The profile under which the skill schema is output. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard output.

This command outputs the schema for the skill with the specified skill Id to the terminal. You can optionally redirect this output to a file using the > operator as seen below.

$ ask smapi get-skill-manifest -s {skill_id} > skill.json

For more information about ASK CLI commands, refer to the ASK CLI Command Reference.

Step 3: Update skill manifest with private distribution mode

By default, skills are publicly distributed. Once you have obtained the skill manifest, add the distributionMode field to the publishingInformation section mark the skill as private. Open the skill manifest file in a text editor, add the following line to the manifest taking care to preserve the JSON format, and save.

"distributionMode": "PRIVATE"

Following is an example of a skill manifest that contains a distributionMode field.

{
  "skillManifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "summary": "This skill starts and ends a meeting",
          "examplePhrases": [
            "Alexa, start the meeting",
            "Alexa, end the meeting"
          ],
          "keywords": [
            "conference"
          ],
          "name": "myConferencingSkill",
          "smallIconUri": "https://someUrl",
          "description": "This skill starts and ends a meeting",
          "largeIconUri": "https://someUrl"
        }
      },
      "isAvailableWorldwide": false,
      "testingInstructions": "account: myTestAccount",
      "category": "SMART_HOME",
      "distributionMode": "PRIVATE",
      "distributionCountries": [
        "US"
      ]
    },
    "apis": {
      "smartHome": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:123456789:function:MyConferencingLambda"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "uri": "arn:aws:lambda:us-east-1:123456789:function:MyConferencingLambda"
            }
          }
        }
      }
    },
    "manifestVersion": "1.0",
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "locales": {
        "en-US": {
          "privacyPolicyUrl": "https://url/privacy.html"
        }
      },
      "isExportCompliant": true,
      "containsAds": false,
      "isChildDirected": false,
      "usesPersonalInfo": false
    }
  }
}

A skill with this field in the skill manifest is not published in the public skill catalog, even if submitted for certification.

Step 4: Upload updated skill manifest

Update the skill with the modified manifest using the update-skill.

An example update skill command looks like the following:

$ ask smapi update-skill-manifest -s {skill_id} -f skill.json

Step 5: Publish the skill

You must submit the skill for it to be published as a private skill. If you are using the ASK CLI, the command to post a skill for publication is submit.

An example submit-skill-for-certification command looks like the following:

$ ask smapi submit-skill-for-certification -s {skillId}

When you publish a skill privately, its status will change to Live in the developer portal. This process can take a few hours.

Step 6: Distribute a private skill

Once your skill has been published (privately) to the live stage, you can:

  • Add a skill to a specific Alexa for Business account
  • Remove a skill from a specific Alexa for Business account
  • List the Alexa for Business accounts that have access to a private skill

Add a private distribution account

You can add an account to the private distribution account list for the specified private skill. This means the specified account will be granted access to the skill. To add an account, run the following command:

ask smapi set-private-distribution-account-id <-s|--skill-id {skillId}> --stage live <--account-id {id}>

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Required. The stage for the skill. The supported value is `live`.
--account-id

Required. Provide the AWS account ID in the exact ARN format: arn:aws:iam::<account ID>:root. For example, if the AWS account ID is 123456789012, you would provide: arn:aws:iam::123456789012:root. You must specify the root and not an individual user for that account.

Remove a private distribution account

You can delete an account from the private distribution account list. This means the account's access to the private skill will be revoked. To delete an account, run the following command:

ask smapi delete-private-distribution-account-id <-s|--skill-id {skillId}> --stage live <--account-id {id}>

List private distribution accounts

You can also list all of the accounts to which a skill has been privately distributed. This means you can obtain a list of all the accounts that have access to the private skill. To list accounts, run the following command:

ask smapi list-private-distribution-accounts <-s|--skill-id {skillId}> --stage live

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Required. The stage for the skill. The supported value is `live`.

Manage skill access from the Alexa for Business console

Once you have set up the private skill for distribution, the customer whose account has been granted access can follow these steps to access the private skill:

  1. Log in to the Alexa For Business console.
  2. Navigate to the Skills > Private Skills tab. Select Review and then Enable the private skill.
  3. Navigate to the Enabled Skills tab. Add the private skill to a skill group to enable the skill on devices in rooms containing that skill group. See the Alexa for Business administrators guide for more information.