Building Skill IDs

The skill_id uniquely identifies a skill on IBM watsonx Orchestrate. This identifier is created based on the title, version, and operationId objects of the skill's OpenAPI file. You can use it when you create skill flows, sequence skills, or create inputs with lists of dynamic values through OpenAPI files.

Tip:For prebuilt skills, you get this identifier in Skill IDs for prebuilt apps.

The IDs are constructed in the following format:

<info.title>__<info.version>__<paths[].path.operation.operationId>

The format represents the path to the objects that you need to use to create the ID. Notice that the dot (.) denotes a child object of a previous object and aim to guide you on finding these objects within the sections of an OpenAPI file.

The <info.title> part is the title of your API that you can find in the info section of the OpenAPI file, for example:

"info": {
  "title": "Sample API"
}

The <info.version> part is the version of your API that you can find in the info section of the OpenAPI file, for example:

"info": {
  "title": "Sample API",
  "version": "1.0"
}

The <paths[].path.operation.operationId> part is the operationId that identifies the operation to call from your API. In more details, inside the paths section, look for the endpoint (path) and its operation (HTTP Method) to call. Each operation can have an operationId that identify it. For example, for GET /user you can have the following structure:

"paths": {
  "/user": {
      "get": {
      "summary": "Get user",
      "operationId": "getUser"
    }
  }
}

Note:Any spaces in the values are replaced with hyphens, and the objects are separated by two underscores.

For the previous examples, you have the following structure for the skill ID:

Sample-API__1.0__getUser

Using Skill IDs

You use Skill IDs in different use cases. The following are some use cases:

Creating a skill flow

You can use the skill_id property to create a skill flow, and then you can import that file as a new skill or skill flow into watsonx Orchestrate. For example, the following JSON OpenAPI specification creates an issue on Jira and sends a slack message to notify the team about the new issue.

"components": [
  {
      "name": "Create a Jira issue",
      "id": "Jira-Issue__2.0.0__create_Issue",
      "type": "primitive",
      "description": "Create operation for Jira Issue"
  },
  {
      "name": "Send a message",
      "id": "Slack-message__3.0.0__create_message",
      "type": "primitive",
      "description": "A new message is posted in Slack"
  }
]

Sequencing skills

After you received the response from a skill that you ran, a suggestion might appear on the watsonx Orchestrate chat with the next best skill that you might run. For example, after a text is created with generative AI, the suggestion might be sending this text through email. See Sequencing skills with x-ibm properties to know more.

The following JSON snippet shows the x-ibm-next-actions property set with a reference to a prebuilt skill:

"x-ibm-next-actions": [
  {
    "skill_id": "Microsoft-Exchange-Messages__2.0.0__SENDOUTLOOK_Messages",
    "utterance": "Send an email by using Outlook"
  }
]

Dynamic values for list of options

You can use the skill_id property to set an input as a list of options in a skill based on the response of another skill. See Configuring dynamic values for list of options.