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

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