Support for AGENTS.md and .agents/skills/, the community has been asking since August 2025

The fragmentation is brutal. I have 12 agent definitions that need to live somewhere standard, and right now it's all locked into .claude/ with no portability.

For now I keep everything in a single CLAUDE.md with per-agent sections + a scratchpad for session state. At least it's one file to maintain instead of symlink hacks. Would switch to AGENTS.md in a heartbeat if it were supported.

https://github.com/Koroqe/claude-code-sdlc — current workaround structure.

We use AGENTS.md extensively at MEEET World (707 agents coordinated through a shared API + skill system). Happy to share our patterns if useful for this feature.

Our agent architecture

While waiting for official AGENTS.md support, Claude Code's existing features already cover most of the use cases described here. Here's how:

Hierarchical CLAUDE.md works as agent definition files. Claude Code loads them in cascade:

~/.claude/CLAUDE.md          # global rules (all projects)
~/CLAUDE.md                  # home-level rules
./CLAUDE.md                  # project-level rules
./.claude/CLAUDE.md          # project-specific (gitignored)

Each level can define different "agent personas" — behavioral constraints, tool preferences, output formats. The cascade means you define shared rules once at the top and override per-project.

.claude/commands/ is the skills directory. Each .md file becomes a slash command:

~/.claude/commands/review.md     # /review — available everywhere
./.claude/commands/deploy.md     # /deploy — project-specific

Inside each command file, you define the agent's behavior for that task — what tools to use, what checks to run, what format to output. This is functionally equivalent to .agents/skills/.

Practical structure that works today:

project/
  CLAUDE.md                    # Agent definition: role, constraints, judgment rules
  .claude/
    commands/
      plan.md                  # /plan — architecture planning agent behavior
      review.md                # /review — code review agent behavior
      deploy.md                # /deploy — deployment agent behavior
  tasks/
    todo.md                    # Task queue for autonomous execution

The CLAUDE.md hierarchy + commands directory gives you per-agent behavioral definitions, per-project skill libraries, and shared rules — without needing a separate AGENTS.md spec.

What's genuinely missing vs. AGENTS.md: cross-tool portability (same definitions working in Cursor, Copilot, etc.) and a standardized discovery mechanism. Those are real gaps that only official support would solve. But for "define agent behaviors and skills in Claude Code," the building blocks are already there.

.agents/skills worked on version 1.0117.

why did you remove it, after all, you have pioneered it and after nudging claude still runs it.

<img width="1782" height="1024" alt="Image" src="https://github.com/user-attachments/assets/968a29e8-7803-4cca-a2f7-230fa8b718f8" />

tested on v2.1.100: .agents/skills/ still returns "Unknown skill."

per-skill symlinks from .claude/skills/ to .agents/skills/ work though, so the discovery path is the only thing missing

any updates?

It's pretty obvious that this is an intentional marketing/growth hack strategy.

So only voting with your wallet will change their mind.

We treat claude as the exception, and it just gets symlinks and we adopt none of their features other than .agents/skills/**/* and .agents/commands/**/*.md

Adding to the workaround stack since this thread is the de facto reference until Anthropic responds.

One pattern that hasn't come up: @AGENTS.md as a CLAUDE.md import works in current Claude Code:

@AGENTS.md

Tradeoff vs the approaches already posted:

• vs per-skill symlinks (@jcurbelo): no filesystem-permission / Windows edge cases
• vs pr_guard sync (@kingpanther13): single source of truth, no sync to enforce
• vs CLAUDE.md hierarchy + .claude/commands/ (@yurukusa): keeps AGENTS.md as the canonical filename for cross-tool consumers

Caveats from our usage: /compact can drop imported content mid-session (separate known issue), and Claude-native affordances (skills auto-trigger, slash commands) still need .claude/ siblings, they don't fire from inside an imported file.

