Skill Tutorial

Follow these instructions to build a skill from scratch in Skill Studio, add nodes (such as dataset queries, charts, and visualizations), wire in parameters for dynamic behavior, and configure the chat response using a prompt composer.

---

1. Getting Started in Skill Studio

• Select Your Assistant:

  • Open Skill Studio.
  • Choose the assistant you want to work on.
  • If the chosen assistant doesn’t have any skills yet, click Add Skill.

• Starting a New Skill:

  • You can either use an existing managed skill or start from scratch.
  • If the assistant already has a skill, navigate to the skill view (in the middle of the screen) and click to add a new skill if needed.

---

2. Understanding the Basic Nodes

• Skill Initialization vs. Skill Response:
  • When you create a new blank skill, you will see two nodes (displayed as tabs on the left):
    • Skill Initialization: Acts to get everything running, kicks off the rest of the skill.
    • Skill Response: Delivers the output to the end user.
  • Initially, you may notice that Skill Response is not connected to Skill Initialization.

---

3. Adding a Dataset Query Node

3.1 Add a New Node

• Click the plus button to add a node.
• In the node list, you will see groups like Code, Visual, Prompt, and End Node for Skill Response.

3.2 Select the Code Node

• Choose the dataset_query node.
• This node allows you to run a SQL statement against the skill’s configured dataset and returns a table.
• Once added, the dataset_query node automatically connects to the Skill Response node.

3.3 Exploring Inputs and Outputs

• Open the Inputs and Outputs panel for the datasetquery node.
  • Execution Table: Shows the order of node execution.
  • Input Table: Displays all inputs (current values, names, and types).
  • Output Table: Shows what the node will output (with sample values).

3.4 Configuring the Query

• In the metrics area:
  • Click the dropdown and select a metric (e.g., total sales).
• In the dimensions area:
  • Choose a dimension (e.g., brand).
• Configure filters, limit, and sorting as needed.

3.5 Testing the dataset_query

• In the node list, select Run Node on the dataset_query node.
• Verify that the statuses change to green check marks, indicating a successful run.
• Note: Running a node from the list only executes nodes up until that point (so Skill Response may be skipped).
• Switch to the Preview tab to see the output (a data frame).

---

4. Adding Parameters to Your Query

4.1 Adding a Metric Parameter

• Create the Metric Variable:
  • Click the Variables button.
  • Click Add Variable and name it metric.
  • Toggle Include Chat Parameter so that the parameter is populated at runtime from the user's question.
  • Limit Acceptable Values: Restrict to metric-type columns if needed.
  • Variable Type: Change to list if you want to allow multiple metrics (default string allows only one).
• Wire the Variable:
  • In the datasetquery node, open Inputs and Outputs.
  • Remove any hardcoded metric values.
  • Click the metrics input field and select the metric variable.

4.2 Adding a Dimension Parameter

• Create a Dimension Variable:
  • Click Add Variable and name it (e.g., dimension).
  • Toggle Include Chat Parameter.
• Wire the Variable:
  • Remove any hardcoded dimension values in the datasetquery node.
  • In the dimensions input field, select your new dimension variable.
  • (If the parameter does not appear immediately, try refreshing the view.)

4.3 Adding a Filter Parameter

• Create the Filter Variable:
  • Click Add Variable and name it filter.
  • Toggle Include Chat Parameter.
  • Limit acceptable values as required.
• Wire the Filter:
  • In the datasetquery node’s Inputs and Outputs, add the filter variable to the filter input area.
• Test the Filter:
  • Open the testing chat (e.g., Max Chat).
  • Ask a question like:
    Show me brands that have the best selling fruit
  • Verify that the filter is applied and formatted correctly using predicate logic (e.g., "equal to", "not equal to").

---

5. Visualizing Your Data with a Chart

5.1 Adding a Chart Node

• Insert a Chart Node:
  • Click between the datasetquery and Skill Response nodes.
  • Select the Chart node.
• Configure the Chart:
  • In the Chart node’s Inputs and Outputs, select the output data frame from the datasetquery node.
  • (For now, you can set the tab title and index later.)
• Test the Chart Node:
  • Use the play button at the bottom or ask a question (e.g., Show me fruit brand sales) to run the skill.
  • Verify that a bar chart appears displaying the queried data.
  • Blue dots on the datasetquery node indicate that its output is being used as input in the Chart node.

