[Feature Request] Support the standard .agents/skills/ directory for agent skills

Or .agents/skills

There is a discussion in the agent skills standard git repo on what the standard directory for skills should be and the consensus is .agents/skills/

https://github.com/agentskills/agentskills/issues/15

the consensus is .agents/skills/

Yes, please. I have symlink fatigue

Yes please.

For sure no „standard“ with „github“ in the pathname!

Please, finally .agent/skills

Looking at https://github.com/agentskills/agentskills/issues/15 Claude Code now seems to be the only major coding agent without support for the .agents/skills folder.

please no .github by default, simply using .agent/skills would be awesome! Hopefully we get it for claude code soon as well

@egils it should be .agents (plural), that's the standard.

It’s a bit awkward to define the official spec for the entire ecosystem, only to have your own product be the one that doesn't follow it. I guess reading the documentation is optional when you’re the one who wrote it?

Please at least support .agents/skills.

Any progress on supporting the .agents/skills directory? This is an incredibly frustrating state to be in for a team that uses multiple CLI tools.

I can't believe this isn't a thing, I'm in shock. I thought I screwed something up but CC really doesn't have automatic support for .agents?

I'm surprised this is an issue. I just want to track my skills using github in my code directory like all the rest of my code, not .claude or .agents. I followed 2 closed feature requests which linked to related requests to get here. This ticket under represents how many people have requested this feature.

It almost seems like they don't want to make it easy to move from one agent system to another...

I've also created an issue because Claude is unusable since my cognitive map resides in ~/.agents/, and I'd rather stop using AI than duplicate content simply because a company is vendor-only instead of being more customizable or supporting universal paths. .github wouldn't be acceptable either because it would be another vendor and not a universal path.

@Aesthermortis indeed.

Also, how many tokens are we wasting on CLAUDE.md and .claude/skills symlinks?

Please, Anthropic - support AGENTS.md and .agents/skills 🙏

+1 — concrete team use case for a configurable skills path.

Our team distributes a shared set of Claude Code skills (MCP-server operational guides, internal workflow helpers) from a single git repo that every engineer clones. The goal is simple: a git pull on that repo should update everyone's active skills, with the repo as the single source of truth — no per-machine copying or drift.

Today the only mechanism that achieves "git pull = live" for an always-on personal skill is a per-skill symlink from ~/.claude/skills/<name> into the repo's working tree, e.g.:

ln -s ~/git/<team-repo>/.claude/skills/<skill> ~/.claude/skills/<skill>

That works, but it's brittle as a distribution mechanism:

• It's per-skill and manual — every engineer re-creates a symlink for each skill, and new skills don't appear until someone adds another link.
• A symlink tracks the repo's checked-out branch working tree, so a stray git checkout silently changes everyone's skills.
• Same-named skills shadow rather than merge, so layering a thin personal skill over a team one isn't possible.
• The marketplace/plugin path copies skills into ~/.claude/plugins/cache instead of tracking the working tree, so it isn't git-pull-live either.

A first-class configurable skills source would remove all of this. Either of these would solve our case:

1. A settings key (e.g. additionalSkillsPaths: ["~/git/team-repo/.claude/skills"]) and/or a CLAUDE_-prefixed env var pointing at one or more extra skills directories, or
2. The standard .github/skills/ discovery this issue proposes, as long as it's loaded from a directory the team controls in-repo.

For reference, this has been requested several times and the dedicated variants were closed without shipping: #18621 (closed not_planned), #22902 and #12541 (closed as duplicates/locked). This issue (#16345) is the live one, so consolidating support here.

To use Claude I had to duplicate my skills by breaking SSOT, DRY, etc. This makes me upset because everything is in ~.agents/ which makes it difficult to use Claude with other AIs at the same time. This might be a bit selfish on Anthopics' part.

I do not agree with the comment above because .github would be another vendor not trackable by other AIs, which would create the same friction. AIs should use a universal route, and if they want they can have their own but I am not going to use them as a vendor only.

@Aesthermortis agree

This might be a bit selfish on Anthopics' part.

Yep, quite selfish. We're also paying for this overhead out of our own pocket- by having to maintain .claude/ duplicates/symlinks, Claude has to think about why `.agents' exists on every turn.

This is one of the reasons why I switched to Codex for my daily driver.

~/.agents/skills/ pls

.agents should be supported but setting a custom path in settings.json should also be

Workaround while Claude Code only loads .claude/skills: keep one skill source and copy it into Claude’s paths.

npx @agentplaybooks/cli@beta sync . --target=claude --apply

That writes .claude/skills (and CLAUDE.md if you have instructions). It does not make Claude Code read .agents/skills — it is a workaround until this ships. I maintain the CLI.

Workaround while Claude Code only loads .claude/skills: keep one skill source and copy it into Claude’s paths. npx @agentplaybooks/cli@beta sync . --target=claude --apply That writes .claude/skills (and CLAUDE.md if you have instructions). It does not make Claude Code read .agents/skills — it is a workaround until this ships. I maintain the CLI.

