Design the Custom Intents for Your Skill

An intent represents an action that fulfils a spoken request and each intent has a set of sample utterances attached to it. Custom intents serve the functions that are unique to your skill. See the following best practices to get the most out of your custom intents and sample utterances.

Sample utterance variety and length

Include a variety of sample utterances in the interaction model because it helps to train the natural language understanding model. When in doubt, include more rather than fewer sample utterances. Sample utterances help the skill to achieve the user’s objective even when the sample utterances don't include the request word-for-word.

Phrase patterns

Include synonyms as well as common phrases that users might say to make a request of the skill. They could include diverse range of words, formatting or formality tones, for example formal, semi-formal, and informal, to cover the broader aspect of various requests. For example:

  • what is the weather
  • what's the weather
  • today's weather
  • what would today's weather be like
  • present weather condition

Variations can also include prefixes and suffixes like ‘please’, ‘can you’, and ‘tell me’, to better train the natural language understanding model to achieve the objective even if the exact spoken utterance isn't present in the sample utterances.

Word length

The interaction model should include basic or one-word sample utterances, such as:

  • products
  • options
  • features

The interaction model should also include multi-word or long sample utterances, such as:

  • what products do you have
  • what are my options
  • features available

Sentence structure

The sample utterances can be in the form of statements, commands, or questions, such as:

  • options
  • give me my options
  • what options do I have

The interaction model should support sample utterances that work on their own inside the skill, as well as sample utterances that allow the user to launch the skill and directly access skill functionality.

Skills should include sample utterances that users might say when they are inside the skill. The sample utterances should be independent requests that work on their own as a user request and are complete sentences. For example:

  • tell an animal fact
  • i want to order food
  • can i know my horoscope
  • what is the weather today

For some skills, users might open the skill and make a request simultaneously. For such skills, the sample utterances should cover a possibility where the requests would be grammatically correct when combined with a supported launch phrase. For example, a user might say:

  • ask grocery store what the price of an apple is
  • ask animal facts for an animal fact

Such requests include the invocation names like ‘grocery store’ and ‘animal facts’ in combination with the requests ‘what the price of an apple is’ and ‘an animal fact’. Although ‘what the price of an apple is’ and ‘an animal fact’ aren't complete sentences on their own, make sure to include them to account for user requests made from outside the skill.

To help route user requests, the natural language understanding model uses keywords from the sample utterances, and also compares the length of the sample utterance to the user's utterance.

Language use and localization

The sample utterances should be appropriate for the language and the marketplace in which the skill is released. If the same skill is available in multiple marketplaces like American English, Australian English, British English, and Indian English, the sample utterances for each marketplace should reflect the common ways in which the local users would make a request. For example:

  • If users can ask to add a particular food item in their list, American English skills might include variants of sample utterances with the local word ‘cookies’ and ‘fries’ whereas the British English skill should include variants like ‘biscuits’ and ‘chips’ for the same or similar requests.

The language of the sample utterances should match the language of the skill. The sample utterances should reflect what the local users might say inside the skill, because a skill developed in a particular language won't be able to handle requests made in another language correctly. For example:

  • An English language-based skill shouldn't include sample utterances written in Devanagari or Hindi. The English skill is unlikely to understand Hindi utterances correctly.

Marketed phrases

Any example phrases included in the Alexa companion app, prompts for the skill, or any skill marketing materials showing what the users might say to interact with the skill, should be covered in the sample utterance exactly. The sample utterances shouldn't include the wake word, like Alexa, nor any phrasing for opening the skill. For example:

  • If your prompt tells customers that they can say ‘what is my horoscope’ inside the skill to know their horoscope, the interaction model should include the sample utterance ‘what is my horoscope’ to support the example phrase.

Relevant sample utterances

The sample utterances included in the interaction model should be relevant to the functionality of the skill. The sample utterances included should only reflect the requests that users are likely to say to access the available functions. For example:

  • A food ordering skill should only cover the sample utterances related to ordering the food, tracking the order, or asking for menu. The same skill shouldn't include sample utterances to know about a horoscope or listen to a podcast.

Test your utterances

Each sample utterance introduced in the interaction model should be unique and shouldn't match word for word with any other sample utterance included in a different custom intent. If your interaction model includes utterance conflicts, Alexa attempts to resolve to the correct intent, but may not be able to. For example, if the skill includes the same sample utterance ‘how’s the weather going to be’ to check for the week’s weather as well as to check for today’s weather, the skill may be unable to determine if the user is asking for the week’s weather or today’s weather and may not answer appropriately.

Test your utterances with the utterance profiler as you build your interaction model. For details, see Test Your Utterances as You Build Your Model.

When possible, each intent should support a single function. This can help the skill provide a better customer experience.

