Chat is a powerful feature that can assist you with data analysis and reporting in Displayr. You may want to repeat certain workflows you've used Chat to do - here is where Skills come in. Skills allow you to create prescribed workflows for Chat to follow, and be able to share those workflows across documents. Think of this as writing a QScript without having to know anything about JavaScript. Skills are a series of instructions, in plain English, that Chat can follow to perform standardized workflows. This article covers:

• When to consider making a skill
• The Skills menu
• Run a skill
• Create a new skill with a worked example
• Skill accessibility and different versions
• Edit and delete a skill
• Tips

When to consider making a skill

The following are examples of use cases for making skills. They are by no means exhaustive; the lowest bar for when to make a skill is when you'd like the Chat to follow the same set of instructions more than once. 

• Data processing and cleaning - i.e. First, look for variable sets on a scale and create top 2 boxes on those variable sets. Then, create a copy of those variable sets and change the Structure to Binary-Multi, counting the top 2 ratings.
• Creating a standard report - i.e. First, create a folder for "Demographics". Then, create pages within that folder with summary tables of the demographic variables, i.e. Age, State, Income, etc.
• Styling - i.e. For each pie chart in the Report with a scaled variable, apply the Pie_Chart_Scale.QTemplate. Then, add a text box to the page with the biggest category shown in the pie chart.
• Checking - i.e. Ensure that the Title of each page corresponds to the content shown on the page. Check that all mentions of X Brand Inc has the Inc at the end.

The Skills menu

The Skills menu is located in Chat, immediately below where it says Ask anything. 

Click on Skills to open the menu where you can create a New skill and search, run, edit, or delete any other skills that your document has access to. Note that there are additional skills built into Displayr that Chat may run in the background; you can't edit or view these. You can hover over a skill to see the Description. 

Chat has access to all skills that are saved on the Displayr Cloud Drive in the same folder as your current document, plus any that are saved in the parent folders above the document but not sub-folders below. This goes all the way up to the Home directory of the Displayr Cloud Drive. All skills saved in your Home directory will be accessible to all documents. More guidance on where to save skills is in the Skill accessibility and different versions section below.

Run a skill

There are different ways to run a skill, either explicitly or implicitly.

• Select it from the Skills menu. This causes a prompt to be added to Chat like "Use the market-share skill", and you run it by sending that message to Chat by clicking the arrow on the right.
• Type a reference to a skill in the Chat prompt box and run it, i.e. /market-share.
• Ask the AI to do something. The AI reads through the descriptions of the various skills, works out if the skill is relevant, and runs it itself.

Create a new skill

It's important to remember that when you give Chat skills, you're giving it instructions about what to do when and why. If these instructions are contradictory, Chat will - just like a person - behave erratically. Therefore, each skill needs to be as specific as possible in all details. 

With this in mind, to create a new skill, click on Skills > New to open the editor. You'll be presented with 4 fields:

1. Name: this is the name listed in the menu.
   • Make it predictable and callable.
   • Use lowercase + hyphens (e.g. shapley-driver-analysis) to make it readable and easy to remember
   • Make it specific enough that someone can guess what it does from the name alone (avoid overly generic names like analysis).
2. Description: define what the skill does in 1 sentence. This is used by the agent to decide whether to run the skill, so it should be:
   • Outcome-focused (what changes / what the user gets).
   • Concrete (name the analysis/output it produces).
   • Short (one clear sentence is ideal)⁠.
   • Good pattern:
     “Run a driver analysis and summarize the key drivers.”
     Less good:
     “Helps with analysis.” (too vague)
3. When to use: add “trigger conditions” and boundaries for when the skill should be used. This is optional, but it’s one of the biggest levers for making skills run at the right time.⁠ Include:
   • Specific user phrases that should trigger it.
   • Unambiguous rules (when not to use it, or what to do instead).
   • Any prerequisites (e.g., “only after data is loaded / weights set / pages exist”).
   • The placeholder example is basically the right idea: key terms + “if they say X, do Y instead”.⁠
