You run npx skill install my-skill, the install completes cleanly, and then you open Claude Code and ask it to use the skill. Claude has no idea what you are talking about. The skill simply does not exist as far as the agent is concerned. This is not a broken install or a corrupted file. It is a path mismatch: the npx skill CLI writes to ~/.agents/skills/, but Claude Code looks exclusively in ~/.claude/skills/. Two different directories, zero overlap.
Where the Paths Diverge
The npx skill command comes from the Claude Code ecosystem and follows the Agent Protocol convention for storing agent assets. Under that convention, skills live at:
Claude Code, however, resolves skills from its own configuration directory:
When you run npx skill install, the package lands in ~/.agents/skills/. Claude Code scans ~/.claude/skills/ at startup and finds nothing new. The two directories never communicate with each other by default.
Fix 1 - Manual Symlink
The fastest one-time repair is a symlink. A symlink makes the skill directory appear in both locations simultaneously without duplicating any files. Changes to the skill (updates, edits) are reflected in both paths automatically.
The -sfn flags mean: create a symbolic link (-s), force-replace any existing entry (-f), and treat the target as a directory name rather than following it if it already exists (-n). After running this, Claude Code will see the skill on the next session start.
If you have several skills already installed that you want to migrate at once:
This approach works but it requires you to remember to run it each time you install a new skill.
Fix 2 - The SessionStart Hook
A more durable fix is to configure a SessionStart hook in ~/.claude/settings.json. Claude Code fires this hook automatically at the beginning of every session, before any user interaction. By placing the sync logic there, you never have to think about it again.
A SessionStart hook runs once at the top of every Claude Code session. That makes it the right place for one-time environment setup that should always be current.
Open (or create) ~/.claude/settings.json and add the following hooks block. If you already have other settings in the file, merge the hooks key into your existing JSON rather than replacing the whole file.
The command iterates over every subdirectory in ~/.agents/skills/, checks that it is actually a directory (guards against empty globs), and creates or refreshes a symlink for it in ~/.claude/skills/. The 2>/dev/null || true at the end prevents the hook from surfacing errors when ~/.agents/skills/ does not yet exist or is empty.
Setting "async": true means Claude Code does not wait for the symlink loop to finish before proceeding. The operation is fast enough that it will complete well before you type your first message, but marking it async avoids any perceptible delay on startup.
What the Hook Does Not Cover
The hook syncs directories but it does not install skills. You still use npx skill install to install and npx skill update to update. The hook simply ensures that whatever lands in ~/.agents/skills/ is also visible to Claude Code - automatically, every session.
It also does not handle the reverse direction. Skills placed directly in ~/.claude/skills/ (without going through npx skill install) are already in the right place and need no syncing.
If you keep skills in a third location - for example a team-shared directory on a network mount or a dotfiles repo you manage yourself - you can extend the hook command to loop over that path as well:
Why This Happens at All
The root cause is that the npx skill CLI and Claude Code were developed along different conventions for where agent assets should live. The Agent Protocol ecosystem uses ~/.agents/ as a neutral, tool-agnostic home for skills, MCP servers, and similar artifacts. Claude Code uses ~/.claude/ as its configuration root, following the same pattern as ~/.vscode/, ~/.cursor/, and similar editor-specific directories.
Neither convention is wrong. They serve different goals. The mismatch will likely be resolved in a future release - either npx skill install will detect the Claude Code directory and offer to install there, or Claude Code will grow support for reading from multiple skill paths. Until then, the symlink approach or the SessionStart hook bridges the gap without touching either tool's internals.
The fix takes thirty seconds. The SessionStart hook takes sixty. Either way, you only do it once.
Hit a different Claude Code configuration issue? The Layer5 community on Slack includes a growing group of developers working through exactly these kinds of AI tooling edge cases - drop in and share what you found.
Team
