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