8 Tips for Effective Skill Description And Metadata Writing

A well-written skill description makes a first impression on your customer and sets the right expectations about the values it brings. However, this space is often given less weightage during skill building. Our top skill developers always use this space well to convey what value their skills offer to a new or existing customer and periodically update their skill description and metadata, when they update their skills. This also helps skills’ searchability on the Alexa Skill store.

Your skill may be the best of all time, but if its description isn’t written fittingly, there’s a high chance that the customer may not understand value of your skill and it may even miss a chance to be enabled.

In this blog, we’ll share 8 Tips for writing an effective skill description under the distribution tab on developer console which will make your skill stand out on Alexa skill stores. Let’s get started:

Tip# 1 – Use an Appropriate Skill Name

Choose an appropriate “Skill Name” which is easy to remember as well as relevant to core functionality of the skill. This space also works best for metadata keyword search. Having a fitting skill name will set the right expectation about the skill with customers. For instance, look at the following example:

_{Skill Title: Order a Pizza}

_{Skill Description: Now learn to cook Pizza at your home any time. The skill brings your 100+ authentic easy-to-cook pizzas recipes at home for small get together, kid’s party, family dinner or special occasion. The recipes are healthy, tasty and simply out of the world.}

In the above example, a customer may understand from the skill name that one can order a pizza whereas upon reading the skill description, it conveys that it provides pizza recipes. This would be confusing for the customer and they may decide to not use the skill.

Also, the skill may not be able to pass the certification process as the title seems to be confusing.

Let’s take another example:

^{Skill Name: Rain Sound ShuttleSkill}

^{Description: The skill plays soothing fire sound for 20 minutes. You can ask anytime “Alexa open fire sound” and relax.}

Again, in the case it isn’t clear for a customer which sound it is going to play. The skill name and description talk about two different kind of sounds i.e. Rain sound in skill name and fire sound in skill title. Such writing or confusion must be avoided as it may lead to bad customer experience.

Tip# 2 – Write the Description from Customer Perspective

A well-written skill description aims to showcase what value it is going to add. Usually it is recommended to add this information in initial two sentences which proves to be quite useful. Description should be simple and concise and should be written from a customer perspective like skill utility or functions e.g.

^{Skill Name: Bollywood Quiz}

^{Skill Description: This is a Bollywood Quiz.}

Instead a better description would be

^{Skill Name: Impossible Bollywood Quiz}

^{Skill Description: “Rishte mein to hum tumhare kya lagte hain?” If you can’t answer that, there’s no point trying this skill. However, if this question gives you a chuckle, then you have come to the right place. Impossible Bollywood Quiz is not for the faint hearted. All those years of watching Hindi movies and memorizing umpteen songs and dialogs from those movies, can get washed away once you encounter the completely insane options for the questions.}

^{So, before you try our skill, simply because you love Bollywood so much, we suggest that you take a deep breath, relax and just say: Alexa, let’s play the Impossible Bollywood Quiz.}

^{The skill’s response will be in Hindi/Hinglish.}

Also, ensure that the description does not misrepresent any functionality of the skill or claim any additional features which aren’t there. For e.g. a skill description states that it plays music from 80’s Hollywood hits but it does not play 80’s Hollywood music rather it is a Hollywood quiz.  Also,  another example would be a description mentioning to have anti-virus features included.

Having this will lead also to rejection of your skill.

Tip# 3 – Skill Description language must be same as Alexa account Language

For better customer engagement, a lot of developers make multi-locale skills which may get them larger customer base. Therefore, it is important that the correct locale language is used in metadata fields, namely skill long description, example phrases and URLs.

Locale language is the language of the country you are creating the skill for like for example – Japanese for Japan, German for Germany, English for US, UK, Australia, India, Italian for Italy, Portuguese for Portugal, Spanish for Spain and US_ES, and French for France. etc.

For instance, if a skill supports English and German locales, each locale must have the description in their respective language. Please ensure it does not have a mix of words from two different languages which is not a good developer experience and may also lead to rejection in the certification process. For example:

^{“Alexa ask Question of the Day” [correct ]}

 ^{“Alexa frage Question of the Day”  [Incorrect – as frage is German and the rest is in English]}

