# Skills and business goals

> Define the skills your practice builds, tag criteria with them, follow each skill's score over time, and keep each business goal's evidence by level.

- Plans: All plans
- Canonical: https://docs.devlin.ai/results-and-analytics/skills-and-goals

Skills and goals connect practice to the numbers your organization cares about. A **skill** is something learners practice across many simulations and evaluators, such as "Uses the customer's name" or "Handles objections". You tag evaluation criteria with skills, and devlin.ai adds up every tagged criterion into one score per skill over time. A **goal** is one business number, such as an escalation rate, with the evidence for it gathered level by level underneath. Both live in Brain and are available on every plan. Neither is required to build, publish or evaluate anything.

## Before you start
- Skills and goals belong to the active workspace. Another workspace cannot see or use them.
- Everyone in the workspace can create and change skills and goals: owners, admins and members.
- Skill scores come from evaluated attempts. A simulation or evaluator adds to a skill only when evaluation is on and at least one of its criteria is tagged with that skill. See [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring).

## Steps
1. Open **Brain → Skills**. Select **New skill**, or **Import** to bring in a competency model you already have.
2. Open a simulation's evaluation settings, or an evaluator's rubric, and tag each criterion with the skills it measures in its **Skills** field.
3. Open **Brain → Goals**, select **New goal**, name the business number under **Results**, and add the skills that move it.
4. When a goal's review comes due, open the goal, select **Record measurement** to record the latest numbers, then select **Mark reviewed**.

## Result
- **Brain → Skills** lists each skill with its score and how many results it rests on. Selecting a skill shows its score over time and the simulations and evaluators the results came from.
- **Brain → Goals** shows each goal with its latest Results, Behavior, Learning and Reaction numbers. Opening a goal shows each level with its baseline, its target and every number recorded. A baseline and target show as soon as you set them, before any number is recorded.
- On **Results → Learners**, a learner with tagged results gets a **Skills** section with their own score on each skill.

## Skills and sub-skills
A skill can sit under another skill. A skill placed under another is called a sub-skill. Use this to group narrow, observable skills under a broad one, for example "Uses the customer's name" under "Builds rapport". There is only one level: a sub-skill cannot have sub-skills of its own.

Name a skill after something a reviewer could see or hear. The form says so just above the **Name** box, with "Uses the customer's name" as the example. Broad skills such as "Empathetic communication" are allowed too.

To create a skill:

1. Select **New skill** at the top of the Skills tab.
2. Type a **Name** and, optionally, a **Description** of what the skill looks like when done well. The description shows when you select the skill, not in the list.
3. Leave **Sits under** on "Nothing, it's a top-level skill", or pick the skill it belongs under.
4. Select **Create skill**.

Each skill has a menu with the same items: **Edit**, **Add a skill under this**, **Move under another skill**, **Combine with another skill** and **Archive**. On a sub-skill, **Make it a top-level skill** takes the place of **Add a skill under this**. **Add a skill under this** opens the same form with **Sits under** already filled in.

Rules for names and places:

- Two active skills under the same parent cannot share a name, ignoring letter case. The form says "There is already a skill named" (or "There is already a sub-skill named" under a parent) followed by the name, and asks you to pick a different name. The same name can be used under two different parents.
- A sub-skill cannot have sub-skills of its own. Trying to add one shows "A sub-skill can't have sub-skills of its own. Make it a top-level skill first."
- A skill that has sub-skills cannot move under another skill. The form names the skill and says "has sub-skills, so it can't sit under another skill. Move its sub-skills out first, or combine it with another skill instead."
- Archived sub-skills count too. When every sub-skill left under a skill is archived, the form says "has archived sub-skills, so it can't sit under another skill. Restore and move them out first, or combine it with another skill instead." Check **Show archived** to see them.
- Sub-skills that were combined into another skill don't count. A skill whose only sub-skills left are combined ones can move under another skill.
- Moving a skill never changes which criteria are tagged. A parent's score always follows where its sub-skills sit now.

