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 with a set of selected users.
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.
- Prerequisites to build and publish a private skill
- Step 1: Install the ASK CLI
- Step 2: Download skill manifest
- Step 3: Update skill manifest with private distribution mode
- Step 4: Upload updated skill manifest
- Step 5: Publish the skill
- Step 6: Distribute a private skill
- Manage skill access from the Alexa for Business console
- Related topics
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 (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 is123456789012
, 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:
- Log in to the Alexa For Business console.
- Navigate to the Skills > Private Skills tab. Select Review and then Enable the private skill.
- 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.