# Skills

> How skills are written, versioned in the library and pinned per workspace, how agents propose them, and how you approve them with wheems review.

A **skill** is how to do a task that comes up again: the steps, the checks, and what to watch for. Agents propose skills as they learn, and none reaches the library without you. This page covers the library, writing a skill yourself, proposals and review.

Skills use the [Agent Skills](https://agentskills.io) `SKILL.md` format.

## The library

The install's library holds every skill at every version, numbered 1, 2, 3:

```text
~/wheems/library/skills/weekly-report/
├── skill.yaml       who wrote each version
├── 1/SKILL.md
└── 2/SKILL.md
```

```markdown title="library/skills/weekly-report/2/SKILL.md"
---
name: weekly-report
description: Writes the weekly report. Use when asked for a summary of the week.
---

1. Read the git log for the last seven days and the brief.
2. List what shipped, what's blocked and what's next.
```

- The library is never loaded into an agent whole.
- A workspace **pins** the versions it uses in `skills.yaml`, so a new version never silently reaches a live workspace.
- Each agent lists the skills it uses in its front matter, chosen from its workspace's `skills.yaml`.
- `skill.yaml` records the versions agents proposed. A version it doesn't list was written by a person, and no agent can change that skill.

```yaml title="~/wheems/workspaces/acme/skills.yaml"
skills:
  weekly-report: 2
```

```markdown title="~/wheems/workspaces/acme/agents/chief-of-staff.md"
---
engine: claude-code
model: claude-opus-5-5
account: claude-subscription
skills: [weekly-report]
---
```

`wheems validate` checks that every pinned version exists in the library and that each agent's skills are in its workspace's `skills.yaml`.

## Looking at skills

```bash title="Terminal"
wheems skill list                  # the library, and proposals waiting for review
wheems skill show weekly-report    # the latest version
wheems skill show weekly-report 1  # an older one
```

With no skills yet:

```text title="Output"
The library has no skills yet.
```

## Writing a skill yourself

Create the skill's first numbered folder and its `SKILL.md`:

```bash title="Terminal"
mkdir -p ~/wheems/library/skills/weekly-report/1
$EDITOR ~/wheems/library/skills/weekly-report/1/SKILL.md
```

Give it front matter with a `name` (lowercase words and dashes, the same as the folder) and a `description` that says when to use it, then the instructions.

Pin it in each workspace that should have it, and list it on the agents that use it:

```yaml title="~/wheems/workspaces/acme/skills.yaml"
skills:
  weekly-report: 1
```

Then check:

```bash title="Terminal"
wheems validate
```

```text title="Output"
Valid
```

A new version is a new numbered folder, `2/SKILL.md`. Change the pin to move a workspace to it.

## How agents propose skills

When an agent works out how to do something it'll be asked to do again, it proposes a skill. Its built-in instructions tell it to improve an existing skill rather than add another, read a skill before changing it, write lessons rather than logs, and leave out one-off failures.

```bash title="Terminal (in an agent's session)"
wheems skill propose weekly-report - <<'EOF'
---
name: weekly-report
description: Writes the weekly report. Use when asked for a summary of the week.
---

The steps, in plain English.
EOF
```

Wheems checks the proposal before saving it to `.wheems/review/skills/`. It needs:

- front matter with a `name` and a `description`, and instructions after it;
- at most 64 KB;
- nothing that looks like a credential.

### Near-duplicates

Each proposal is compared with every skill in the library and every waiting proposal. With an embedding model that has a known near-duplicate score, the comparison is by meaning: for `nomic-embed-text` that's 0.8, measured on real skills (near-duplicates score 0.84 to 0.94, different tasks 0.75 or less). Otherwise it compares the share of words the two have in common. The agent is told which skills its proposal may repeat, and so are you when you review.

## Reviewing with `wheems review`

```bash title="Terminal"
wheems review
```

It goes through what waits for you:

- **skills agents proposed**: a new skill in full, or a change as a diff against the version it changes;
- **changes to `about-you.md`** the filer suggested, as a diff.

For each, choose:

| Choice | What happens |
| --- | --- |
| **Approve** | It's applied. |
| **Edit, then approve** | It opens in your editor (`$VISUAL`, then `$EDITOR`). What you save is approved. |
| **Turn it down** | It's deleted. |
| **Leave it for later** | It stays waiting. |
| **Stop reviewing** | You leave; the rest stays waiting. |

Approving a skill:

1. adds it to the library as the next version;
2. pins that version in the proposing workspace's `skills.yaml`;
3. asks which of the workspace's agents get it, with the one that proposed it ticked;
4. commits.

Outside a terminal, or with `--list`, `wheems review` only lists what waits. `wheems doctor` says how much waits too:

```text title="Output"
Review
  ! review: 2 skill proposals wait for review
      Run: wheems review
```

> **Planned · milestone 5:** Approved skills are recorded and pinned, but not yet written into agents' sessions. Every agent in a workspace shares one folder today, so a skill written there would reach all of them, not only the agents it was given to. From milestone 5 each agent session gets a folder of its own, which carries only its pinned skills.

## The skill budget

Too many skills crowd an agent's context. `skill_budget` in `workspace.yaml` (default 20) is how many skills a workspace may pin, or one agent may list, before `wheems validate` and `wheems doctor` warn: `21 skills is over the budget of 20`.

```yaml title="~/wheems/workspaces/acme/workspace.yaml"
skill_budget: 20
```