5.2 Adding a Visualization Layout Node

• Insert a Visualization Layout Node:
  • Add a new node between the Chart node and the Skill Response node.
  • Select the Visualization Layout node.
• Configure the Visualization Layout:
  • In the Chart node, set:
    • Tab Title: For example, chart (this name appears on the artifact view).
    • Index: Set to 0 to make it the first tab.
• Wire the Chart into the Layout:
  • In the Visualization Layout node, add the chart output as a content block.
• Hook Up to Skill Response:
  • In the Skill Response node’s Inputs and Outputs, select the Visualization Layout node as a content block.
• Final Test:
  • Run the entire skill (using the overall play button or by asking a question such as Show me fruit brands sales) to verify that both the chat and visual outputs work as expected.

---

6. Troubleshooting & Adjusting Parameters

• Testing with Alternative Questions:
  • Try asking:
    Which brands sold oranges?
  • If you see an error (e.g., “no viable chart types found” because of multiple dimensions), adjust the dimension variable.
• Adjusting the Dimension Parameter:
  • Change the dimension variable’s type from list to string so that only one dimension is parsed from the user’s query.
  • Ask a rephrased question to force a new interpretation using the updated parameter.

📘

Learn More about Parameters Here

• Re-Testing:
  • Use the chat (Max Chat) to force a fresh interpretation rather than relying solely on the play button.

---

7. Enhancing the Chat Response with a Prompt Composer

7.1 Identifying the Issue

• When asking a question like:
  Which brand sells the least fruit?
• You might notice that although the datasetquery and visualization nodes return data correctly, the chat response lacks descriptive output.

7.2 Adding a Prompt Composer Node

• Insert the Prompt Composer Node:
  • Click between the datasetquery and Chart nodes.
  • Select the Prompt Composer node.
• Configure the Prompt Composer:
  • In Inputs and Outputs, note the available inputs:
    • Template Context: (Add the datasetquery’s data frame here.)
    • Prompt from Library: (Select a pre-built prompt.)
    • Match Value for Examples: (Optional for future use.)
  • Add the datasetquery’s output to the Template Context.
• Using the Prompt Library:
  • Navigate to the Prompt Library in the left navigation.
  • Select an existing prompt (e.g., Basic Chat Response for My Max).
  • Edit the prompt to include instructions like:
    Use the data below to respond.
  • Save your changes.
• Wire the Prompt Composer to Skill Response:
  • In the Prompt Composer node, select the updated prompt from the library.
  • In the Skill Response node’s Inputs and Outputs, add the output of the Prompt Composer to the chat response input.
• Test the Enhanced Chat Response:
  • Ask the question again (e.g., Which brand sells the least fruit?).
  • Verify that the skill now returns a complete chat response (e.g., “The brand that sells the least fruit is Quality Foods” along with the corresponding value).
  • Optionally, check diagnostics to review the composed prompt and ensure it includes your datasetquery data.

---

8. Configuring Skill Properties for Prime Time

• Open Skill Properties:
  • Click the settings cog (usually in the skill row) to open the Skill Properties panel.
• Customize the Skill:
  • Enable/Disable for Chat: Toggle the skill for chat usage.
  • Rename the Skill: Use only letters, numbers, dashes, and underscores (no spaces).
  • Add a Description: Provide a brief description for end users.
  • Define Capabilities:
    • For example: “Produces bar charts” and “Answers questions about a context data table.”
  • List Limitations:
    • For example: “Only makes simple charts.”
  • Provide Example Questions:
    • Which brand sells the least fruit?
    • Which brand sells the most vegetables?
    • Show me sales by brand.
  • Select a Dataset: Optionally, set a specific dataset for the skill.
• Final Testing:
  • Run the skill and ask an example question that aligns with your Skill Properties to ensure everything functions as expected.

---

9. Conclusion

You have now built a fully functional skill in Skill Studio by:

• Adding and configuring nodes: (datasetquery, chart, visualization layout, prompt composer).
• Creating and wiring parameters: (metric, dimension, filter) that update dynamically from chat input.
• Enhancing the chat response: Using a prompt from the Prompt Library.
• Customizing overall skill properties: To provide clear capabilities, limitations, and example questions.

For more advanced configurations (such as using match values for examples or additional rendering techniques), refer to the ReadMe documentation on Prompt Composer, Prompt Renderer, and Template Renderer.

---

Happy building!