Skill Discovery

Discovery Is a Scan, Not a Search

In the hands-on lesson, you watched Claude Code find roll-dice the moment your session started — before you’d said anything about dice. That’s discovery: at session start, an agent scans a fixed set of directories, and for every SKILL.md it finds, reads only the name and description. It does this for every skill installed, whether or not the conversation ever touches on it.

This lesson is about the “fixed set of directories” part — exactly where an agent looks, and why there’s more than one location.

Where Claude Code Looks

Personal skills live in ~/.claude/skills/ — available across every project on your machine. This is the right home for skills about how you work rather than any one codebase: a personal debugging checklist, a preferred way of reviewing your own pull requests before opening them.

Project skills live in .claude/skills/ at the project root — the location you used in the hands-on lesson. Because this directory is part of the repository, project skills are naturally shared: commit one, and every teammate who pulls the branch gets it automatically, with no separate install step. This is the right home for anything specific to the codebase itself.

Plugin skills ship bundled inside an installed Claude Code plugin. A plugin can package multiple skills alongside other capabilities, so installing the plugin is what makes its skills available — you don’t manage the individual skill files the way you do personal or project ones.

Claude Code discovers skills from all three sources at once and treats them identically once found — a plugin skill isn’t more or less likely to activate than a project skill with an equally good description. Location determines where a skill lives and how it’s shared, not how it behaves once discovered.

Why More Than One Location?

Each location answers a different question about a skill:

Put a skill in the wrong location and it still technically works, but it stops traveling with the thing it’s actually about — a personal habit stuffed into a project directory forces it on every teammate; a project-specific convention kept in your personal directory means nobody else benefits from it.

The Cross-Client Convention: .agents/skills/

Because Agent Skills is an open format, more than one agent product needs to agree on where to look — and .claude/skills/ is understandably Claude Code’s own convention, not something a different vendor’s tool would necessarily check. To solve this, a second path has emerged across the ecosystem: .agents/skills/ (project-level) and ~/.agents/skills/ (user-level).

A skill placed under .agents/skills/ is automatically visible to any compliant client scanning a project — not just Claude Code. Many clients scan both their own native path and this shared one, precisely so that a skill written once doesn’t need a separate copy per tool.

If you’re writing a skill purely for your own Claude Code use, .claude/skills/ is simplest. If you know it’ll be used from more than one client — say, some teammates use Claude Code and others use a different agent product — .agents/skills/ is worth using instead, since the file itself doesn’t change either way; only its location does.

Working Through an Example

Say a project has this layout:

my-project/
├── .claude/skills/
│   └── deploy-checklist/SKILL.md
├── .agents/skills/
│   └── api-conventions/SKILL.md
└── ...

In Claude Code, both deploy-checklist and api-conventions get discovered — Claude Code checks its own native path and the cross-client one. A teammate using a different, .agents/skills/-only client would discover api-conventions but not deploy-checklist, since that skill only exists in Claude Code’s native location.

This is worth predicting correctly before you rely on it: a skill’s location determines its audience just as much as its content does.

Summary

• Discovery happens at session start: an agent scans fixed directories and reads only name + description from every SKILL.md it finds
• Claude Code checks three kinds of location — personal (~/.claude/skills/), project (.claude/skills/), and plugin-bundled — treating skills from all three identically once discovered
• .agents/skills/ (project and user scope) is a cross-client convention that makes a skill visible to any compliant agent product, not just Claude Code
• Where you put a skill determines who and what discovers it — a real design decision, not just a filesystem detail

Discovery tells an agent a skill exists. The next lesson covers what happens after that — the full progressive loading model, and exactly what it costs in tokens at each stage.