Documenting your skill design

Key takeaways

Explore all possible customer paths through your skill experience by using the storyboarding method to document what should happen in a dialog and when.


In this article:

At all phases of your own design process, asking, answering, and documenting critical information about your customer, their goals, and your solution is essential to creating the best possible experience. Use the guidelines on this page to anticipate and document important customer needs and expectations, translate them to design requirements, then into the design itself. 

Check out “Decide what to build

If you don’t know what to build, aren’t sure if what you’re building supports the right features; or have too many ideas for what to build: 


Check out “Design your dialogs

If you’re ready to start design, have a design in progress, aren’t sure if you’re supporting all the necessary use cases; or, need a low-fi document or prototype to test.


Check out “Finishing touches

If you’ve gotten feedback on a live or beta skill, and incorporated that feedback into your designs, are almost ready to submit to certification; or, already launched a skill you want to improve.


Decide what to build

Determine the value proposition of your skill

Before you start designing and building your skill, you should ask yourself these two critical questions: “What’s in it for your customer?” and “Why use voice?” First, check out the Design Principles to learn about what makes a great conversation with Alexa, and why customers would use their voice to accomplish their goals. Keep those principles in mind as you decide what to build, and how you prioritize all your ideas. 

What’s in it for your customer?

Once you know what general kind of experience you want to build – Is your customer playing a game? Completing a task? Looking for information or content? – you can begin to ask what your skill should do for your customer. Why would they converse with your skill? What are they going to expect to be able to do? You might have to search existing data or survey your customers (or potential customers) to understand what their needs and goals are, and how likely they are to use Alexa to meet those needs and goals.

If you have an existing customer-facing product or service, such as a mobile app or website, use what you already know about your customers to decide how Alexa can help. Is there a question they constantly type into your search bar that Alexa could handle? What does the app or website do that would be faster, easier, or more fun with Alexa? Consider also any expectations your customer might already have of your skill because they’ve interacted with your brand or experience elsewhere before. Further, be aware that your skill name, as well as your skill description, might also work to set the right (or wrong!) expectations for your customers about what your skill will do.

For example, if we want to create a hypothetical game skill called “Seattle Super Trivia,” our customers might expect our game to do at least the following, as do most trivia games:

  • Greet them
  • Tell them the rules of the game; tell them how to play; Offer them help when they need it
  • Ask trivia questions about Seattle
  • Track right/wrong answers
  • Recognize special achievements; track their personal best or milestones

Why use voice?

For example, If we consider the design principles while deciding how to design our hypothetical game skill called “Seattle Super Trivia,” a player might say the following about our game:

  • “I like to play hands-free while I do the dishes”
  • “I come back every day to keep my winning streak alive”

and our skill can present compelling use cases for voice by adding features such as the following …

  • Allowing customers to answer trivia questions in their own words (supports a robust set of utterances); Supporting trivia questions in true/false and multiple-choice
  • Providing an exciting medium to experience trivia; Sound and voice provides another dimension to experience and formulate trivia questions (identifying a song, setting a sense of place with ambient sounds)
  • Being a personable, engaging, and entertaining game host

Once you’ve completed the above to determine who your customer is, what they need, and what compelling voice experiences might fulfill them, you might want to create a list of requirements Now you’re ready to choose a skill type and write your first conversation …


Questions for a better CX

  • Who is my customer? What are they like? What do they need?
  • What would be faster or easier with Alexa than the alternatives?
  • What would be more fun with Alexa than the alternatives?
  • Why would a customer use Alexa rather than the alternatives?
  • What do you want your customer to say about your skill?
  • What will customers expect my skill to do?
  • How often would customers use the skill?
  • What customer expectations will my skill name set?


Choose a skill type

There are a number of ways to bring your ideas to life as an Alexa skill. Each skill type has a built-in set of capabilities that may fit the technical needs of your skill’s design requirements, or you can create your own custom skill. 

To create ... Use this skill type

A skill made to your specifications that can handle just about any type of request. For example:

  • Look up information from a web service.
  • Integrate with a web service to order something (order a car from a ride-share company, order a pizza from a restaurant).
  • Play interactive games.
  • Do just about anything else you can think of!
Custom skill (custom interaction model) You define the requests the skill can handle (intents) and the words customers say to invoke those requests (utterances).
A skill that lets customers control cloud-enabled smart home devices, such as lights, door locks, cameras, thermostats, smart TVs and much more. For example:
  • Turn lights on and off
  • Change the brightness of dimmable lights
  • Change the color or color temperature of a tunable light
  • Change the temperature on a thermostat
  • Find out if the door is currently locked
  • Watch a home camera feed
  • Change the volume on a speaker
  • Change the channel of a TV
Smart Home Skill API (pre-built model) The Smart Home Skill API defines the requests the skill can handle (device directives) and the words customers say to invoke those requests (utterances).

A skill that lets a customer control cloud-enabled video. For example:

  • Play a movie
    Find a TV show
  • Change a channel
  • Pause, rewind, or fast-forward video content
Video Skill API (pre-built model) The Video Skill API defines the requests the skill can handle (device directives) and the words customers say to invoke those requests (utterances).

A skill that provides original content from:

  • Podcasts
  • Livestream
  • RSS feeds
Flash Briefing Skill API (pre-built model) The Flash Briefing Skill API defines the words customers say to invoke the Flash Briefing or news request (utterances) and the format of the content so that Alexa can provide it to the customer.

