Skill design content guidelines

Follow these guidelines to make skill design easier for yourself and to ensure your users experience skills that are consistent and easy to use.

Skill name

The skill name, also known as skill title, must inform the user what is the intention of the skill. In other words, what using the skill does for the user.

Note: The format for a skill name is Verb + [indefinite article (when singular)] + (noun):
  • Send (verb) an (article) email (noun)
  • Find (verb) candidates (plural noun)

A well-named skill indicates the action and starts with a verb.
A skill flow focuses on the result: the goal of using the group of skills.

The skill name appears in multiple places:

  • Skill tiles in the skill catalog
  • Skill tiles on the homepage
  • Skill forms titles
  • Team skills page
  • Building and enhancing skills

There are 2 types of skill tiles where the skill name appears:

The skill tile in the skill catalog.
Figure 1. The skill tile in the skill catalog.

The skill tile in the skill set.
Figure 2. The skill tile in the skill set.

DOs and DON’Ts

Based on these best practices, the following are the "DOs" and "DON'Ts" for creating a skill name.

DOs

An example of a skill name that is written following the pattern "Verb + indefinite article + noun", is action based, and uses sentence-style capitalization.
Figure 3. An example of a skill name that is written following the pattern Verb + indefinite article + noun, is action based, and uses sentence-style capitalization.

  • Do make sure that skill names are written in Verb + indefinite article + noun.
  • Do make sure that skill names are action or intent based.
  • Do use of Sentence-style capitalization.
  • Do make skill names short but meaningful.

An example of a skill name that is short and meaningful.
Figure 4. An example of a skill name that is short and meaningful.

DON’Ts

  • Don't make skill names too long that it goes to the next line or is truncated.

An example of a skill name that becomes long because a preposition is used instead of an article, for example.
Figure 5. An example of a skill name that because a preposition is used instead of an article

  • Don't use periods, underscores, or dashes in place of spaces.

An example of a skill name that uses underscores and dashes in place of spaces.
Figure 6. An example of a skill name that uses underscores and dashes in place of spaces.

  • Don't use all caps.

An example of a skill name all written in all caps.
Figure 7. An example of a skill name all written in all caps.

  • Don't make skill names feature based.

An example of a skill name that is feature-based.
Figure 8. An example of a skill name that is feature-based.

Skill form title

For skill form title, use sentence case and capitalize the first letter only.

DOs and DON’Ts

Consider the following DOs and DON'Ts when creating a skill form title.

DOs

An example of a well-named skill form title that uses Sentence case.
Figure 9. An example of a well named form title that uses Sentence case.

Do use Sentence case, in which only the first letter of the first word is capitalized, for the input field title.

DON’Ts

  • Don’t use of all caps for the input field title.

An example of a skill form title that uses all caps.
Figure 10. An example of a skill form title that uses all caps.

  • Don’t use Latin terms like via, i.e., e.g., and etc.

  • Don’t use underscores in place of spaces.

An example of a skill form title that uses underscores in place of spaces.
Figure 11. An example of a skill form title that uses underscores in place of spaces.

Skill description

The line below the skill name is the "Description" in the .yaml or .json file, but it’s not really a description. This text is a continuation of the skill name to provide more information, in no more than 15 words (one sentence), about the skill, what it’s used for, or how that skill contributes to the overall goal.

If the text is too long (has “...”), the user must hover over it to show the tool tip box that shows the rest of the text. So, with a long text, the description is truncated after the first line, as you can see in the following example.

Example of skill description.
Figure 12. Example of skill description with long text.

The skill description appears in multiple places, such as the following examples. Consider the description’s location and available space when you write descriptions:

  • Skill tiles in the catalog
  • Skill forms titles
  • Skills page
  • Building and enhancing skills

DOs and DON’Ts

Consider the following DOs and DON'Ts when creating a skill description.

DOs

  • Do give users more information about what the skill does but leave the description blank if there's nothing more to add.
  • When there's nothing else to add, mention the app the skill is used in: "in Salesforce".

A good skill description should give users more information about what that skill does.
Figure 13. A good skill description says more about what that skill does. When there's nothing more to say, just mention the app the skill is from.

DON’Ts

  • Don't use the skill name as the description, meaning that if there's nothing more to say don't repeat the skill name, just indicate the app the skill is used in: "in Salesforce".

An example of a skill description that uses the skill name as the description.
Figure 14. An example of a skill description that uses the skill name as the description.

Skill icon

Each skill must have at least one icon. The icon represents the app or apps that are used to run the skill. If multiple apps are involved, multiple icons are attributed to the skill.

The skill icon appears in multiple places. Consider their placement when you determine the size of the icon to use:

  • Skill tiles in the skill catalog
  • Skill tiles on the homepage
  • Skill forms titles
  • Building and enhancing skills