Use **Search skills** to narrow the list by name or description, and **Show archived** to list archived skills too. An archived skill is marked "Archived" and shows no score. It can't be selected; its menu offers **Restore**.

### Archiving
**Archive** takes a skill out of the list, out of the skill pickers and out of every score. The toast that confirms it has an **Undo** button. Criteria keep their tags to it, so when you restore it, its results come back.

- Archiving a skill also archives the active sub-skills under it.
- Restoring a skill restores only that skill. Its sub-skills stay archived until you restore each one, so a sub-skill you archived on purpose does not come back by accident.
- A sub-skill cannot be restored while the skill it sits under is archived. Restore that skill first.
- To restore, check **Show archived**, open the skill's menu and select **Restore**.

## Import a competency model
**Import** creates many skills at once, from a pasted list or a CSV file. Nothing is saved until you select the import button.

1. On the Skills tab, select **Import**.
2. Choose **Paste a list** or **Upload CSV**.
3. For a pasted list, type one skill per line. Indent a line, or start it with a dash, to put it under the skill above it.
4. For a CSV file, give it a header row with a `skill` column, a sub-skill column and a `description` column. The sub-skill column can be headed `sub-skill`, `sub_skill`, `subskill` or `sub skill`. Headers that competency models often use for the child level, such as `behavior`, `behaviour` and `indicator`, are read as the sub-skill column too. A row with only a skill names a skill. A row with a skill and a sub-skill puts the sub-skill under that skill, and creates the skill as well if it is new.
5. Check the **Preview**. Each row is marked **New skill**, **New sub-skill** or **Matches existing**. Rows that match a skill already in the workspace, ignoring letter case, are skipped. Repeated rows in the file are collapsed into one.
6. Select the button that names how many skills will be created, such as **Import** followed by the number.

Things to know:

- Every cell is read as text. A cell that starts with a formula character such as `=` is saved as plain text, never calculated.
- A row whose skill is missing, or whose name or description is too long, is skipped and listed under "Some rows were skipped" with its row or line number.
- One import takes up to 2,000 new skills and sub-skills. For more, split the file and import each part.
- Imported skills behave like skills created by hand.

## Tag criteria with skills
Every criterion in a simulation's evaluation settings, and every criterion in an evaluator's rubric, has a **Skills** field.

1. Click the field, which reads "Search or add a skill", and type part of a skill's name.
2. Pick a skill from the list. Sub-skills are listed indented under their skill.
3. To make a new skill from the field, type its name and pick **Create skill** followed by the name. It is created as a top-level skill.
4. Save the simulation or evaluator as usual.

Rules for tags:

- A criterion can be tagged with several skills, up to 20. At the limit the field stops offering skills and says "Remove one to add another."
- A criterion can name a broad skill, one of its sub-skills, or both. A result never counts twice for the same skill.
- Tags are bookkeeping only. They are never shown to learners, never sent to the AI judge, and never change a score. Tagging a published simulation or evaluator does not send it through content moderation again.
- A save checks only the tags it adds. A criterion still tagged with a skill that was archived or combined since keeps saving. A tag to an archived skill shows "(archived)" after the skill's name, and a tag to a combined skill shows the skill it was combined with.
- Tags are saved with the simulation's versions. Restoring a version keeps its tags to every skill still in the workspace, archived and combined skills included. Only tags to skills that no longer exist are dropped.
- A duplicated simulation keeps its tags, since it stays in the same workspace. Tags are removed when a simulation is transferred to another workspace, in every version that moves with it, and a template's criteria never bring tags with them.

Because tags live on the criterion as it is now, tagging an older simulation counts its past results at once, and retagging a criterion relabels its past results too. A criterion you delete drops out of every skill's history.

## Combine duplicate skills
When two skills mean the same thing, combine them. Criteria keep their tags, and their results count toward the skill you keep.