Mixing words or sentences from two different languages is not permitted except in case of Hindi- Indian language.  For instance, for Hindi - Latin content should be in Latin and Hindi words in Devanagari for e.g. यह skill Delhi शहर के बारे में तथ्य देता है  is correct.

However, if Hindi language words are written in Latin script i.e English for e.g.  "yah skill delhi shahar ke bare me tathy deta hai" will lead to rejection.

The second one is basically Hindi language written in Latin as script for English is Latin and Hindi is Devanagari.

Tip# 4 Use Correct Invocation Name and Wake Word for Example Phrases mentioned in Metadata

Sometimes, due to incorrect invocation name or wake word, the skill does not pass skill certification. Therefore, it is recommended to ensure that all visible example phrases on skill detail page must show the content that is intended to be spoken exactly by Alexa customer. Below are the few key points to be remembered:

1.      First example phrase in skill metadata must always contain correct invocation name and wake word.

Ideally, following the below structure for example phrases serves as the ideal baseline:  

Alexa <launch phrase> <invocation name> <action or utterances mentioned in the documentation Sample Utterance of custom intents>

2.  In case 2 and 3 example phrases, wake word and invocation name are recommended but optional.

3.     Any sample utterance visible on the skill detail page must be mapped to intent schema.

4.     If invocation name is part of any example phrase it must be accurate and free of spelling, omission or typing errors.

5.      All example phrases must be free of emoticons, grammar or typing errors.

For more information, you can refer to the review and test example phrase documentation.  

Tip# 5  – Mention compatible device(s) and all functions for Smart Home Skills

If you have developed a skill that works only with a specific device it is important to mention it in the description. For instance let’s say there is a game skill which works only for Xbox One. If a customer has PS4, he would get confused to configure wrong device (in this case PS4) with this skill.

Similarly, description also must mention all functions a skill can perform specially in case of smart home skills for e.g. Turn On wifi, set thermostats to 180 degree, show camera, turn up the volume to 2 etc. Also it should explicitly convey that account linking is required.

Tip# 6 – Ensure Error free URLs and Appropriate Skill Icon

It is important that that you verify that all the links visible to the customer on the skill description page are free of errors and open properly. In case it is broken or has error, your skill will be rejected for this reason to avoid bad customer experience.

Also, please ensure that the skill icon is neither blank nor has a cropped image. In case your image is blurred or cropped, it may lead to skill rejection and you need to submit the skill again with an appropriate image.

If you don’t have a skill icon already, you could build one for your Alexa skill in minutes. Refer to the blog “Create Eye-Catching Icons for Your Alexa Skills in Minutes”

Tip# 7 Proofread to eliminate any grammatical or structural errors

You would agree having an incomplete sentence structure, grammatical errors and typos is a complete “no”. To avoid this situation always proofread the text a few times before you submit skill description ensuring all sentences are complete, meaningful and free of any grammatical errors or typos.

^{For example “This is a skill about ____________. You can contact us fg@_________.}  

Important to note that a text should not be literally translated from one language to another. We know sometimes automatic translation can be funny and embarrassing. To avoid such situations, please refrain any automatic translation tool or instead have a native speaker either write or proofread your content and sentence structure.   

Tip # 8: Review the entire Skill Description and Detail page with a quick checklist.

This may be painful at first, but when all is done, you’ll be glad to see that you took the time to properly convey your vision, leading to a quality skill description resulting in clearing certification with zero errors. The quick checklist is as below:

1.      Appropriate Skill Title

2.      Write description from customer perspective

3.      Skill description language must be same as Alexa account Language

4.      Correct Invocation Name and Wake Word for Example Phrases in Metadata

5.      Define compatible devices and all functions for Smart Home Skills

6.      Faultless URLs and appropriate skill icon

7.      Proofread to eliminate any grammatical or structured errors

8.      Review the entire “Skill Description and Detail Page” with a quick checklist.

Hope this blog post helps you in writing interesting and valuable metadata for better customer experience and better  searchability for skill on Alexa Skill Store. You can read more about it from the description checklist.

Happy skill building.