Agent Skills: Proximity Isn't Precedence

Skills let a coding agent follow a repeatable procedure without being told it again every session. A skill is a folder, its instructions load when a task matches, and the rest of the time it costs almost nothing. That much is well documented. What is less obvious is that a skill's location is part of its meaning. The same SKILL.md file behaves differently depending on which directory it sits in, and the difference is not only a question of who can see it.

This article is about that difference: where a skill can live, what each placement actually changes, how two skills with the same name resolve against each other, and how to decide which content belongs where.

What a skill actually is

A skill is a directory containing a SKILL.md file, plus whatever else the procedure needs: scripts, reference documents, templates, assets. The frontmatter carries the metadata, the body carries the instructions.

The structural fact worth holding onto is the split between those two. A skill's description is always in context, because that is how the agent decides whether the skill is relevant to the task in front of it. The body is not. It loads only when the skill is actually used, which is why a skill can carry a long reference document at almost no standing cost. Claude Code truncates the combined description and when_to_use text at 1,536 characters in the skill listing for precisely that reason, and recommends putting the key use case first.¹

That split is what separates a skill from an always-on instruction file. CLAUDE.md is injected on every turn, so everything in it competes for attention on every turn, whether the current task needs it or not. A skill is a playbook the agent goes and fetches. It is not a tool or an MCP server either: those add capabilities the agent did not have, while a skill adds procedure over the capabilities it already has.

Where skills can live

There are four locations.¹

• Personal, at ~/.claude/skills/<skill-name>/SKILL.md. Available in every project on your machine.
• Project, at .claude/skills/<skill-name>/SKILL.md. Available inside that repository only.
• Plugin, at <plugin>/skills/<skill-name>/SKILL.md. Available wherever the plugin is enabled, under a plugin-name:skill-name namespace.
• Enterprise, in the managed settings location for the platform.² Applies to every user in the organization.

Availability is not the same thing as presence on disk, and the discovery rules are where monorepos get interesting. Project skills load from .claude/skills/ in the directory the session starts in and in every parent directory up to the repository root, so starting in a subdirectory still picks up the skills defined at the top. Skills in nested directories below the starting point are not loaded at startup at all. They become available the first time the agent reads or edits a file inside that subdirectory, and then stay available for the rest of the session. That is the mechanism that lets a package ship its own skills: touch a file under apps/web/, and apps/web/.claude/skills/ comes into scope behind it.

Added directories load skills too, and this is a deliberate exception. --add-dir grants file access rather than configuration discovery, but .claude/skills/ inside an added directory is loaded alongside the project skills anyway.

Edits are picked up live. Adding, changing or removing a skill under a watched directory takes effect inside the current session. Creating a top-level skills directory that did not exist when the session started needs a restart, since there was nothing there to watch.

Skills have a cascade

Those four locations are the origins of a cascade, and skills resolve the way CSS does. The comparison is worth taking literally rather than loosely, because it is precise about the part people get right and about the part they get backwards.

Two separate mechanisms are at work.

• Where a skill applies behaves like a selector. It runs from broad to narrow: your home directory is every session on the machine, a repository is one project, a nested directory is one package inside it.
• Which skill wins when two share a name behaves like origin and importance. It does not run narrow to broad. The broader placement wins.

Getting this inverted is the usual mistake. It is tempting to assume the skill nearest the working directory is the strongest one, the way a nested rule in a stylesheet usually is. For availability that intuition is right. For a name collision it is exactly wrong.

What happens when two skills share a name

Enterprise overrides personal, personal overrides project, and a skill at any of those three levels overrides a bundled skill of the same name. A code-review skill in your project's .claude/skills/ replaces the bundled /code-review. If a skill and a command share a name, the skill takes precedence.

Two parts of that are commonly stated wrong.

Plugin skills do not participate in it. They carry a plugin-name:skill-name namespace, so they cannot collide with the other levels at all. Plugins are not the bottom rung of the ladder, they are off the ladder.

Nested skills do not override either, they coexist. Given a deploy skill at the repository root and another at apps/web/.claude/skills/deploy, both stay available. The nested one appears under a directory-qualified name, apps/web:deploy, and its description says which directory it applies to. Typing /deploy runs the root skill and typing the qualified name runs the nested one. When the unqualified name is invoked, the root skill loads with a list of the qualified variants appended to it, plus an instruction to also invoke any variant whose directory holds the files being worked on. The nested skill therefore still applies to work in its own directory even when nobody typed its qualified name.

That is the cascade behaving like a cascade rather than like a switch, and it is the one place where narrower really does mean more applicable. Everywhere else, collisions are resolved by origin, which is a reason to make them impossible: give skills clear, unique names. frontend-pr-review rather than review.

What placement actually changes

Personal. Available in every project and every session on your machine, so a change affects all future work immediately. It stays private and never travels through git. The sharp edge is that a personal skill does not exist outside your machine: Cowork sessions, cloud sessions and routines do not read ~/.claude/skills/. A routine that invokes a personal-only skill reports it as not found, because every run starts as a fresh remote session.

Project. Available only while you are working inside that repository, and completely isolated from your other projects. It travels with the repo, so teammates get the same behavior when they clone it, and cloud sessions load it from the cloned repository. It also carries a trust consequence. A project skill's allowed-tools takes effect after you accept the workspace trust dialog for the folder, the same as the permission rules in .claude/settings.json, and a skill can grant itself broad tool access. A checked-in skill is something to read before trusting a repository rather than after.

Plugin. Versioned distribution across repositories and people, namespaced so it never fights with anything.

Enterprise. Policy. It wins every collision, and it can set things users are not able to override, such as turning off shell execution inside skills.

Home placement creates a persistent personal baseline. Project placement creates context-bound, shareable behavior. Plugin placement creates distributable behavior. Enterprise placement creates policy. The choice controls whether a skill follows you everywhere or stays locked to one codebase, and whether it exists at all when the session is not running on your laptop.

Deciding what goes where

Ask one question: is this my reusable habit, or this codebase's required workflow?

Habits go in the home directory:

• your preferred commit-message style
• your documentation or explanation format
• cross-project research and summarization routines

Requirements go in the repository:

• the team's code-review checklist, tied to this project's conventions
• the deployment or release procedure for this stack
• the architecture or testing rules everyone has to follow

Anything on the second list that more than one repository needs belongs in a plugin instead. And if a personal habit turns out to be something you also need in cloud sessions or routines, that is a reason to move it into a repository or a plugin, not a reason to keep a second copy at home.

A few things about shape rather than location:

• Keep the core procedure in the body and move heavy reference material into separate files in the same folder, read on demand. The body's cost is paid only when the skill runs, and a separate file's cost is paid only when the body says to open it.
• Write the description for retrieval rather than for documentation. It is the one part that is always in context, and the decision to load the skill is made from it.
• Use the paths frontmatter field when a skill applies to part of a repository rather than all of it. Glob patterns there limit automatic activation to matching files, which is the selector half of the cascade stated explicitly instead of inferred from where the folder happens to sit.
• Split a skill that has grown broad into two narrower ones. A description covering two situations is worse at being loaded for either of them.
• Do not duplicate the same rule at home and in the project. One of the two copies will drift, and precedence means you will not be told which one you are running.

References

1. 1.Claude Code docs: Extend Claude with skills
2. 2.Claude Code docs: Settings files