1. Select **Combine** at the top of the Skills tab, or **Combine with another skill** in a skill's menu.
2. Under **Combine**, pick the skill that goes away.
3. Under **With (this one is kept)**, pick the skill to keep. It keeps its name and description.
4. Read the summary, which says "Results for" one skill "will count toward" the other, and select **Combine**.

Rules:

- A top-level skill combines only with another top-level skill, and a sub-skill only with another sub-skill.
- Combining a skill that has sub-skills moves its sub-skills under the skill you keep. If the kept skill already has a sub-skill with the same name, the combine is refused until you rename one of them.
- A skill that was combined into one that was later combined again counts toward the last one kept.
- When you select the kept skill, its panel says "Includes results from" followed by the combined skills' names.

To undo, select **Undo** in the toast that confirms the combine, or **Undo** next to it under **Recently combined** on the Skills tab. Undoing puts the combined skill back on its own, moves its sub-skills back, and its results stop counting toward the other skill. A combine can be undone once. If another active skill now uses the combined skill's name in the same place, undo is refused and the message names the skill to rename first.

Undoing the combine of a sub-skill puts it back under the skill it sat under. The message says the sub-skill "can't come back under" that skill, and what to do first, when that skill:

- now sits under another skill: make it a top-level skill first, then undo.
- is archived: restore it first, then undo.
- was itself combined into another skill: undo that combine first.

## Read a skill's score
Each skill on the Skills tab is one line: its name, then the number of results its score rests on, then its blended score over the last 26 weeks as a percentage. Sub-skills are listed the same way, indented under the skill they sit under. On a phone-width screen the number of results and the score sit under the name. A skill with nothing counted yet reads "No results yet".

How the score is worked out:

- A result is one tagged criterion on one evaluated attempt or evaluator result. Its percentage is the points earned out of the points possible on that criterion.
- The score is the average of those percentages. Each criterion counts the same, whatever its point value.
- A top-level skill's score counts every criterion tagged with it or with any of its sub-skills, once each. The panel says "Average score on criteria tagged with this skill or its sub-skills".
- A combined skill's results count toward the skill it was combined with. Archived skills have no score.
- Test runs and feedback-only results are left out. An attempt that had no learner turn is left out. When a dropped voice call was picked back up, the attempt counts once. For evaluators, only final results count.
- When a reviewer changes the rating of an individual criterion, the reviewed points count. A review that changes only the overall score or pass result leaves each criterion's points as the AI judged them, so the skill score does not change.

Select a skill, or a sub-skill, to see its details and trend on the right. On a narrow screen the panel is under the list, and selecting a skill scrolls to it. The panel shows:

- The skill's description, when it has one.
- **Goals this skill moves**: the goals the skill is linked to.
- "Includes results from" followed by the names of the skills combined into it.

Then its trend:

- **Week** and **Month** group the results. Week shows the last 26 weeks and Month the last 12 months. Weeks start on Monday and both are counted in UTC.
- The large number is the latest week or month that has results. A week or month without results is a gap in the line, not a zero.
- Point at the chart, or use the arrow keys, to read each week's score, results and learners. **Show data** opens the same numbers as a table.
- **Counts results from** lists every simulation and evaluator the skill's results came from, with each one's result count. Uncheck any of them to see the score without them. **All simulations and evaluators** checks them all again.
- A selected sub-skill shows its own results only, with a link back to the skill it sits under.

A skill linked to a goal shows the goal's name under **Goals this skill moves** when you select it.

