›_ Claude Code Issues
Claude Code Issues / #66352

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

Status Closed — not planned
Maintainer reply None cached
Workaround ✓ Mentioned in thread ↓
Activity 7 comments · opened Jun 8, 2026 · closed Jul 16, 2026

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_

View original on GitHub ↗

6 Comments

github-actions[bot] · 4 months ago

Found 3 possible duplicate issues:

  1. https://github.com/anthropics/claude-code/issues/56193
  2. https://github.com/anthropics/claude-code/issues/22902
  3. https://github.com/anthropics/claude-code/issues/53950

This issue will be automatically closed as a duplicate in 3 days.

  • If your issue is a duplicate, please close it and 👍 the existing issue instead
  • To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

kcarriedo · 4 months ago

This addresses a real friction point for anyone running more than one AI coding agent in their daily workflow — the maintenance overhead of keeping skills in sync across tool-specific directories is non-trivial, and it gets worse the moment a skill changes.

The single-source-of-truth argument is well-founded. If ~/.agents/skills/ became a canonical discovery path (analogous to how ~/.ssh/ or ~/.gitconfig serve as user-level defaults regardless of which SSH client or git frontend you're using), it would reduce both duplication and drift. Developers currently working across Claude Code, Codex CLI, and Cursor would benefit immediately.

A few things worth surfacing for the discussion:

The priority ordering question matters: when a user-level ~/.agents/skills/ skill conflicts with (or shadows) a project-level .claude/agents/ skill, which wins? Explicit project-level skills overriding user-level defaults seems like the right call — same as how project-level .gitignore overrides global — but this needs to be stated clearly in the spec.

Discovery vs. activation is worth separating: even if ~/.agents/skills/ is discovered, there's a question of whether skills there are automatically available or require explicit opt-in per project. Auto-availability could cause unexpected behavior in sandboxed/security-sensitive projects.

The duplicate issue links flagged by the bot (22902, 56193) are worth reading — if those requests were declined or deferred, it's worth understanding the stated reason before re-litigating the same territory.

Strong +1 on the underlying need. The more agents converge on the ACP / Skills spec, the more this cross-tool discovery layer pays off.

Aesthermortis · 4 months ago
Found 3 possible duplicate issues: 1. [[FEATURE] Support additional skills search paths (e.g. .agents/skills/) to enable sharing with Codex and Gemini #56193](https://github.com/anthropics/claude-code/issues/56193) 2. [[FEATURE] Custom skills directory paths via env var or settings #22902](https://github.com/anthropics/claude-code/issues/22902) 3. [[BUG] Skills installed via npx skills add (~/.agents/skills/) not recognized by Skill tool — 'Unknown skill' error #53950](https://github.com/anthropics/claude-code/issues/53950) This issue will be automatically closed as a duplicate in 3 days. If your issue is a duplicate, please close it and 👍 the existing issue instead To prevent auto-closure, add a comment or 👎 this comment 🤖 Generated with Claude Code

I do not think these are valid duplicates for auto-closure.

The suggested duplicate issues are not active canonical tracking issues:

  • #56193 is closed as not planned.
  • #22902 is closed.
  • #53950 is closed as not planned.

If one of these is the official canonical tracking issue for user-level .agents/skills/ discovery, then it should probably be reopened and marked as the canonical issue.

Otherwise, closing this issue as a duplicate of closed / not-planned issues effectively removes the request from active tracking instead of consolidating it.

This issue is specifically about the unresolved user-level single-source-of-truth problem:

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

Claude Code can already work around shared instructions through @path imports from CLAUDE.md, but there is still no equivalent clean mechanism for shared user-level skills.

That creates an asymmetric workflow:

Shared instructions: possible
Shared skills: not possible without duplication, symlinks, or Claude-specific layout changes

The requested behavior is not merely “another custom path”. The acceptance criterion is narrower:

Claude Code should support discovering user-level skills from:
~/.agents/skills/

or provide a first-class setting/env var that allows this directory to be registered without duplicating skills into ~/.claude/skills/.

Please do not auto-close this as duplicate unless there is an open canonical issue tracking this exact request.

Aesthermortis · 4 months ago
This addresses a real friction point for anyone running more than one AI coding agent in their daily workflow — the maintenance overhead of keeping skills in sync across tool-specific directories is non-trivial, and it gets worse the moment a skill changes. The single-source-of-truth argument is well-founded. If ~/.agents/skills/ became a canonical discovery path (analogous to how ~/.ssh/ or ~/.gitconfig serve as user-level defaults regardless of which SSH client or git frontend you're using), it would reduce both duplication and drift. Developers currently working across Claude Code, Codex CLI, and Cursor would benefit immediately. A few things worth surfacing for the discussion: The priority ordering question matters: when a user-level ~/.agents/skills/ skill conflicts with (or shadows) a project-level .claude/agents/ skill, which wins? Explicit project-level skills overriding user-level defaults seems like the right call — same as how project-level .gitignore overrides global — but this needs to be stated clearly in the spec. Discovery vs. activation is worth separating: even if ~/.agents/skills/ is discovered, there's a question of whether skills there are automatically available or require explicit opt-in per project. Auto-availability could cause unexpected behavior in sandboxed/security-sensitive projects. The duplicate issue links flagged by the bot (22902, 56193) are worth reading — if those requests were declined or deferred, it's worth understanding the stated reason before re-litigating the same territory. Strong +1 on the underlying need. The more agents converge on the ACP / Skills spec, the more this cross-tool discovery layer pays off.

Thanks, I agree with the discovery vs activation distinction.

One clarification: I do not think .claude/skills/ should be treated as the conceptual center of the model.

For multi-agent workflows, the canonical user-level location should be vendor-neutral:

~/.agents/skills/

Claude-specific paths such as:

~/.claude/skills/

can remain supported for backwards compatibility, but they should not be required for portable skills.

The important distinction for me is:

Vendor-specific path:
  ~/.claude/skills/

Portable user-level path:
  ~/.agents/skills/

The issue is not that Claude needs yet another private folder. The issue is that Claude Code currently requires skills to live in a Claude-specific layout, while shared instructions can already be imported from a neutral location via @path.

That creates an asymmetric workflow:

Shared instructions:
  possible

Shared skills:
  not possible cleanly

For users maintaining a cross-agent knowledge base, ~/.agents/skills/ should be a first-class discovery path, not a workaround and not a duplicate of ~/.claude/skills/.

On activation, I agree that projects may need control. Discovery does not have to mean unconditional activation in every workspace. A reasonable model could support discovery globally, while allowing project-level allow/deny policy or explicit activation rules.

github-actions[bot] · 3 months ago

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

Aesthermortis · 3 months ago

As always, Claude's stuck in vendor-only mode. That's why it's better to switch to OpenAI.

Showing cached comments. Read the full discussion on GitHub ↗

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

Browse all Claude Code issue topics →