Skills
A skill is a set of written instructions the agent follows for a kind of task. Skills are kept in one place, published as numbered versions, tested and reviewed.
On this page5 sections
What a skill is#
A skill is a folder containing a file named SKILL.md, plus any supporting files the instructions refer to: templates, checklists, scripts, examples. When the agent takes on a task the skill applies to, it reads the skill and follows it.
Skills are how a team's way of doing something stops living in one person's head. Write it down once, improve it as the work teaches you, and every workspace that uses the skill gets the improvement when it chooses to take it.
A skill's SKILL.md has to start with a short header that includes a description. The agent uses the description to decide when the skill applies, so a skill without one is never loaded.
---
description: Compare a carrier's new rate sheet with the current one and list every change.
---
# Compare rate sheets
1. Open both files and confirm they cover the same lanes.
...
How skills are managed#
| Idea | What it means |
|---|---|
| Home | Every skill has one home workspace. The home holds the skill's working copy, and only the home edits it. One workspace can be the home of several skills. |
| Draft | The working copy in the home. The home's own agent uses the draft as it stands. Nobody else receives it. |
| Version | Publishing turns the draft into a numbered version that never changes. Other workspaces only ever use a published version. |
| Pin | A workspace uses a skill by pinning one version. It gets its own copy of that version. |
| Offer | When a new version is published, workspaces pinned to an older one are offered it. Nothing changes until a person accepts. |
| Owners | A skill has one or more owners, who decide what gets published when reviews are required. |
| Cases | Finished tasks kept as examples, which the skill can be run against to see whether a change made it better or worse. |
| Track record | For each version: how often it was used, how long it took, what it cost, and how often a review corrected the result. |
Where skills appear#
In a workspace. Open Skills in the left bar. The view has up to three groups:
- Managed here: skills this workspace is the home of.
- Pinned: skills this workspace uses from another home, with the version, and a note when a newer one is offered.
- On this drive, not from the library: skill folders in the workspace's files that are not managed as skills. They are not versioned or tracked.
Click a skill to open it in a tab.
On the Workspaces page. The Skills tab lists every workspace that is the home of at least one skill.
On a service. A service's Configuration page has a Skills panel listing the skills its engagements start with.
A typical path#
- Do a piece of work well in a workspace, with the agent.
- Write down how it should be done as a skill in that workspace, and make it a skill.
- Publish version 1.
- Pin it in the workspaces and services that do this kind of work.
- Save finished tasks as cases, so that changes can be tested.
- Improve the draft, run the cases, publish version 2. Workspaces that use the skill are offered it.
- Once several people depend on the skill, turn on review before publishing.
Who can do what#
| To do this | You need |
|---|---|
| See a workspace's skills | View access to the workspace. |
| Make a skill, edit its draft, publish, move it, add and run cases | Edit access to the skill's home. |
| Pin a skill, accept an offer, remove a pin | Edit access to the workspace that is pinning. |
| Decide a skill review, change the publish rule, change owners | To be an owner of the skill, or the owner of its home workspace. |
| Delete a skill | To be the owner of its home workspace, or an organization admin. |
| Attach a skill to a service | Organization admin. |