## Goals and the four levels
A goal is one business number: its **Results** measure. Everything else on the goal is evidence gathered under that number, in the four levels evaluation is usually described in. For how to choose the numbers, see [Measuring whether a simulation worked](https://docs.devlin.ai/design-guidance/measuring-simulation-impact).

- **Results**: the number the business cares about, such as an escalation rate. Required, and each goal has exactly one.
- **Behavior**: what people do on the job, from data you already have, such as QA scores, observations or audits. Optional, up to 5 measures. A Behavior measure can name one of the goal's skills, so the on-the-job number sits next to that skill's practice score.
- **Learning**: the practice score of the goal's skills, computed from tagged results and never typed in. You can give it an optional target score.
- **Reaction**: how learners felt about the practice, from your own survey. Optional, up to 5 measures. devlin.ai does not collect survey answers, so these numbers are always ones you record.

These levels are evidence, not proof. The goal page says so: "Evidence by level. These numbers show what changed alongside practice; they do not show cause." A rising practice score next to a falling escalation rate shows the two moved together. It does not show that the simulation moved the business number.

### Create a goal
**New goal** opens a form in three steps. The step names are listed at the top, with the step you are on marked, and each step starts with a sentence on why it matters. **Next** checks the step before moving on, and **Back** returns to the step before without losing what you typed.

1. On **Brain → Goals**, select **New goal**.
2. **The business number.** Type a **Goal name**. Under **Results**, fill in the **Metric**, and optionally the **Unit** (what the number is counted in, such as %, $ or calls), **Better when it** (**Goes up** or **Goes down**), the **Baseline** with the date it was **Measured on**, and the **Target** with the date to reach it **By**. The goal name and the metric are required. Select **Next**.
3. **Skills that move it.** Under **Skills that move this goal**, add the skills practice builds toward this number. You can create a skill from this field too. Optionally, type a **Target score** for Learning. Select **Next**.
4. **Evidence and check-ins.** Everything here is optional. Select **+ Add a Behavior measure** for an on-the-job number, and under **Shows on the job for (optional)** pick one of the goal's skills. Select **+ Add a Reaction measure** for a number from your own survey. Under **Check-ins**, pick a **Review schedule** and its first date (see [Review schedule](#review-schedule)). Under **Status and notes**, add any **Notes**.
5. Select **Save goal**.

A baseline shows on the goal as soon as it is saved: the level shows the **Baseline** and **Target** and says "No new numbers since the baseline. Record one when your next report comes in." When the baseline has a date, it is the first point on the level's chart, so the line starts where the number stood. A measure with no baseline or target is charted as a plain line of the numbers you record.

To change a goal later, open it and select **Edit goal**. The same three steps open, but you can select any step name to go straight to it, and **Save goal** is on every step. If something on another step needs fixing, saving opens that step and says what to fix. The last step also sets the goal's **Status**: **Active**, **Achieved** or **Retired**. Achieved and retired goals move under **Achieved and retired** at the bottom of the Goals tab. Removing a measure that already has recorded numbers is refused: "Delete its recorded numbers first." Removing a skill from the goal also clears it from any Behavior measure that named it. A skill archived or combined after you linked it stays linked, and a Behavior measure that names it keeps it, so the goal's other changes still save. Only a skill you add must be active.

### The Learning level
Learning is the pooled score of the goal's skills: the average over every tagged result of those skills, each result counted once even when it is tagged with two of them. It follows the same rules as a skill's score, and is shown week by week.

Its baseline is the first full week of results after the goal was created, so a week that was already under way when the goal was made never sets it. The goal shows the baseline, the latest week, the target when you set one, and how many results were counted. When the goal has no skills, Learning reads "Not set up" until you add some in **Edit goal**.

### Record a measurement
1. Open the goal and select **Record measurement**, or **Record a number** under a measure that has none yet.
2. Under **Measure**, pick the measure. Learning is not in the list, because it is never typed in.
3. Type the **Value** and the **Date** it was measured, and optionally a **Note** saying where the number came from.
4. Select **Save**.

Every recorded number is listed under **Measurements** on the goal, newest first. To remove a number recorded by mistake, select **Delete** on its row and confirm. Baselines and targets are set on the goal itself, not recorded as measurements.

### Review schedule
A goal's check-ins follow a schedule you pick under **Check-ins** in the goal form:

- **Not scheduled**: the goal is never due.
- **Once**: one review, on the **Review on** date.
- **Every week** or **Every 2 weeks**: on the weekday of the **First review** date.
- **Every month**: under **Repeats**, pick the same day number as the first review, such as "Monthly on day 14", or the same weekday, such as "Monthly on the 2nd Thursday". A first review in the last seven days of its month repeats on the last of that weekday, such as "Monthly on the last Thursday", so it never asks for a fifth weekday a month does not have. A day number a month does not have, such as the 31st, falls on that month's last day.
- **Every quarter**: every three months on the first review's day number.

The form shows the next date as you choose, for example "Next review Thu, Nov 12 (every month on the 2nd Thursday)." The goal page and the goal's card show the same line.

An active goal is due once its next review date has come. It gets a **Review due** badge, and the Goals tab shows a banner that says how many goal reviews are due and ends "Record the latest numbers, then mark it reviewed." (or "mark each one reviewed." when more than one is due). With one goal due, the banner has a button that opens it. Record the latest numbers, then select **Mark reviewed** on the goal page or on the goal's card. That records today as the goal's last review and moves it to the next scheduled date after today, skipping any dates that were missed. A one-time review is done once it is marked. **Mark reviewed** shows only while a review is due. Achieved and retired goals are never due. Reminders appear only in the app; no email is sent.

## A learner's skills
On **Results → Learners**, a selected learner whose results include tagged criteria gets a **Skills** section under the summary card. It lists each skill the learner has results on, with sub-skills under their skill, the latest week's score, the number of results and a small weekly trend over the last 26 weeks. It follows the same rules as the Skills tab. Only results recorded under that exact learner identifier are counted, and only people allowed to see learner identity see the section. See [Learner history and AI summaries](https://docs.devlin.ai/results-and-analytics/learner-history).

## AI tools over MCP
An AI tool connected through the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) can read and change skills and goals with the same rules as the app:

