claude-code - 💡(How to fix) Fix Feature Request: Native support for AGENTS.md and .agents/skills/ as portable alternatives to CLAUDE.md and .claude/skills/ [2 comments, 2 participants]

Summary

Claude Code is the only major agent CLI that doesn't recognize the emerging community standard of AGENTS.md + .agents/skills/. Cursor, Aider, Continue.dev, Codex, and others converge on this layout for portability. Supporting it natively would let a single repo work across every agent tool without maintaining parallel instruction files.

Proposal

1. AGENTS.md dual-read: when Claude Code loads project instructions, check for AGENTS.md in the same directories it currently checks CLAUDE.md. If both exist, concatenate AGENTS.md content first, then CLAUDE.md content (explicit per-project override). If only one exists, use it.

2. .agents/skills/ dual-discovery: alongside ~/.claude/skills/ and ./.claude/skills/, also scan ~/.agents/skills/ and ./.agents/skills/ for SKILL.md files. Merge into the skill registry. On name collision, prefer .claude/ (Claude-specific takes precedence).

3. .agents/hooks/, .agents/commands/: optional follow-on for hook and slash-command portability. Lower priority than steps 1 and 2.

4. Zero breaking changes: projects with only CLAUDE.md see no behavior change. Projects with AGENTS.md only get it honored automatically. Projects with both get deterministic precedence rules.

Prior-art evidence of demand (all 5 currently open, unanswered)

• #6235 (3,639 thumbs-up): "Feature Request: Support AGENTS.md"
• #31005 (117 thumbs-up): "Support for AGENTS.md and .agents/skills/, the community has been asking since April"
• #12925 (96 thumbs-up): "Linear Integration: Assign issues to Claude Code to trigger cloud agent sessions" (adjacent; portability matters)
• #10238 (133 thumbs-up): "Add support for subdirectories in skills" (skill-discovery adjacency)
• #25045 (58 thumbs-up): "allow skills to programmatically rename sessions" (portability adjacent)

Why this is not a duplicate

• #6235 is the original request but has no formal proposal. Anthropic has not responded in the issue thread.
• #31005 asks for both AGENTS.md and .agents/skills/ but is a follow-up ask, not a consolidated design.
• No existing issue proposes the specific dual-read + dual-discovery + precedence model above.
• This FR consolidates the five related asks into one actionable spec that Anthropic can implement or explicitly decline with rationale.

Use case (specific, not hypothetical)

A user maintains a multi-agent workflow: Claude Code for implementation, Cursor for pair-programming refactors, Aider for batch refactors, Codex for one-shot script generation. Every project currently needs:

• CLAUDE.md (Claude Code)
• AGENTS.md (Cursor / Aider / Codex)

These files contain 80%+ overlapping content. When the user updates one, they must remember to mirror to the other. This is a known friction point across the community, and the 3,987 thumbs-up on #6235 alone is evidence that the scale is not niche.

Adding AGENTS.md dual-read in Claude Code would eliminate the duplication for projects that opt in, while preserving full backward compatibility for projects that use only CLAUDE.md.

Acceptance criteria

• AGENTS.md in a project root is read alongside CLAUDE.md with documented precedence
• .agents/skills/ is discovered alongside .claude/skills/ with documented precedence
• Docs page at code.claude.com/docs/en/memory updated to cover both paths
• A simple example repo demonstrates running the same skill on Claude Code AND Cursor without duplication
• Closing notes on #6235 and #31005 reference this FR