Enhancing and publishing skills
After building your custom skills to Orchestrate, you can enhance it to optimize the experience of using it in Orchestrate to meet your team’s needs. When your skill is fully trained, you can publish it to the Orchestrate skill catalog so that your team can use it.
The following diagram illustrates the steps to enhance and publish your skills:
![Enhance skills](../images/enhance_and_publish.png)
To enhance and publish your skills, follow the steps:
- From the menu
, select Skill studio.
- All 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.
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](../images/nametab.png)
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 conversational 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.
![Add slot logic flow button](../images/add-slot-logic-flow.png)
After you click this button, two other buttons are enabled to edit or delete the logic flow.
![Add slot logic flow button](../images/edit-remove-slot-logic-flow.png)
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 conversational
By default, all skills and skill flows are enabled as conversational and eligible to be used on actions for AI assistants.
If you imported a skill, you can find this skill in the AI assistant builder after the admin connects to the required apps on the team skill sets related to the AI assistant's environments. For more information about assistants and actions from skills, see: Creating an action from skill.
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 tofalse
.
- By default all skills are conversational, unless the annotation
- 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 thex-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.
- Conversational
-
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 intead 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 a conversational skill.
Configuring the output of the skill
You can configure how to display the output of the tasks to the users. On Orchestrate, the outputs can be displayed in two formats: output fields or consistent text.
The output fields format is the default output format. It creates output fields 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](../images/enhance_skill-table.png)
Follow the following procedure to enhance an output field:
- 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](../images/enhance_skill-tableArray.png)
The consistent text format returns to the user a default text message after the skill is used. You can also configure this feature by using the x-ibm-nl-output-template
property. For more information about the x-ibm-nl-output-template
property, see Configuring output messages.
![Default text example](../images/enhance_skill-defaultValueExample.png)
Follow the following procedure to enhance a consistent text output:
- Click the Edit response.
- In the Enhance this skill page, select the Output tab.
- Select Text.
- In Results set the default text.
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.
![Security tab](../images/securitytab.png)
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 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.
The following GIF illustrates how to add phrases to run the skill in Orchestrate.
![GIF to show how phrases tab works](../images/phrases.gif)
Removing a phrase
To remove a phrase, click the delete icon .
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.
![Next best skills](../images/nbatab.png)
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.
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](../images/nbamapping.png)
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](../images/nbachat.png)
Removing a next best skill
To remove any of the next best skills, select the skill and then click the delete icon .
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.