Enhancing and publishing skills

After building your custom skills to watsonx Orchestrate, you can enhance it to optimize the experience of using it in watsonx Orchestrate to meet your team’s needs. When your skill is fully trained, you can publish it to the watsonx Orchestrate skill catalog so that your team can use it.

The following diagram illustrates the steps to enhance and publish your skills:

Enhance skills — Figure 1. The three steps to enhance and publish skills.

Note: You can only enhance custom skills that are built from OpenAPI files and skills built from in-product apps. However, the prebuilt skills cannot be enhanced.

To enhance and publish your skills, follow the steps:

From the menu , select Skill studio.
- The imported skills are listed on Skills and apps page along with their status, which is either Ready to publish or Published. You can search and select the skill that you want to enhance.
From the menu next to your skill, select Enhance this skill. You see a page with multiple tabs that are designed to enhance your skills.
Enter the following information under the respective tabs:
Choose one of the following options:
- Click Save as draft to save the skill for further enhancement.
- Click Publish to publish your skill to the skill catalog.

Note: You can also delete and export your skills.

Configuring the name and description of the skill

You can name and describe the skill to convey how the skill is used and why the user would want to use it.

To configure the name and description of the skill:

In the Enhance this skill page, select the Name tab.
Specify the name and description for the skill in the respective fields. The default values are inherited from the title and description of the operation in your OpenAPI. For more information on how to configure your app name in OpenAPI specification, see Configuring the app name.
Categorize your skills by adding any number of category keywords. Type a category and click Enter.

Name tab in the Enhance skill page — Figure 2. The 'Name' tab on the 'Enhance skill' page.

The name tab also displays the preview of the skill tiles as they appear on the skill catalog and skill set.

You can customize the skill by defining your own icon in the OpenAPI specification. For more information, see Adding an icon to the app.

Configuring the input of a skill

You can enhance the skill input experience for your users. To enhance the input fields, in the Enhance this skill page, select the Input tab. In the input tab you can:

Edit the field name of the parameter in the Provide the Label for input parameter field.

Figure 3. Example of input name enhancement.
Turn a parameter as required in the input form by selecting the Required checkbox.

Figure 4. Example of input required enhancement.
Drag the parameters to arrange them in the form that is presented to users.

Figure 5. Example of input order enhancement.
Edit the input field format, whose available formats are Options, Single-line text, and Multi-line text.

Figure 6. Example of input field format enhancement.

Note: For Single-line text and Multi-line text formats, you can use the text field to provide examples of possible input values to your users.

Gathering information from users with slot logic flows

You can collect information from user inputs to better guide the responses of your AI assistant with slot log flow. In the Input tab, you add an slot logic flow for skills that you can use in AI assistants.

With logic flows, builders can add input validation to skills, thus turning their input requests into a fluid conversation, whatever is the logic that the builder created. Without slot logic flows, skills accept any input, usually failing at run time if the input is invalid, without any conversation to try to handle the error when the skill runs.

To add the slot logic flow, you must click the Add slot logic flow button.

After you click this button, two other buttons are enabled to edit or delete the logic flow.

The logic flow for the slot is built as an automation, so when you click the Edit slot logic flow button, you are redirected to a workflow in the automation builder. Learn how to create your flow to validate the inputs of your users in Adding slot logic flow.

If you delete the slot logic flow, the way that the AI assistant validates the user inputs in the web chat can be impacted.

Skills enabled as skill-based actions

By default, all skills and skill flows are eligible to be used as skill-based actions for AI assistants.

If you imported a skill, you can find it in the AI assistant builder after the admin connects to the required apps on the skill set related to the AI assistant's environments. For more information about assistants and actions from skills, see: Creating an action from skill.

Note: You cannot delete skills that are used by assistants.

Automatic fallback to forms over multi-turn conversations

AI assistants fallback to forms to get input from users for actions from skills when any of the following criteria apply:

Skill is a skill flow

Skill flows display their inputs and outputs in a form. You can use skill flows as conversational skills if all their component skills are:
- Conversational
  - By default all skills are conversational, unless the annotation x-ibm-conversational-skill is set to false.
- Connected
  - All the component skills must be connected to the skillset.
  - wo-identity based Automation builder skill is considered to be connected by default.
- Published
  - All the component skills should be published in the skill set.
- Visible
  - By default, all skill flows created are allowed to use only visible skills.
Important:Skill flows don't have the x-ibm-conversational-skill property to set them as conversational. Make sure that the component skills follow the previous criteria to turn skill flows eligible to create actions.
Skill input or output has annotations

If any of the following properties are present in the Request or Response body of the OpenAPI specification that defines the skill, then AI assistants use forms instead of multi-turn conversations:
- x-ibm-ui-extension
- x-ibm-operators
- x-ibm-filter-format
- x-ibm-pagination
Input or output fields use complex objects

If any of the following complex objects are present in the Request or Response body of the OpenAPI specification that defines the skill, then AI assistants use forms instead of multi-turn conversations:
- table
- file
- password
- boolean
Number of inputs fields exceeds the configured value

If the number of input fields of the skill exceeds the maximum number of fields to consider a skill to be conversational, then the AI assistants use forms instead of multi-turn conversations. For more information on setting the default number for skills to be conversational, see Configuring the number of input fields for multi-turn conversations.

Configuring the output of the skill

You can configure how to display the output of the tasks to the users. On watsonx Orchestrate, the outputs can be displayed in two formats: output fields or literal text.

Configuring the output as a field

The output fields are formatted based on the skill output schema that is configured in the OpenAPI file. For more information about the skill output schema, see Configuring skills.

Output fields example — Figure 9. The image exemplify the output fields.

Follow the procedure to enhance an output as a field format:

In the Enhance this skill page, select the Output tab.
Click the Edit response.
Select Table.
For each Add header field, set the label for the output field.
In the drop-down field, configure the order that the fields are displayed on the output form.

Array schemas display a table as output on the form. In that case, you can add a header and a description to that table by configuring the Header and Description options.

Output fields in array example — Figure 10. The image exemplify the output fields for array schemas.

Configuring the output as a literal text

The format of a literal text returns to the user a default text message after the skill is used. You can also configure a literal text by using the x-ibm-nl-output-template property. For more information about the x-ibm-nl-output-template property, see Configuring output messages.

Follow the procedure to enhance an output as a literal text format:

In the Enhance this skill page, select the Output tab.
Click the Edit response.
Select Text.
In Results set the default text.

Default text example — Figure 11. The image exemplify the consistent text output.

Concatenating output values in literal text

You can concatenate the values that are returned in the skill output with the literal text. To do it, in the text tab, use the syntax "{skillOutputReference}" along with the literal text, where the skillOutputReference is the skill output reference.

You can find out the skill output reference through the Table menu in the table headers.

Default text example with skill output — Figure 13. The image exemplify the consistent text with a skill output .

Configuring the security schemas

On the Security tab, you can review the authentication type and the server, which are inherited from the OpenAPI. For more information, see Configuring the API security scheme.

You can test the authentication in the Security tab as shown in the following image.

You can see how the user input is requested on the right side of the screen. It’s best not to change this information. If you do, ensure that you have the correct server and authentication method before making changes.

Adding phrases

Phrases are the texts you can use to find and use a skill in the chat bar. To add phrases, go to the Enhance this skill page, select the Phrases tab, and use any of the following methods:

Type the phrase in the Enter new train phrase field. Press Enter to add more phrases.
Generate phrases based on IBM Granite Models. For that, click Auto-generate phrases (Experimental).

Important:The auto-generate phrases is a feature available for instances of IBM watsonx Orchestrate running on SaaS deployments only.
Generate phrase on watsonx Orchestrate based on the information in the OpenAPI. For more information, see Training skills with phrases.
Add phrases by using an IBM natural language extension in the OpenAPI.

Note: A good description of the skill helps to generate better recommendations. It takes a few seconds to generate phrases and not all is perfect. However, you can choose to delete any phrase you don’t like by using the delete icon. Using phrases, trains the natural language understanding (NLU) model, which means you don’t need to guess every iteration of what someone says. The NLU can understand related intents, and the users are asked for clarification. In this way, users receive choices if they are not sure about which skill to run when they type something.

The following GIF illustrates how to add phrases to run the skill in watsonx Orchestrate.

GIF to show how phrases tab works — Figure 15. The 'Phrases' tab on the 'Enhance skill' page.

Removing a phrase

To remove a phrase, click the delete icon Remove phrase .

Configuring the next best skills

The next best skills feature helps you find skills to complete tasks that naturally follow the work currently being done.

To add the next best skills:

In the Enhance this skill page, click Next best skills tab.
Click the Add a skill icon.
Select the app to add the skill.
Click Add skill+ in the skill tile to add the skill as the next best skill.

Note: You can use the Add a skill icon to add up to ten skills.

Data mapping for next best skills

When you enhance a skill, you can map data from the skill or skill flow into the next best skills added.

Next best skills - mapping — Figure 17. Mapping fields in the 'Next best skills' tab.

Following are the steps to map data to the next best skills:

Select the skill to map the input values.
Click the Input tab.
Map values to the required input parameters by using any of the following methods:
Click Save as draft to save the changes to the skill.
Click Publish to publish the skill to the skill catalog.

The following image shows how the mapping in the Next best skills tab gets reflected when you use the skill. The output value user email of the User Info (demo) skill is mapped to the Text field of the Slack skill. Therefore, when you use the User Info (demo) skill in the chat, the user email value is automatically inserted in the Text field of the Slack skill.

Next best skills - chat — Figure 18. The 'Next best skills' working in the chat.

Removing a next best skill

To remove any of the next best skills, select the skill and then click the delete icon Delete .

Tip: When a skill that was part of the next best skills is removed from the skill catalog, you get a notification. You can remove this skill from the Next best skills tab and add new skills.

What to do next

After a skill is enhanced and published, it is available for you to add to your skill set from the skill catalog. For instructions, see Adding a skill from skill catalog.

Tip: Members with the admin role can add the skill to a team skill set.