I think this is a useful workaround, but it still doesn't address the architectural problem behind this issue.

There are two different things here:

• Content synchronization: keep ".agents/skills" as the canonical source and generate provider-specific copies such as ".claude/skills".
• Native discovery: Claude Code directly discovers and loads ".agents/skills", with no provider-specific mirror required.

"agentplaybooks sync" solves the first problem. It does not solve the second.

For me, that distinction matters because a generated copy is still a physical duplicate. Calling ".claude/skills" a derived artifact may preserve a logical source of truth, but the filesystem still contains multiple representations of the same knowledge:

.agents/skills/foo/SKILL.md
.claude/skills/foo/SKILL.md
.cursor/skills/foo/SKILL.md
...

That duplication creates infrastructure that should not be necessary in the first place: synchronization, conflict detection, backups, drift handling, precedence rules, duplicated search/indexing results, and ambiguity for other tooling inspecting the repository.

In other words, the workaround does not remove the interoperability problem; it automates the maintenance of the interoperability problem.

Symlinks are slightly better in that they avoid duplicating the file contents, but they are still a compatibility hack: Claude Code only sees the skill because users manufacture a path inside Claude's vendor-specific namespace.

The clean architecture is much simpler:

.agents/skills/
↑
Claude ─┤
Codex ─┤
Other ─┘

One shared location, one physical representation, and every compatible agent discovers it natively.

So I do see value in "agentplaybooks sync" as a temporary deployment adapter for tools that do not support shared paths yet. But I would not consider synchronization of generated vendor-specific copies a solution to this issue.

Native ".agents/skills" discovery, or at minimum configurable additional skill roots, is still the actual fix.

Agree — a generated copy is still a copy. Native .agents/skills is still the fix.

The other path is your own store: load it over MCP or the API in every environment. Same source, no vendor folders. It can also carry MCP settings, and cookies if you hop machines.

https://agentplaybooks.ai — I maintain it. It does not make Claude Code read .agents/skills.

@SaschaBrunnerCH Can you update the title to match the new description?

A standardized skills directory would solve exactly the problem I keep hitting: I maintain a library of 100+ skills and had to build my own dependency-graph scan just to understand what's installed where, because discovery paths differ per tool and per project. A conventional location would make tooling like hub/orphan analysis portable across setups. From a non-English market angle, a standard directory also lowers the bar for sharing localized skill packs without each tool reinventing installation. Question: in your view, should the standard cover only discovery paths, or also minimal metadata like version and dependencies so tools can resolve compatibility before loading?

@SaschaBrunnerCH can you please update the issue title?

+1 for reading .agents/skills/ (project and ~/.agents/skills/) alongside .claude/skills/.

Our setup: the same repos are used from both Claude Code and Cursor. Cursor already discovers
skills from .agents/skills/, .cursor/skills/ and .claude/skills/, so today the only
location both tools read is .claude/skills/. That works, but it makes a Claude-specific
folder the de-facto cross-tool home, and any tool that only reads .agents/skills/ (Codex,
Gemini CLI, …) needs a symlink/junction, which is fragile on Windows and in git.

Minimal ask, no breaking change:

