Define Skill Metadata

Users can scroll or search through the list of published skills in the Alexa app and read information about those skills in detail cards. You need to define this detail card by filling in the relevant fields in the developer portal. Providing good content for your detail card helps users discover, understand, and use your skill.

The detail card displays the following information (illustrated below):

  Description Field in Developer Portal
A. The name of the skill, displayed at the top of the detail card. Skill Information > Name
B. An icon representing the skill. Publishing Information > Images
C. Three example phrases that illustrate how users can invoke your skill. For accuracy, these phrases must come directly from your sample utterances. See Defining your Example Phrases (“Try Saying”) below. Publishing Information > Example Phrases
D. A full description explaining the skill’s core functionality and any prerequisites to using it (such as additional hardware, software, or accounts).

You also provide a short description, which is shown when viewing the list of skills.
Publishing Information > Full Skill Description

Publishing Information > Short Skill Description
E. The invocation name that users say to invoke your skill. For example, if the invocation name is “tide pooler”, users can say “ask tide pooler…” to begin interacting with the skill. Skill Information > Invocation Name
Detail Card for a Skill in the Alexa App
Detail Card for a Skill in the Alexa App

In addition, the list of skills shows a smaller set of information for each skill:

  • Skill name (Skill Information > Name) and icon (Publishing Information > Images).
  • A short description (Publishing Information > Short Skill Description).
  • The first of the three example phrases (Publishing Information > Example Phrases).

This example shows how Tide Pooler appears in the list of skills. Note the short version of the description and the single example phrase:

Skill shown in the list
Skill shown in the list

Defining your Example Phrases (“Try Saying”)

The three example phrases show users what they need to say to begin using your skill. As shown above, the first phrase is shown in the list of skills, and all three are displayed prominently on the detail card. To ensure accuracy, these phrases must meet specific requirements:

  • If you use utterances for an intent you defined, the phrases must come directly from your sample utterances.
  • If you use utterances for a built-in intent, either use the exact phrase provided in the documentation for the intent or a variation of this phrase. Be sure to fully test the utterance and verify that it works and your skill returns a valid response. If the example utterances you provide fail to return a valid response during certification, your skill will fail certification.

To create the example phrases for the detail card:

  1. Review your sample utterances and select three that will help users get started and access your skill’s core functionality.
  2. Fill in a valid value for any slots in those utterances. If the utterance uses a slot defined with a custom slot type, use a value explicitly defined for that custom slot type.

    • For example, the {City} slot in the utterance OneshotTideIntent when is high tide in {City} uses custom slot type called LIST_OF_CITIES. When filling this slot in, you would use a city that is explicitly defined in LIST_OF_CITIES.
    • For more about custom slot types, see Define the Interaction Model in JSON and Text.
  3. For at least the first phrase, combine the utterance with the default wake word (“Alexa”) and your skill’s invocation name.

    • Use title case for your invocation name (for example, “Tide Pooler”, not “tide pooler” or “Tide pooler”).
    • Make sure the phrase is grammatical and uses appropriate punctuation.
    • For example, the utterance when is high tide in {City} becomes “Alexa, ask Tide Pooler when is high tide in Seattle.” In this example, “ask” is one of the supported words for invoking a skill and “Tide Pooler” is the invocation name.
  4. Enter the three phrases in the Example Phrases field on the Publishing Information tab for your skill.

For example, the Tide Pooler skill includes the following sample utterances:

OneshotTideIntent when is high tide in {City}
OneshotTideIntent when is high tide in {City} {State}
OneshotTideIntent when is high tide in {City} city
OneshotTideIntent when is high tide in {City} on {Date}
OneshotTideIntent when is high tide on {Date}
OneshotTideIntent when is high tide {Date}
SupportedCitiesIntent what cities
SupportedCitiesIntent what cities are supported
SupportedCitiesIntent which cities
OneshotTideIntent get high tide for {Date}
OneshotTideIntent get high tide {Date}
OneshotTideIntent when is high tide {Date}
OneshotTideIntent tide information
OneshotTideIntent tide information for {City}

For this skill, the developer chose the following three utterances:

OneshotTideIntent when is high tide in {City}
OneshotTideIntent when is high tide in {City} on {Date}
SupportedCitiesIntent what cities are supported

They replaced the {City} slot with actual values from the LIST_OF_CITIES custom slot type (“Seattle” and “San Diego”) and created the following three example phrases for the detail card:

  • “Alexa, ask Tide Pooler when is high tide in Seattle”
  • “Alexa, ask Tide Pooler when is high tide in San Diego on Saturday”
  • “Alexa, ask Tide pooler what cities are supported”

In this particular example, all three phrases are in question format. The developer could have chosen a different set of phrases from the above utterances, such as:

  • “Alexa, tell Tide Pooler to get high tide for tomorrow
  • “Alexa, ask Tide Pooler for tide information for Los Angeles

Again, note that these variations also come from the list of sample utterances:

OneshotTideIntent get high tide for {Date}
OneshotTideIntent tide information for {City}

Previewing the Detail Card in the Alexa App

Once you have entered all of the information for your detail card, be sure to open the Alexa app and preview the card. The app shows both published skills and your own skills currently in development, so you can see how your card will appear to users. You can enter the name of your skill in the search box to filter the list of skills.

Next Steps

See all coding topics:

Other topics:

Reference materials: