Establish the purpose and user stories

Start with what people want to accomplish, and determine the capabilities of your skill and the benefits of using it. Then, identify stories that describe what people need to and can do. Later, use scripts and flows to identify details and variations for the interactions.

Identify the purpose and capabilities

Describe one or more scenarios in which people will find your skill useful and desirable. Determine the capabilities of the skill by asking the following questions:

• What is the purpose of the skill? Why will people want to use it?
• What will the person be doing before, during, and after interacting with the skill?
• What will people get from the skill that they cannot get another way?

Identify the user stories

Based on the purpose and capabilities of the skill, identify individual steps and actions.

• What can a user do, or not do, with the skill?
• What information is the person expected to have available?
• What are the ways a user can invoke the skill?
• What features directly support the purpose?
• Is there information that you need from other experiences, for example from a website or from a mobile app?

Write scripts

Scripts show the conversation between the user and Alexa, like in a movie or play, and are a great way to determine how conversation will flow. Use scripts to help identify situations that you may not have already accounted for.

Consider the following when writing a script:

• Keep interactions brief.
• Write for how people talk, instead of how they read and write.
• Avoid repetitive phrases.
• Indicate when the user needs to provide information.
• Don’t assume that the user knows what to do or what will happen.
• Clearly present options.
• In general, provide no more than three choices at a time.
• Ask for information one piece at a time.

Develop the flow

A basic script doesn’t fully represent how people will interact with your skill in real life. Users may say too little, too much, or say things that you weren’t expecting. Use the following techniques to expand your script and catch various ways in which a user might accomplish tasks:

Outline the shortest route to completion

The shortest route to completion is generally when the user gives all information and slots at once, an account is already linked if relevant, and other prerequisites are satisfied in a single invocation of the skill.

Outline alternate paths and decision trees

Often, what the user says doesn’t include all information necessary to complete the request. In the flow, identify alternate pathways and user decisions.

Outline behind-the-scenes decisions the system logic will have to make

Identify behind-the-scenes system decisions, for example with new or returning users. A background system check might change the flow a user follows.

Outline how the skill will help the user

In the help, include clear directions for what users can do with the skill. Based on the complexity of the skill, the help might provide one simple response or many responses.

Outline the account linking process, if present

Determine the information that is required for account linking. The flow also needs to identify how the skill will respond when account linking hasn’t been completed.

Get ready to build

Once you have a script and a detailed flow, start creating the structure for what your skill does and what users will say to engage with it.

Identify intents

Intents represent the unique things that your skill is able to do. A skill for planning a trip might have five intents, for example PlanATrip, BookTheTrip, Stop, Cancel, and Help.

For information about producing a list of intents alongside your script and flow, see What Users Say.

Identify utterances

Utterances include the robust list of words, phrases, and sentences users will say to engage and fulfill the intent. For example, to use the PlanATrip intent, the user might say “Plan a trip,” “Plan a trip for next Friday,” or “Plan a hiking trip to Portland.”

For information about identifying utterances, see What Users Say.