[FEATURE] Support user-level .agents/skills/ discovery for cross-agent single-source-of-truth workflows

Preflight Checklist

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

Problem Statement

Summary

Claude Code should support discovering user-level Agent Skills from ~/.agents/skills/, in addition to the existing Claude-specific locations such as ~/.claude/skills/.

This would allow developers who use multiple AI coding agents to maintain a single source of truth for reusable skills, instead of duplicating the same skill folders into tool-specific directories.

Current behavior

Claude Code supports user-level instructions through ~/.claude/CLAUDE.md.

Those instructions can import external files with @path, so it is possible to keep shared instruction files outside the Claude-specific folder, for example:

@~/.agents/instructions/core.md
@~/.agents/instructions/workflows.md
@~/.agents/instructions/architecture.md

That solves the instruction side reasonably well.

However, skills are different. Claude Code discovers skills from Claude-specific locations, such as:

~/.claude/skills/
<project>/.claude/skills/

Even when using --add-dir, Claude Code only auto-loads skills from .claude/skills/ inside the added directory.

This means a shared user-level layout like this is not discoverable as skills:

~/.agents/
├── instructions/
│   ├── core.md
│   ├── architecture.md
│   └── workflows.md
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── repo-analysis/
    │   └── SKILL.md
    └── pdf-processing/
        └── SKILL.md

Why this matters

Many developers do not use only one AI coding tool. A realistic workflow may involve Claude Code, Codex, Copilot, Cursor, Gemini CLI, or other agents depending on the task.

For these workflows, duplicating the same skills into multiple tool-specific directories creates several problems:

• Skill definitions drift over time.
• Fixes must be copied manually across directories.
• A user cannot maintain one canonical cognitive map for all agents.
• Tool-specific folder conventions become vendor lock-in.
• The same SKILL.md format becomes less portable than intended.

In my workflow, ~/.agents/ is the canonical location for reusable agent knowledge:

~/.agents/
├── instructions/
├── skills/
└── agents/

A small Claude-specific wrapper for instructions is acceptable. Duplicating skills into ~/.claude/skills/ is not, because skills are executable/reusable knowledge units and should remain canonical.

Expected behavior

Claude Code should scan ~/.agents/skills/ as an additional user-level skills directory.

Suggested discovery order:

<project>/.claude/skills/
<project>/.agents/skills/
~/.claude/skills/
~/.agents/skills/

A deterministic precedence rule would avoid ambiguity. For example:

1. Project-level skills override user-level skills.
2. Claude-specific skills override generic .agents skills at the same scope.
3. On name collision, warn the user.

Minimal implementation option

Add support for a user-configurable skills path, for example:

{
  "additionalSkillsPaths": [
    "~/.agents/skills"
  ]
}

or an environment variable:

CLAUDE_CODE_SKILLS_PATHS="$HOME/.agents/skills"

Even simpler, Claude Code could scan ~/.agents/skills/ by default as an interoperable user-level convention.

Non-goals

This request is not asking Claude Code to remove or replace ~/.claude/skills/.

This request is also not asking for a new skill format. The existing SKILL.md format is fine.

The request is only about discovery paths, so that existing Agent Skills can be reused without duplication.

Why the current workarounds are insufficient

A CLAUDE.md wrapper can solve shared instructions, because imports work.

Skills cannot be solved the same way. Requiring users to copy skills into ~/.claude/skills/ defeats the purpose of reusable cross-agent skills.

Symlinks are also a poor workaround because they are fragile across platforms, visually noisy in repositories, and still force users to model their agent knowledge around one tool’s private directory layout.

Desired outcome

Claude Code should become a better citizen in multi-agent workflows by supporting a shared user-level skills location:

~/.agents/skills/

This would preserve backwards compatibility while making Claude Code easier to adopt for developers who already maintain portable agent instructions and skills.

Proposed Solution

🤦‍♂️

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_