There are two sizes of an icon:

Icon sizing 48 px x 48 px.
Figure 15. Icon sizing 48px x 48px.

Icon sizing 64 px x 64 px.
Figure 16. Icon sizing 64px x 64px.

DOs and DON’Ts

Consider the following DOs and DON'Ts when adding a skill icon.

DOs

  • Do use skill icons that are clearly visible.

An example of a skill icon that is clearly visible.
Figure 17. An example of a skill icon that is clearly visible.

  • Do use certified skill icons. Consult with Legal and Content before you use the icon.

An example of a skill icon that is certified.
Figure 18. An example of a skill icon that is certified.

  • Do use the updated and latest icons.

An example of a skill icon that is updated.
Figure 19. An example of a skill icon that is updated.

DON’Ts

  • Don't use skill icons that are difficult to read. The icon in this example includes extra text, which would be difficult to see.

Don't use skill icons that are difficult to read. The icon in this example includes extra text, which would be difficult to see.
Figure 20. Don't use skill icons that are difficult to read. The icon in this example includes extra text, which would be difficult to see.

  • Don't use any random icon to represent the skill, only icons of the apps used in that skill.

Don't use any random icon to represent the skill, only icons of the apps used in that skill.
Figure 21. Don't use any random icon to represent the skill, only icons of the apps used in that skill.

  • Don't use an old version of an icon.

Don't use an old version of an icon.
Figure 22. Don't use an old version of an icon.

Skill input

Field titles and helper text

Many skills require users to complete a form that consists of fields (also known as parameters, properties, or values).

To ensure consistency, follow these style guidelines in the .json and .yaml files for your skills.

Consider the following DOs for field titles.

DOs

Field titles

  • Do keep field titles short, ideally fewer than 4 words.

  • Do make sure that field titles make sense from a user perspective, not a technical perspective.

  • Do write field titles in Sentence-style capitalization, which means that only the first letter or the first word is capitalized. The exception is initialisms like URL. These words must be in all caps.

An example of good and bad field titles.
Figure 23. An example of good and bad field titles.

  • Do respect cultural differences by changing “First name” to “Given name” and “Last name” to “Surname” in the .json or .yaml file.

Given name and Surname in 'title'.
Figure 24. Given name and Surname in 'title'.

Field helper and placeholder text

Helper text provides additional aid or context to the user. Often used to explain the correct data format, placeholder text provides hints or examples of what to enter.

DOs and DON’Ts

Consider the following DOs and DON'Ts for helper and placeholder text.

DOs

  • Do keep helper text short. After the first sentence, the code will hide the rest of the text in a Show more link.

  • Do focus on what the property is, not what it does. Omit “Specifies” or “Indicates” before “whether”.

    title: Allow
    description: Whether...

  • Do omit "or not" with “whether” because the term "whether" means “whether or not”.

  • Do avoid slashes because they are ambiguous (they could mean “and” or “or):

    State/Province
    should be
    State or province

    HTTP/HTTPS endpoints
    should be
    HTTP or HTTPS endpoints

An example of a simple field title and none field description.
Figure 25. An example of a simple field title and none field description.

  • Do leave the description blank, instead of repeating the field title as the description, by putting in two double quotation marks in the .json or .yaml file: ""

Don't repeat the field title as the description.
Figure 26. Don't repeat the field title as the description.

DOs

  • Don’t include a description when the description repeats the field title but says nothing else. Instead, use two double quotation marks ("") in the .json or .yaml file.

Description that repeats the field title but says nothing else.
Figure 27. Description that repeats the field title but says nothing else.

Input field

Use single and multi-line text fields appropriately.

Do use single and multi-line text fields appropriately.
Figure 28. Do use single and multi-line text fields appropriately.

Don’t use Multi-line text when not needed.
Figure 29. Don’t use Multi-line text when not needed.

Required and optional fields

In the form design, the required fields are shown at the top and optional fields are in the Show more section. Organize your fields so the required fields are at the top and the optional fields are at the bottom, in the Show more section.

An example of an input form that shows the required fields at the top and optional fields in the Show more section.
Figure 30. An example of an input form that shows the required fields at the top and optional fields in the Show more section.

Field verification

Field verification must be done in situations, avoiding the user continuing the skill failing because an entry is invalid.

There are two types of field verification:

  • Error
  • Warning

An example of field verification for errors and warnings.
Figure 31. An example of field verification for errors and warnings.

Auto-complete suggestion

After a user selects a location, the other fields like Posting location and Job country are completed automatically.

An example of an auto-complete suggestion for a field that loads locations.
Figure 32. An example of auto-complete suggestion for a field that loads locations.

Table component - selectors

Use the appropriate selectors (table).

Consider the following DOs when adding selectors to a table.

DOs

  • Do use check boxes when you want user to select multiple items.

An example of a table that uses check boxes to enable users to select multiple items.
Figure 33. An example of a table that uses check boxes to enable users to select multiple items.

  • Do use of a radio button to allow the user to select one item.

An example of a table that use radio buttons to enable users to select one item.
Figure 34. An example of a table that use radio buttons to enable users to select one item.

Table component - header

Keep the table header concise, ideally no more than 6 words.

Consider the following DOs when adding a header to a table.

DOs

  • Do ensure data table titles use Sentence-style capitalization, in which only the first letter is capitalized.

An example of a table title that use Sentence-style capitalization.
Figure 35. An example of a table title that use Sentence-style capitalization.

  • Don’t allow the data table title to be longer than one line.

An example of a table that has a title longer than one line.
Figure 36. An example of a table that has a title longer than one line.

Table component - description

Include a description of the table but only when it adds more information.

DOs and DON’Ts

Consider the following DOs and DON'Ts when adding a header to a table.

DOs

  • Do make table description short.

An example of a table with short descriptions.
Figure 37. An example of a table with short descriptions.

DON'Ts

  • Don’t make table description more than one line.

An example of a table that has a description with more than one line.
Figure 38. An example of a table that has a description with more than one line.

  • Don’t include it if it repeats the table header.

Skill output

Skill output, sometimes called “responses”, is the information that is returned after users use a skill. This output corresponds to the input provided. It is presented to users in the conversation area above the chat bar. What the output is depends completely on what the skill is used for.

Output occurs at various points of the skill use and appears to our users as coming from the platform. Imagine there’s a conversation going on and write output responses that read as if there is a conversation going on with your user, but don’t use the first person (“I did x for you”).

When users choose a skill from the skill catalog and uses it (clicks Use), the output must confirm the skill choice and start communicating the process to completing the skill.

Note: When creating a skill flow to run multiple skills together, an output from a skill can be used as an input to another skill in the sequence or a next best skill.

Example

What is provided to the user when the skill is used

  • Textual feedback along with next best skill

An example of textual feedback that is provided to users when they use a skill.
Figure 39. An example of textual feedback provided to users when they use a skill.

  • Data table along with next best skill

An example of the next best skill to run after users use a skill.
Figure 40. An example of next best skill to run after users use a skill.

  • A toast notification about the skill’s completion

An example of toast notification about the skill’s completion.
Figure 41. An example of toast notification about the skill’s completion.

When a skill runs in the background

An example of inline text in the chat while a skill runs in the background.
Figure 42. An example of inline text in the chat while a skill runs in the background.

Example scenario

A user clicks the Send an email skill and clicks Use. By doing this, the user is requesting the platform to send an email. In the conversation area, it returns “Sure. You just need to complete this form first.” The same behavior would occur if the user typed “Send an email”, or another phrase that triggers this skill, in the chat bar.

After completing the task, the user receives the following output:

  • The email was sent to rebeccas@example.com successfully.
  • The email was sent to 3 candidates successfully.
Note: How "successfully" is at the end of the sentence. The placement of "successfully" at the end of the sentence is intentional because people scan sentences for status words, so having it at the end makes it more visible.

Example phrases

  • Ok. Here's a draft of what you can tell the candidate about the parental leave at GreyPine.

When asked to schedule interviews:

  • Interviews for 4 candidates were scheduled successfully.
  • Here are the details of the scheduled interviews.

When a skill is not in the skill set:

  • This skill isn't in the skill set. Consider the following suggestions:

Consider the following DOs and DON'Ts when writing output (responses).

DOs and DON’Ts

DOs

  • Do write in the active voice (subject + verb, in this case “You canceled”). Note the spelling of “canceled”. US English is one l.

An example of inline text in the chat when a skill fails.
Figure 43. An example of inline text in the chat when a skill fails.

An example of inline text in the chat when a skill fails.
Figure 44. An example of inline text in the chat when a skill fails.

Green check icon. Write responses that sound like you would say them to your manager when asked to complete a task.

  • Sure. You just need to complete this form first.
  • Sending the email...

Clients communicate with the watsonx platform but not a digital entity. We can’t use the personal pronoun “I” in responses or personify the responses in any way. The greeting says "Check out the skill catalog and let's get to work.” and the chat bar says “What do you want to do?”.

An example of the use of the digital labor.
Figure 45. An example of the use of the digital labor.

DON’Ts

Although we can’t personify the output (responses), we can be conversational. Think about how you would say it and then take yourself out of the response. For example, instead of writing “I sent the email.”, write “The email was sent.”