Avoid invocation phrasing in sample utterances

The sample utterances should not include the invocation name by itself or in combination with supported invocation phrasing. For example, if a skill has an invocation name ‘Animal Facts’ the skill shouldn't include sample utterances like:

  • animal facts
  • open animal facts
  • start animal facts

There are some exceptional instances where the invocation name can be included in sample utterances, if customers are likely to say it naturally when interacting with the skill. For example:

  • If the skill only plays a radio player, the users most likely would open the skill and ask to play the radio player. In such cases, you might include sample utterances like ‘play radio player’ inside the skill even though it is a supported invocation phrasing.

Customers can invoke a skill with a request using certain phrases. The launch phrasing and request usually have a connecting word. For example:

  • Ask animals facts to tell me a fact
  • Open help desk and help me

Connecting words shouldn't be included in the beginning of the sample utterances because they won't be included in the skill request. For example:

  • The skill shouldn't include a sample utterance ‘to tell me a fact’ or ‘and help me’, because the connecting word won't be sent to the skill.

Connecting words should only be included in the sample utterances if likely for the user to say and crucial to the meaning. Consider ‘to be or not to be’, which would be incomplete on its own if present in the skill as ‘be or not to be’.

Typos, grammar, and formatting

The sample utterances should be free from typographical errors or grammatical mistakes, and any abbreviations written out as they would be said aloud. For example:

  • The sample utterances should include the word ‘doctor’ instead of ‘Dr.’, or ‘miss’ instead of ‘Ms.’

The sample utterances shouldn't include any punctuation, such as commas, semicolons, or parentheses, except apostrophes, hyphens, and periods where appropriate. Write any symbols in spoken form where appropriate. For example:

  • ‘3.3’ should be written ‘three point three’ and ‘$1’ should be written as ‘one dollar’.

The sample utterances should follow all tokenization best practices:

  • Numbers, including Roman numbers, should be spelled out. For example, ‘twelve’ and ‘four’ instead of ‘12’ and ‘IV’.
  • Abbreviations and acronyms should be written in lowercase and should be separated by a period and a space. For example, ‘nba’ should be written as ‘n. b. a.’
  • When a language includes multiple character sets, write your sample utterances in the most appropriate local form. For example, in a Hindi skill, Hindi words should be written in Devanagari while English words are in Latin script.

Using slots in sample utterances

Slots can be used to build parts of sample utterances or can be used together to build entire sample utterances. For more information, see Create Intents, Utterances, and Slots.

To easily support user requests that use the same phrasing but change one or more words or values, consider using a slot. For example, if the user wants to add ingredients in a list:

  • add apples to my list
  • add oranges to my list
  • add carrots to my list

Instead of writing sample utterances for each item, the sample utterance could make use of a slot. For example:

  • add {Ingredient} to my list

This {Ingredient} slot would include values like 'apples', 'oranges', and 'carrots', which would reduce the number of repetitive sample utterances required in the interaction model. For more information about slots, see Design the Slots for Your Skill.

Use unique slot names

Each sample utterance should include a particular slot only once. If you use the same slot type in a particular sample utterance multiple times, link the same slot type to a different slot name. For example, if the sample utterance must include the Ingredient slot type two times in the same sample utterance, use two different slots {IngredientA} and {IngredientB} in the sample utterance, each associated with the Ingredient slot type.

Slot-only sample utterances

Certain functionality of the skill may require users to say one word utterances. For example:

  • In a quiz skill, a user might provide an answer to the quiz question as a single word.

  • If you include a slot-only sample utterance in the interaction model, include it in its own intent with no other sample utterances.

Implementing slot filling

If certain pieces of information are required to complete an interaction, you can add slot filling to your skill to capture the values. Alexa treats user utterances for slot filling separately from the sample utterances; these user utterances would only be used once the skill opens a dialog with the users.

All slot filling user utterances must include the slot to be filled in each user utterance, so that the skill can decide what part of the utterance should be used to fill the slot, and which words are around the slot.

For example, you might use slot filling to complete the following interaction:

  • User: order some food

The user hasn't provided specific information about what food item they want to order, so the skill could use slot filling to open a dialog with the user to ask for specifics:

  • Alexa: What would you like to order?
  • User: I want to order a burger

In this case, the skill should include a slot filling sample utterance like ‘I want to order a {FoodItem}’ where {FoodItem} is the slot and contains the value burger. The skill would then know that burger is the food item that the user wants to order.

For more details on slots and slot filling, see Design the Slots for Your Skill.

Alexa Conversations

Alexa Conversations is a learning–based approach to dialog management. To decide whether Alexa Conversations or a custom skill might work better for your skill, see Should I build my skill with Alexa Conversations?.

Was this page helpful?

Last updated: Nov 28, 2023