Start a team

Claude Code skill not loading? Find the copy that wins

Last updated: 23 September 2026

You edit a skill and Claude behaves exactly as before. Or you install one and Claude never reaches for it. Both usually have the same cause: the copy you are looking at is not the copy that loads. Here is where Claude Code finds skills, which copy wins, the limit that quietly hides some of them, and how to find the one in effect.

Where Claude Code loads skills from

  • Personal: ~/.claude/skills/<name>/SKILL.md.
  • Project: .claude/skills/ in the folder you started in and each folder above it, up to the repository root.
  • Nested: a .claude/skills/ inside a subfolder, loaded the first time Claude touches a file there.
  • Plugins: run as /plugin-name:skill-name.
  • Enterprise: the managed settings folder, set by an administrator.
  • Your claude.ai account: skills synced into ~/.claude/skills/synced/, since v2.1.273.

Which copy wins

When two skills share a name, enterprise beats personal, and personal beats project. The loser is not an error and nothing tells you about it. So a skill in your repository's .claude/skills/ does nothing if a personal skill of the same name exists in your home folder, and editing the project copy changes nothing you can see. Plugin skills carry the plugin's name, so they never collide. A synced claude.ai skill steps aside and runs as /anthropic-skills:<name>.

The listing budget

Claude sees every skill's name and description at the start of a session, and loads the full skill only when it uses one. That list gets 1% of the context window. When there are more skills than fit, every name stays, but the least-used skills lose their descriptions, and each description is cut at 1,536 characters. A skill whose description was dropped is one Claude rarely picks, because it no longer knows what the skill is for. Short, specific descriptions are the fix.

When changes take effect

Edits to a skill in a folder Claude is already watching apply without a restart. A skills folder created after the session started is not watched, so a new project .claude/skills/ needs a restart before its skills appear.

Check what loaded

Type /skills in Claude Code to list the skills this session has. If the one you expect is missing, or appears under a different description, search your home folder and plugins for another copy with the same name.

Codex is different

Codex follows the open agent skills layout: .agents/skills in each folder from the working folder up to the repository root, ~/.agents/skills for your own, and /etc/codex/skills for administrators. The older ~/.codex/skills still loads but is on its way out. Its first listing gets 2% of the context window, and it warns when some skills are left out.

Find the copy in effect with flanner

Flanner Skills reads every skill package on the machine, runs nothing, and tells you which copy each agent loads:

flanner skills list
flanner skills list --all
flanner skills inspect deploy
flanner skills doctor
  • skills list shows what is in effect; --all adds the shadowed copies behind it.
  • skills inspect shows every copy of one skill, and which one wins.
  • skills doctor exits with an error on a defect: a SKILL.md with no name or description, a name that does not match its folder, a copy shadowed by one from somewhere else, or differing copies that Codex would offer side by side.

On the machine flanner was built on, 110 skill packages were installed and 57 were in effect. The other 53 were shadowed, and editing one of those is the usual cause of "my change did nothing".

To see which skills actually get used, turn on observation with flanner skills observe enable, then read flanner skills report --days 30. It records the skill's name, the time and the session, never your prompts, and works for Claude Code; Codex use shows as unknown.

flanner reads project, personal and plugin skills for Claude Code, and repository, user and administrator skills for Codex. It does not read enterprise, nested or synced claude.ai skills, so check those with /skills. The skills docs cover changing a skill safely and rolling one back.

Sources

Checked on 23 September 2026, against Claude Code v2.1.280.

← All posts