[Bug]: Claude Code cannot read globally installed skills from ~/.agents/skills

[zhangxy-zju]

Description

When installing skills globally with Claude Code selected, skills are installed to ~/.agents/skills (canonical location), but Claude Code cannot read them because it looks for skills in ~/.claude/skills.

Steps to Reproduce

1. Install a skill globally: npx skills add <source> -g
2. Select Claude Code as the agent
3. The skill is installed to ~/.agents/skills/
4. Claude Code cannot discover the skill because it reads from ~/.claude/skills/

Expected Behavior

Claude Code should be able to read globally installed skills from ~/.agents/skills, similar to other universal agents like Cline, Codex, Cursor, etc.

Actual Behavior

Skills installed to ~/.agents/skills are not discoverable by Claude Code.

Root Cause

The isUniversalAgent() function only checks if skillsDir === '.agents/skills' for project-level, but doesn't consider the global case where an agent's globalSkillsDir points to the canonical ~/.agents/skills.

Claude Code's configuration:

• skillsDir: '.claude/skills' (project-level, non-universal)
• globalSkillsDir: '~/.claude/skills' (was pointing to a different directory than canonical)

Solution

1. Update claude-code's globalSkillsDir to ~/.agents/skills
2. Modify isUniversalAgent() to accept a global parameter and check if globalSkillsDir === ~/.agents/skills
3. Update related functions (getUniversalAgents, getNonUniversalAgents, etc.) to support the global context

Version

1.4.5

Operating System

macOS

[anglee0323]

Just checked on my machine — the symlink is actually created correctly:

~/.claude/skills/find-skills -> ../../.agents/skills/find-skills

So the intended design seems to be:

1. The actual skill files live in ~/.agents/skills/ as the single source of truth
2. A symlink is created from ~/.claude/skills/<skill-name> pointing to that location
3. Claude Code follows the symlink and finds the skill normally

This design makes sense — skills are stored once in the universal location, and each agent just gets a symlink. Updates to ~/.agents/skills/ are automatically reflected without needing to sync copies.

The bug you're reporting might be that the symlink creation step is failing or being skipped in certain environments/versions, rather than the directory mapping being wrong. Worth checking whether the issue is in symlink creation logic rather than the globalSkillsDir path itself.

[zhangxy-zju]

Fix Summary

Updated the PR #694 with a more comprehensive fix. The root cause turned out to be two separate bugs:

Bug 1: isUniversalAgent() didn't distinguish project vs global level

Agents like Cursor, Copilot, Codex etc. use .agents/skills at project level (universal) but have distinct global directories (~/.cursor/skills, ~/.copilot/skills). The old isUniversalAgent() only checked skillsDir (project level), so during global install it incorrectly treated these agents as "universal" and skipped creating agent-specific symlinks — meaning ~/.cursor/skills/, ~/.claude/skills/ etc. were left empty.

Fix: isUniversalAgent(type, isGlobal?) now checks globalSkillsDir === ~/.agents/skills when isGlobal=true.

Bug 2: uniqueDirs check forced copy mode incorrectly

In add.ts, the install-mode decision used project-level skillsDir for the uniqueness check, even during global installs. This caused two problems:

• Agents with different globalSkillsDir but same skillsDir were treated as identical → forced installMode = 'copy'
• For local source paths, copy mode was always forced — losing the live symlink to the local source

Fix: uniqueDirs now uses globalSkillsDir for global installs. Local sources always get the symlink/copy prompt (defaulting to symlink with --yes).

Result

After the fix, skills add /local/path -g -a claude-code -y correctly creates:

~/.claude/skills/<skill> → ~/.agents/skills/<skill> → /local/source/path

All SKILL.md files are accessible through the full symlink chain.

[gjkim42]

Encountered the same issue.

Is there a workaround for this?
Not sure which version introduced this bug.

[cutlery]

+1 for this