- **Read.** `list_skills`, `list_skill_merges`, `get_skill_results`, `list_goals` and `get_goal`. `get_skill_results` can filter by skill, simulation, evaluator, date range and one learner's identifier. The learner filter is ignored when the person behind the connection may not see learner identities.
- **Skills.** `create_skill`, `update_skill`, `archive_skill`, `import_skills`, `merge_skills` and `unmerge_skill`. `import_skills` takes a structured list, so a tool can read a competency model from any document and import it. One call takes fewer rows than the app's import, so a long list goes in several calls. `merge_skills` is the app's Combine: it changes nothing until the tool confirms, and it can preview first.
- **Goals.** `create_goal`, `update_goal`, `link_goal_skills`, `record_goal_measurement` and `delete_goal_measurement`. A goal's review schedule is set with `review_date` (the first review), `review_cadence` and, for a monthly schedule, `review_monthly_by`. `update_goal` with `mark_reviewed` marks a due review done, the same as **Mark reviewed** in the app, and is refused while no review is due.
- **Tags.** `set_criterion_skills` changes the skill tags of one criterion of a simulation or evaluator and nothing else. On a published or archived simulation or evaluator, the tool has to confirm the live change.

When the workspace requires approval for live changes, combining skills and changing the tags of a published or archived simulation or evaluator are held for an owner or admin to approve in the app. The other skill and goal changes apply directly.

## Related
- [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring)
- [Designing evaluation criteria and pass thresholds](https://docs.devlin.ai/design-guidance/evaluation-criteria-design)
- [Measuring whether a simulation worked](https://docs.devlin.ai/design-guidance/measuring-simulation-impact)
- [Evaluators, scoring learner-submitted work](https://docs.devlin.ai/evaluators/evaluators-scoring-submitted-work)
- [Learner history and AI summaries](https://docs.devlin.ai/results-and-analytics/learner-history)
- [The Results dashboard](https://docs.devlin.ai/results-and-analytics/results-dashboard)