claude-code - 💡(How to fix) Fix [FEATURE] Support additional skills search paths (e.g. .agents/skills/) to enable sharing with Codex and Gemini [1 comments, 2 participants]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet (previous requests were closed)
• This is a single feature request (not multiple features)

Problem Statement

Claude Code only discovers skills from two fixed paths:

• ~/.claude/skills/ (personal)
• .claude/skills/ (project)

There is no way to configure additional search paths. This has been requested multiple times — all closed without implementation:

• #18621 — Add option to configure skills path
• #22902 — Custom skills directory paths via env var or settings
• #33957 — Support configurable skills directory path

This is now more urgent: both Codex and Gemini CLI have adopted .agents/ as their standard directory for shared AI tooling (skills, agents, prompts). Teams using multiple AI coding agents now have a natural canonical location for shared skills — .agents/skills/ — but Claude Code cannot read from it.

Current workarounds are poor

1. Symlinks (.claude/skills → .agents/skills) — symlinks are poorly supported in git (cross-platform issues, CI environments often don't preserve them)
2. Duplicate skills in both directories — defeats the purpose; skills diverge over time
3. Local plugin with extraKnownMarketplaces — requires a .claude-plugin/marketplace.json manifest and forces skills into .agents/.claude-plugin/skills/ rather than .agents/skills/, an awkward structure that breaks Codex discovery
4. --add-dir — requires CLI flag at launch time rather than project configuration; doesn't work with IDE integrations

Proposed Solution

Add a skillsPaths array to settings.json (project or user scope):

{
  "skillsPaths": [".agents/skills"]
}

Skills found in these paths would be loaded in addition to the standard .claude/skills/ and ~/.claude/skills/ locations. Relative paths would resolve from the project root.

An environment variable alternative would also be acceptable:

CLAUDE_SKILLS_PATH=".agents/skills:.claude/skills"

Why This Matters

The multi-agent ecosystem is converging on .agents/ as a shared directory. Codex reads .agents/skills/ by default; Gemini CLI follows the same convention. Claude Code being the odd one out means teams are forced into fragile workarounds just to share skills across tools that are often used on the same codebase.

A skillsPaths setting in settings.json is a small, low-risk change that would allow teams to maintain a single set of skills in .agents/skills/ — committable, cross-platform, no symlinks required — and have all their AI tools discover them.

Environment

• Platform: Linux (WSL2) / cross-platform ask
• Claude Code CLI + IDE integrations