4. Instructions: list what Chat should do as a list “Step 1 / Step 2 …”. This is the most reliable format.⁠ Good instructions:
   • Start with prerequisite checks (what must be true before proceeding)
   • Use numbered steps with one action per step
   • Specify inputs/parameters the skill needs (and defaults if the user didn’t give them)
   • Add branching only when necessary (e.g., “If the user asked for X, do X; otherwise do Y”)
   • Add a finish condition (what “done” looks like)⁠

A worked example

This example creates a new skill called "market-share" for brands from survey data.

1. Import your survey data. To use the provided example data, from the Data Sources tree, click + >  Cloud sources > URL and paste in the following:
   https://app.displayr.com/DataMart/File/9aacd542-792c-57c7-bfff-ba723aa0b315?file=Cell%20Phones%20-%202%20weeks.sav&company_id=751221
2. From Chat, go to Skills > New.
3. Set the Name to "market-share."
4. Set the Description to: 
   "Calculates market share for brands or companies from survey data, using the best available behavioral proxy (brand bought/used most often, last brand bought, or favorite brand)."
5. Set When to use to:
   "Use whenever the user asks for market share, brand share, share of market, or share by brand or company — including when they describe that goal without using the word 'share'."

6. Paste the following into the Instructions field:

   # Find a market share proxy
   If the user has mentioned a specific variable or variable set, use it. Otherwise, identify the variable set in the study that is the best proxy for market share. Common variables (best is highest in the list) are:
   - Last brand purchased or consumed
   - Most common or main brand purchased or consumed
   - Favorite brand
   We refer to this as "Market Share Proxy"
   
   If no proxy exists, tell the user you couldn't find one, and ask them to suggest one.
   
   # Duplicate the variable set
   Duplicate the Market Share Proxy
   
   # Set the name for the new variable set
   1. Set the base name of the newly created variable set to "Market Share".
   2. If the user has given a rationale, append a short relevant qualifier to the base name.
   3. If a variable set with that name already exists, make it unique by appending a space and the lowest integer that produces an unused name (e.g. "Market Share 1", then "Market Share 2", and so on).
   4. Set the Label property of the newly created variable set to this final name.
   
   # Create a table, rebase, and sort
   1. Create a table of Market Share as a single output
   2. If Market Share has an Other option, and it has a messy label (e.g., "other (specify)"), rename it as Other
   3. Set any options — excluding NET, brands, and Other — to missing values (e.g., don't know, none of these)
   4. Sort the categories (using the Data Reduction; do not use a Rule), from highest to lowest, leaving NET and Other at the bottom.
   

7. Click Save and choose what folder to save the corresponding .QSkill file in. By default, Displayr saves the skill to the current folder of your document and it is then only available there. To make it available to everyone in your organization, save it to the Home folder instead. See Skill accessibility and different versions for more detail.
8. Now your skill is accessible via the Skills menu.

Skill accessibility and different versions

When you save a skill, it's saved as a .QSkill file in a folder in the Displayr Cloud Drive. Documents have access to all skills in the same folder and any folders above in the directory, but not folders below the document's current folder. If you want to make a skill generally available, save it in the Home folder. Given .QSkill files are written in markup language, you can even create them outside Displayr and upload them to the Displayr Cloud Drive. You can also download or move .QSkill files within the Displayr Cloud Drive.

When saving a skill, Displayr will warn you if you save it somewhere the current document can’t access:

Saving to [Folder Location] means this skill won’t be available to your current document. To use it here, save it to your home folder, to a folder that contains this document, or to a folder in which the current folder is within.⁠⁠

Different versions of a skill

When you hover over a skill in the Skills menu, icons will appear to Edit (pencil) or Delete (trash) the skill.

Clicking Edit will open the editor where you can review the current skill and make any necessary edits. Note that you cannot save the edited version in a new place; you will need to either copy all the information into a new skill or move the .QSkill file (or a copy) to the desired folder on your Displayr Cloud Drive. 

If you click Delete, you will be prompted to confirm deletion before the skill actually gets deleted. Please note that the Displayr Cloud Drive does not have a Recently Deleted menu, so deleting a skill is permanent and cannot be recovered. 

Consider the following skill, which at first glance seems straightforward.