# Skills

A skill is a directory of instructions the agent pulls in when it is relevant:

```
~/.agents/skills/commit-helper/SKILL.md      every repo
./.agents/skills/commit-helper/SKILL.md      this one, checked in
```

```markdown
---
name: commit-helper
description: Use when writing commit messages for this repo
---

Read the last twenty commits for tone before writing anything.
Conventions are in references/conventions.md.
```

The directory name is the skill's name, and a `name:` that disagrees with it is
a load error. Only the description reaches the model until the skill is
invoked, so it is what decides whether the skill fires at all; the body can be
as long as you like.

Two ways in, one way to load. The agent calls the `skill` tool when a
description matches what it is doing; you can force one with `/commit-helper
fix the flaky test`, which the model answers by making the same call. `/skills`
lists what was found, project shadowing personal on a name collision, grouped
by where each one came from:

```
skills: 3
  personal
    /commit-helper  Use when writing commit messages
  claude
    /pdf            Extract text and tables from PDFs
  claude:superpowers
    /brainstorming  Use when exploring an idea before writing a plan
```

One line each, truncated to the width. A description written for another
harness can be three sentences long, and this list is for recognising a skill
you already know about rather than for reading it.

Skill directories are readable by `read_file`, `glob` and `grep` even though
they sit outside the working root, so a skill can ship reference files and
point at them. They are not writable by anything: `edit_file`, `write_file` and
`bash` keep the working root as their only root. A skill is input, not a work
product.

Relative paths still anchor to the working root, so a skill pointing at its own
files is read with the directory the `skill` tool prints joined on. If the model
forgets, the "no such file" it gets back names the skill directories, which is
usually enough to recover on the next turn. A shadowed skill's directory is not
readable — only the skills actually in play widen anything.

Discovery happens at startup. The name-and-description listing goes in the
cached prompt prefix, so re-reading the directory each turn would cost a cache
miss on every turn for a file that never changes. Restart to pick up a new
skill. `-no-skills` turns the whole thing off; the eval runner never discovers
skills at all, so METRICS.md is unaffected by what is in your home directory.

## Claude Code's skills

Codey can also use the skills Claude Code already has on this machine — the
ones under `~/.claude/skills`, the ones its installed plugins ship, and a
project's `.claude/skills`. The setup wizard asks about them, and only when
there are some to offer, because a question about nothing is a question worth
not asking:

| `claude_skills` | What happens |
| --- | --- |
| `off` | they are left alone; Codey reads only its own roots. This is the default |
| `use` | they are read where they lie, on every start, so updating a plugin in Claude Code updates the skill here with nothing to re-run |
| `copy` | they are copied once into `~/.agents/skills`, where they are yours to edit and unaffected by the next plugin update |

Off is the default for the same reason `web_search` defaults to none: a skill
is a page of instructions the model will follow, and it should be loaded
because you said so rather than because a directory happened to exist in your
home directory.

Plugins come from `~/.claude/plugins/installed_plugins.json`, newest install
per plugin, so the stale versions left in the cache are not loaded three times
over. A skill of your own in `~/.agents/skills` wins when it shares a name with
one of Claude's — what you put there is a decision, what arrived with a plugin
is not — and `copy` never overwrites a skill already there. Frontmatter Codey
would otherwise reject is accommodated rather than skipped: a name with
capitals, underscores or spaces in it, or one that disagrees with its own
directory, is normalised into a slug instead of becoming a load error, because
these files were written for another harness and are not yours to fix.
`/skills` lists each one with where it came from — `claude`, or
`claude:superpowers` for a plugin's.