For details about the different models, see About Voice Interaction Models. After you've decided on the type of skill you want to make, you can start designing the conversation.


Design your dialogs

Create a happy path

Checklist for writing “happy paths:"

▢  Take as few conversation turns as necessary to start the core purpose or content of the skill

▢  Take as few conversation turns as necessary for the customer to complete a task

▢  Your happy path example represents the typical and best possible experience various types of customer can have in the skill

Depending on how many functions, and what kind your skill will support for your customer; your design may need to support a large volume of edge cases and errors. Before you dive in, try writing one great sample conversation first. This “happy path” should demonstrate the best (most helpful, delightful) interactions your customer can have with your skill, and will act as your “North Star“ to guide you as you complete the rest of the design. Depending on the scope of your skill, you may want to write more than one happy path so you can demonstrate all your skill’s core features working at their best.

Read the following “happy path” for our hypothetical trivia skill. This customer hasn’t played the game before.


Player: Alexa, start Seattle Super Trivia.

Host: Welcome to Seattle Super Trivia. It’s OK, you’ve probably never heard of it. Think you know Seattle? Think again, transplant. I’m about to school you! Are you ready to take the Seattle Super Trivia challenge?

Player: Yes.

Host: I can see you’re a tourist here, so hold on to your umbrella. Each day I’ll have five fresh trivia questions for you. Answer them all correct, and earn a sudden-death bonus round. I’ll give you one hint each day. Alexa will keep score for us.

Alexa: Happy to help. Want to try a practice question?

Player: No.

Host: Let’s get to it then. First question: When was the city of Seattle founded? Was it … A. 1861. B. 1902., or C. 1792?

Player: I don’t know.

Alexa: (whisper mode) Psst. I can give you one hint daily for free. Do you want to use your free daily hint?

Player: Yes, ok.

Alexa: Ok. Here’s a hint. It doesn’t rhyme with the first line of that silly song about Columbus sailing the ocean blue. So, When was the city of Seattle founded? Was it … A. 1861. B. 1902., or C. 1792?

Host: So. When was the city of Seattle founded? Was it … A. 1861. B. 1902., or C. 1792?

Player: It was A.

Alexa: Awesome! That’s correct! The City of Seattle was founded in A: 1861. It was a Wednesday. 

Storyboarding your design

Now that you have your happy path guiding your way, you can begin to think through all the edge cases your skill will need to support. You might find it helpful to start making a list or logic chart to help you track all those cases (or you might find it more helpful to do so after the next step), but you’ll want to quickly move into capturing the full scene of each step in the interaction. Much like you would a screenplay, you’ll need a way to demonstrate at each step of the interaction …

  1. What was said (by your customer)
  2. Who that customer is, what is their context
  3. What Alexa will say in response
  4. What will Alexa say and do to help the customer next?
  5. What will devices with a screen display?

You can use a storyboard format like the one below to document those aspects in one place, turn-by-turn.

For example, the storyboard for the first turn of our customer’s first conversation with our trivia skill might look something like the following …


Our customer invoked the skill. The skill recognizes that they have never used the skill before, and surfaces a unique welcome message. The skill can either follow up by asking the customer if they want to start the game, or it can move on to the next storyboard (giving them the instructions) automatically.


Just two steps into storyboarding our happy path we created previously, and there are a number of additional edge cases with their own dialogs we need to document. 

  • They’ve used the skill before; they don’t need instructions
  • They’ve used the skill before, and they recently had a trivia game already in progress
    • They agree to continue their game
    • They decline to continue their game, and want to start a new one
  • They’ve used the skill before, and this is the 100th day in a row they’ve opened the skill (we want to celebrate)
  • The player has already played the daily game and received a score for that day


  • Gets an answer correct; gets several correct in a row
  • Gets an answer wrong; gets several answers wrong in a row
  • Asks for a hint:
    • They haven’t yet used a hint that day
    • They’ve already used a hint that day
  • Goes into a sudden death round
    • They get a question correct
    • They get a question wrong
  • Gets a personal best high score
  • Asks to quit the game
  • Asks for help 


Each of the above cases will be its own storyboard. When you can no longer anticipate any more customer responses and questions, and have written an appropriate response for each context you thought of, your design is complete, and you can begin testing your designs right away.

Your storyboards for a simple trivia skill like the one above might look something like this:


Use the storyboards to conduct your first tests. You should play the role of Alexa and recruit some testers to try speaking to you ask they would your skill. Did you have a response written to what they said? Did they say something for which you didn’t have a response? Create a new storyboard.

Is the conversation flowing well? If you can find appropriate storyboards to create a smooth conversation with them as they speak, your design is ready for you to start prototyping and building. 


Finishing touches

There are a few more ways your skill can sound natural and provide a brief, contextual, multi-modal, and trustworthy experience that aren’t captured in the above style of documentation. Consider how your skill dialog will …

Title Placeholder Title Placeholder

Vary its responses customers will hear most often

Create a phrase or word bank for varied responses (especially confirmations like “Ok” or “Got it,” and prompts like “What would you like?”)
Support a robust set of possible utterances from customers Create a list of alternative ways a customer will invoke and use the functions of your skill (“Alexa, help”, “I need help”, “How do I play?” “I don’t know what to do”) 
Document touch capabilities Either on your storyboards on another document, demonstrate different states of the display elements and indicate touch targets

Sound pleasing to the ear

Either on your storyboards on another document, document in SSML (Speech Synthesis Markup Language) how you want Alexa to say the speech itself (faster? slower? more casual?)

Previous Article: