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
- Skill form title
- Skill description
- Skill icon
- Skill input
- Skill output
- Skill phrases
- Suggest next steps
- Notifications
- Style notes
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.
- 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:


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

- 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.

DON’Ts
- Don't make skill names too long that it goes to the next line or is truncated.

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

- Don't use all caps.

- Don't make skill names 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

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.

-
Don’t use Latin terms like via, i.e., e.g., and etc.
-
Don’t use 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.

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".

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".

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:


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.

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

- Do use the updated and latest icons.

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 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.

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.

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

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 provinceHTTP/HTTPS endpoints
should be
HTTP or HTTPS endpoints

- 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: ""

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.

Input field
Use single and multi-line text fields appropriately.


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.

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

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

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.

- Do use of a radio button to allow the user 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.

- Don’t allow the data table title to be 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.

DON'Ts
- Don’t make table description 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.
Example
What is provided to the user when the skill is used
- Textual feedback along with next best skill

- Data table along with next best skill

- A toast notification about the skill’s completion

When 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.
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.


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?”.

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.”

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

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.”

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
Include misspellings.
Include as many different verbs as you can think of.
Include as many different nouns as you can think of.
DON'Ts
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:



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

- 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

- 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.