Note: We can't refer to Watson as the user's assistant, associate, worker, or anything similar in content that might be external.

An example of inline text in the chat when a skill fails.
Figure 46. An example of inline text in the chat when a skill fails.

Don’t write in the passive voice (verb by you, in this case “cancelled by you”).

An example of a response for when a skill is completed.
Figure 47. An example of response for when a skill is completed.

Red cross icon. Although we can’t personify the responses, we should avoid sounding like a robot. Don’t mention the skill that is used to complete a task:

  • “I’ll complete the Send an email skill.”
  • ”Sure. I’ll complete the {name of skill} skill for you.”

An example of a not recommended use of the digital labor.
Figure 48. An example of a not recommended use of the digital labor.

Phrases

Phrases are what the client types into the chat box to find and use a skill.

There are two key elements to a phrase: the verb and the noun.

The verb

Not everyone uses the same verb to describe the same action, so brainstorm the various ways that a person could refer to doing that action that is the skill. For example, for the Send an email skill, a user might type “Email...” or “Message...”, using the verb “email” or “message” rather than the verb “send” to trigger this skill. For another example, a user might type “Retrieve” when they want to get something, such as a list of candidates.

The more verbs that you use when you create phrases to trigger skills, the more likely that skill will be found.

The noun

A noun is a person, place, or thing, and not everyone refers to things the same way. For example, you might call something an “email”, but someone else might call it a “message” or a “note”.

The more synonyms (different nouns that means the same thing) you use when you create phrases to trigger skills, the more likely that skill will be found.

Include misspelled words

Don’t be afraid of misspelled words. We don’t want our users not to find the skill they need because they were typing too fast, weren’t paying attention to what they were writing, or didn’t know the correct spelling. Brainstorm all the possible textual errors and include them in your phrases.

DOs and DON'Ts

Based on these best practices, the following are the "DOs" and "DON'Ts" for generating phrases.

DOs

Green check icon. Include misspellings.

Green check icon. Include as many different verbs as you can think of.

Green check icon. Include as many different nouns as you can think of.

DON'Ts

Red cross icon. Have a short list of phrases. NLP generates phrases for you if you don't have at least 15-20 phrases.

Suggest next steps

Instead of leaving it up to your service user by having the platform ask “What do you want to do next?” with nothing but a blank chat field, suggest next steps by offering the next optional skills that your service user might need.

The following images are examples of how to suggest the next steps:

An example for suggesting two ways as next steps after you use a skill.
Figure 49. An example for suggesting two ways as next steps after you use a skill.

An example for suggesting one way as a next step after you use a skill.
Figure 50. An example for suggesting one way as a next step after you use a skill.

An example for suggesting next steps when a skill isn't added to the skill set.
Figure 51. An example for suggesting next steps when a skill isn't added to the skill set.

DOs and DON'Ts

Consider the following are the "DOs" and "DON'Ts" for suggesting next steps.

DOs

An example of what you can do when you suggest the next steps.
Figure 52. An example of what you can do when you suggest the next steps.

  • Do write optional skills to match the names of the skills clicking the options will invoke (verb + article + noun). This style is conversational.
  • Do suggest skills that you could imagine the user use after the previous skills if they did themselves what the platform just did for them.

DON'Ts

An example of what you can't do when you suggest the next steps.
Figure 53. An example of what you can't do when you suggest the next steps.

  • Don’t write optionally skills without articles because that makes them sound more technical and less conversational.
  • Don’t suggest skills that have nothing to do with the last skill that was used.

Notifications

Actionable notifications relate specifically to a task or skill that couldn't be complete because of an error or requires input from the user. See the following examples for how to write different types of notifications.

Examples

  • "Your input is needed to create the job description." instead of "The Create job description skill needs your input."
  • "The job description couldn't be created." Instead of The <name of skill> couldn't complete."

Be sure to tell users why the action of the skill couldn't be completed. Be transparent about the errors that might have occurred and, where possible, provide guidance to help users resolve those errors.

Informational notifications share an update and don't require action.

Examples

  • "A new user was added to your team."
  • "You now have access to..."

Empty state notifications appear when there is nothing to show. The title conveys what will be in the space after it is populated with data. The text below the title tells users what they can do to populate the space.

Example

Start by adding skills
Click Add skills to start accessing skills from various sources and enhancing them.

Note that the title doesn’t end in a period.

Style notes

When people text, they write numbers as numerals regardless of whether it's from 1-9 or greater than 10. So indicate numbers as numerals no matter the quantity.

If you can’t suggest skills as next steps, write "What do you want to do next?" instead of "What would you like to do next?" to match the watsonx Orchestrate style and be direct.