• also scan .agents/skills/ and ~/.agents/skills/
• on name collision, .claude/skills/ wins
• (alternative: a skillsPaths setting as proposed in #56193)

Related (all closed without a maintainer response): #6235, #31005, #50778, #56193, #66352.

Until Claude Code reads .agents/skills/ natively, this workaround keeps repository skills in .agents/skills/ only (Codex reads them there) and gives Claude Code per-skill symlinks, with nothing committed to the repositories.

A small script links each <repo>/.agents/skills/<name> (one that has a SKILL.md) as <repo>/.claude/skills/<name> -> ../../.agents/skills/<name>. It never replaces a real directory or a symlink it didn't create, prunes its own dangling links, and lists each link in the repository's local .git/info/exclude, so git status stays clean. That matters for upstream clones you don't own.

Per-skill links, rather than symlinking the whole .claude/skills directory, let a repository keep its own committed .claude/skills entries alongside them.

<details>
<summary><code>~/.agents/link-repo-skills.sh</code></summary>

#!/usr/bin/env bash
# Link <repo>/.agents/skills/<name> into <repo>/.claude/skills/<name> for Claude Code.
# Run inside a repository, or pass repository paths. Idempotent and quiet.
set -uo pipefail

link_repo() {
	local root src dest exclude name target link
	root=$(git -C "$1" rev-parse --show-toplevel 2>/dev/null) || return 0
	src="${root}/.agents/skills"
	dest="${root}/.claude/skills"
	exclude=$(git -C "$root" rev-parse --path-format=absolute --git-path info/exclude 2>/dev/null) || return 0

	# Prune dangling links this script created.
	if [[ -d "$dest" ]]; then
		for link in "$dest"/*; do
			[[ -L "$link" && ! -e "$link" ]] || continue
			[[ "$(readlink "$link")" == ../../.agents/skills/* ]] || continue
			rm -f "$link"
			name=$(basename "$link")
			[[ -f "$exclude" ]] && sed -i "\|^/\.claude/skills/${name}\$|d" "$exclude"
		done
	fi

	[[ -d "$src" ]] || return 0
	for target in "$src"/*/; do
		name=$(basename "$target")
		[[ -f "${src}/${name}/SKILL.md" ]] || continue
		link="${dest}/${name}"
		[[ -e "$link" || -L "$link" ]] && continue # never replace existing entries
		mkdir -p "$dest"
		ln -s "../../.agents/skills/${name}" "$link"
		# Committed links are tracked, so only untracked ones need excluding.
		if ! git -C "$root" ls-files --error-unmatch ".claude/skills/${name}" >/dev/null 2>&1; then
			mkdir -p "$(dirname "$exclude")"
			grep -qxF "/.claude/skills/${name}" "$exclude" 2>/dev/null ||
				printf '/.claude/skills/%s\n' "$name" >>"$exclude"
		fi
	done
}

if (($#)); then
	for repo in "$@"; do link_repo "$repo"; done
else
	link_repo "$PWD"
fi
exit 0

</details>

To run it automatically, I use a mise cd hook in a mise.toml in the directory that holds my clones (~/git/mise.toml, then mise trust ~/git/mise.toml). cd rather than enter, because enter fires only once for the whole tree, not when moving between repositories. It needs mise activate in the interactive shell.

[hooks]
cd = "~/.agents/link-repo-skills.sh"

Run the script once over existing clones (link-repo-skills.sh repo1 repo2 ...) so sessions started outside the shell, such as from an IDE, also see the skills. A session that is already running won't pick up new links until it restarts.

Re #14836: on Claude Code 2.1.286 (Linux), a fresh session in a repository did load a skill exposed this way through a symlinked .claude/skills/<name>, so per-skill symlinks work for the model; check that rather than relying on the /skills listing.

Once this issue is fixed, cleanup is removing the hook and the links, which are all listed in each repository's .git/info/exclude.

+1 for native ~/.agents/skills (user level) as well as project .agents/skills, or a setting for extra skill directories.

Data point from a user-level setup that shares one skills folder between Claude Code, goose and agy: the only workable way today is ~/.claude/skills -> ~/.agents/skills (a per-skill link breaks as soon as a new skill is created in the shared folder). That has a side effect: Claude Code writes the account-synced skills to ~/.claude/skills/synced/, which then lands inside the shared folder.

Two things would remove the need for the symlink hack:

1. native discovery of ~/.agents/skills, or a documented setting that adds extra skill directories (permissions.additionalDirectories loads no skills; --add-dir needs a flag on every launch);
2. a setting for where account-synced skills are written, so a shared folder is not polluted (today only syncClaudeAiSkills: false exists, which disables them).

Version: Claude Code 2.1.296, Linux.

Agree with @SaschaBrunnerCH that native .agents/skills/ discovery remains the ideal clean-architecture solution.

Until Anthropic adds native support, for folks managing shared skills across multiple tools (Claude Code, Codex, Cursor, etc.), we maintain an open-source, zero-dependency environment manager called agents-env that automates this bridging cleanly:

• User-level (~/.agents/skills/): Uses link-each mode to symlink individual skill directories into ~/.claude/skills/. This directly avoids the issue @mariolpantunes mentioned where symlinking the entire directory causes Claude's account-synced skills (synced/) to pollute the shared store.
• Project-level (.agents/skills/): Uses relative symlinks (link-dir or automatic fallback to link-each if physical files already exist), keeping .agents/skills/ as the single source of truth without polluting git history.
• Multi-agent & declarative: Paths and behaviors across agents are driven by a centralized declarative registry (config/agents.json), with safety fallbacks (existing directories are never overwritten; conflicts backed up to .local.bak).
• Zero dependencies: Pure POSIX/Bash script that can be run interactively or automated via curl ... | bash.

If anyone needs an immediate, non-intrusive workaround without maintaining custom one-off scripts, feel free to check it out:
https://github.com/xianghongai/agents-env

One angle mostly absent from this thread: when one folder is read by every agent on the machine, it becomes a shared integrity surface - any agent, installer, or sync feature that writes to it changes what all the others execute. The workarounds collected here (symlinks, sync scripts) add writers per skill file; they do not remove them. If Claude Code adopts .agents/skills/ natively, the piece that keeps the shared layout honest is a per-file pin - sha-256 recorded at approval, diff on change - and it needs no vendor coordination: it works per-user today. We ship that open-source (rugsnare skills scan/diff covers the Claude Code, Codex and Cursor locations among others, and .agents/skills support just landed in the current release train). The standard being cross-vendor is exactly why the integrity layer should be too.