For repos that also have to feed Cursor / Windsurf / Copilot / Gemini from the same source, there's a free fan-out converter at https://tomevault.io/studio (disclosure: I run it). Doesn't fix the underlying issue, just handles the multi-loader case for the formats Claude Code doesn't read natively today.

quick fix on mac

ln -s ~/.agents/skills ~/.claude/skills

With symlinks as a workaround, it's not required to link per file. Linking the whole folder works properly on my side. It's also consistent when adding a new skill.

ln -s ../.claude/skills .agents/skills

Strongly agree this is the right ask, and the fact that Anthropic authored both MCP and the Skills spec makes the gap even more frustrating. While we wait for native AGENTS.md and .agents/skills/, the workaround I settled on is to keep one source-of-truth and compile it down to both .claude/ (skills + CLAUDE.md) and the AGENTS.md / .agents/skills/ layouts the other tools expect — I use xcaffold (https://github.com/saero-ai/xcaffold) for that. It’s not a substitute for first-class support, but it stops the dual-maintenance bleeding so we can stay on Claude Code without locking the rest of the team out. Happy to see this issue stay open until proper support lands.

I agree that Anthropic is leading the era of agentic development. Defining and being the standard of the chaotic era is the right move.

The GitHub Actions bot just closed a newer duplicate: #56193, and here are all of the _direct duplicates_ of this issue, which are all closed:

Issue | Status | Title
-- | -- | --
#56193 | closed | Support additional skills search paths (e.g. .agents/skills/) to enable sharing with Codex and Gemini
#20820 | closed | Reserve skills/ for user-managed skills, relocate internal skills to system/ (the .agents/skills/ symlink workaround)
#48496 | closed | Allow configuring default paths for skills, rules, agents, and worktrees in settings.json
#48487 | closed | Allow configuring default paths for skills, rules, agents, and worktrees in settings.json (near-identical twin of #48496)
#33957 | closed | Support configurable skills directory path
#22902 | closed | Custom skills directory paths via env var or settings
#18621 | closed | Add option to configure skills path

I agree that Anthropic is leading the era of agentic development.

That's highly debatable lol.

I think you'll find that there's not much going on at anthropic other than vibeslop and copying anything Mario or Nicobailon does.

Any updates on this?

This has become more and more challenging as skills and agents and everything in the .agents folder grows. Resetting links after every edit isn't a good user experience, and this would be a significant quality of life improvement.

Kimi K3 also uses .agents/skills

I've just flipped my entire symlink architecture from .claude/skills as triforce to having claude be the special snowflake symlinking to .agents/skills.

This is a problem for applications trying to deliver their own skills. In my app, Contextify, I want to deliver skills for Claude Code and Codex. Previously, I've just written to each .[ai-agent]/skills but if I want to support all agents, I now have to write logic to determine if the user is centralized on either.

If I blindly symlink .claude/skills to .agent/skills it may pull some other unexpected tools into .claude's environment.

I want to avoid reading and writing and mucking with a person's environment as much as possible. This could all be solved by Claude Code supporting the fallback directory of .agent

Please reconsider making .agents the fallback to .claude.

While native AGENTS.md / .agents/skills/ support is the right long-term fix, teams running Claude Code alongside Codex/Cursor still have to keep multiple layouts in sync today.

I open-sourced a small workaround for that: agentpkg — one manifest installs skills/rules/MCP configs into each agent's native paths, with a SHA-256 lockfile so installs can be verified in CI (useful after the recent skill/MCP supply-chain incidents).

Happy to retire the sync half of it the day this issue ships. The lockfile/verify half stays useful either way.

I open-sourced a small workaround for that: agentpkg — one manifest installs skills/rules/MCP configs into each agent's native paths, with a SHA-256 lockfile so installs can be verified in CI (useful after the recent skill/MCP supply-chain incidents).

the npx skills already does the lockfile (both globally and locally per-repo), and it's a major thing from Vercel.
check the https://skills.sh too