Skills

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 SKILL.md format.

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

~/wheems/library/skills/weekly-report/
├── skill.yaml       who wrote each version
├── 1/SKILL.md
└── 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.

skills:
  weekly-report: 2

---
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.

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:

The library has no skills yet.

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

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:

skills:
  weekly-report: 1

Then check:

wheems validate

Valid

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

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.

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.

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.

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:

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:

Review
  ! review: 2 skill proposals wait for review
      Run: wheems review

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.

skill_budget: 20