2/10/2026
Rory Eckel
Claude Opus 4.6
AI coding agents have become a daily part of my development workflow. I use Claude Code, opencode, and GitHub Copilot across different projects and contexts, and I've run into the same friction over and over: each tool has its own convention for reading project instructions. Claude Code reads CLAUDE.md. GitHub Copilot reads AGENTS.md. opencode reads AGENTS.md and supports a different skills directory.
After some experimentation, I landed on a simple pattern that keeps everything in sync without duplication: write the canonical file once, then symlink it for every tool that needs a different name. This applies to both the top-level instruction file (AGENTS.md) and the emerging Agent Skills format. In this post I'll walk through the setup, starting with the simpler AGENTS.md convention, then building up to skills and third-party skill management via git subtrees.
AGENTS.md is a simple, open format for giving AI coding agents project-specific guidance — build commands, architecture notes, conventions, and anything else an agent needs to work effectively in your repository. Think of it as a README written specifically for agents. It was released by OpenAI in mid-2025 and quickly gained adoption across the ecosystem. In late 2025, the Linux Foundation's Agentic AI Foundation (AAIF) formally adopted it alongside MCP and goose.
The format is intentionally minimal — it's just a Markdown file, no schema or tooling required. You drop an AGENTS.md at the root of your repo and agents read it as part of their system context.
The list is long and growing. As of early 2026, these tools all read AGENTS.md:
That's broad coverage. But there's a notable exception: Claude Code only reads CLAUDE.md, not AGENTS.md.
Rather than maintaining two identical files, the solution is straightforward: write AGENTS.md as the canonical source of truth, then symlink CLAUDE.md to it.
On Linux/macOS:
# Write your instructions in AGENTS.md
vim AGENTS.md
# Create a symlink for Claude Code
ln -s AGENTS.md CLAUDE.md
On Windows (cmd.exe):
REM Create a symlink for Claude Code
mklink CLAUDE.md AGENTS.md
Windows note: Git for Windows does not recognize symlinks created with ln -s in Git Bash. You must use mklink from cmd.exe instead. You'll also need Developer Mode enabled (or an elevated prompt) and git config --global core.symlinks true so that git properly tracks the symlink rather than copying the file contents.
That's it. Both files resolve to the same content. When you update AGENTS.md, Claude Code sees the changes too. Git tracks the symlink, so every collaborator and CI system gets the same setup.
I even include a note at the top of my AGENTS.md to make the relationship explicit:
# AGENTS.md
This file provides guidance to AI coding agents working with code
in this repository. It is symlinked as `CLAUDE.md` for Claude Code
compatibility.
This is a small thing, but it eliminates an entire class of drift bugs where one file gets updated and the other doesn't. One file, many consumers.
AGENTS.md is great for project-wide context, but it's a blunt instrument. Everything goes into a single file that gets loaded into the agent's system prompt on every interaction. As your instructions grow, you start wishing for something more modular — specialized instructions that only activate when relevant.
That's exactly what Agent Skills provide. A skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown instructions:
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: additional documentation
└── assets/ # Optional: templates, resources
The SKILL.md frontmatter declares when the skill should activate:
---
name: playwright-cli
description: Automates browser interactions for web testing, form filling,
screenshots, and data extraction. Use when the user needs to navigate
websites, interact with web pages, or extract information from web pages.
---
Skills use progressive disclosure to manage context efficiently (Agent Skills Specification):
name and description of each skill (~50-100 tokens each)SKILL.md is loadedThis means a skill with extensive reference documentation doesn't bloat your agent's context until it's actually relevant. The references/ directory pattern is particularly useful here — you can include detailed guides that the skill instructions point to, and the agent fetches them on demand.
This is where tool fragmentation shows up again:
.claude/skills/.agents/skills/.agents/skills/.agents/skills/ and .claude/skills/The Agent Skills specification itself is tool-agnostic — it defines the format, not the directory path. But the emerging convention for cross-compatible agents is .agents/skills/, while Claude Code has its own path.
Because GitHub Copilot scans both directories, symlinking .claude/skills to .agents/skills/ means Copilot will discover every skill twice — once from each path. In practice this is a minor issue: the duplicate metadata adds a small amount of token overhead during discovery, and Copilot handles it gracefully. For repos with a handful of skills it's an acceptable tradeoff to keep the symlink strategy simple. If you accumulate a large number of skills and the duplication becomes noticeable, you could skip the .claude/skills symlink on repos where you don't use Claude Code.
The fix is identical to the AGENTS.md approach: use .agents/skills/ as the canonical directory, then symlink .claude/skills to it.
On Linux/macOS:
# Create the canonical skills directory
mkdir -p .agents/skills
# Symlink for Claude Code
mkdir -p .claude
cd .claude && ln -s ../.agents/skills skills && cd ..
On Windows (cmd.exe):
mkdir .agents\skills
mkdir .claude
mklink /D .claude\skills ...agents\skills
Now any skill you add to .agents/skills/ is automatically available to Claude Code as well. Your directory structure looks like this:
project-root/
├── AGENTS.md # Canonical instructions
├── CLAUDE.md -> AGENTS.md # Symlink for Claude Code
├── .agents/
│ └── skills/
│ ├── blogging/ # Your custom skill
│ │ └── SKILL.md
│ └── playwright-cli/ # Third-party skill (see below)
│ ├── SKILL.md
│ └── references/
└── .claude/
└── skills -> ../.agents/skills # Symlink for Claude Code
One set of skills, accessible to every tool.
Writing your own skills is straightforward, but the real power of the Agent Skills format is sharing skills across projects and teams. Third-party skills are starting to appear — like Microsoft's playwright-cli skill for browser automation — and you'll want a clean way to pull them into your repo.
The naive approach is to copy the skill files into your .agents/skills/ directory. This works, but it has problems:
SKILL.md points to, breaking the skill's progressive disclosure chainA better approach uses git subtrees to vendor third-party code and symlinks to wire it into your skills directory:
.vendors directory.vendors into .agents/skills/Git subtrees are simpler than submodules for this use case. The vendored code becomes ordinary files in your repository — collaborators just git clone and everything works. No git submodule init, no git submodule update, no .gitmodules file. Less ceremony, fewer footguns.
Here's how it looks with the playwright-cli skill:
On Linux/macOS:
# Add the third-party repo as a subtree
git subtree add --prefix=.vendors/playwright-cli https://github.com/microsoft/playwright-cli main --squash
# Symlink just the skill into your skills directory
cd .agents/skills
ln -s ../../.vendors/playwright-cli/skills/playwright-cli playwright-cli
On Windows (cmd.exe):
git subtree add --prefix=.vendors/playwright-cli https://github.com/microsoft/playwright-cli main --squash
mklink /D .agents\skills\playwright-cli .....vendors\playwright-cli\skills\playwright-cli
To pull updates later:
git subtree pull --prefix=.vendors/playwright-cli https://github.com/microsoft/playwright-cli main --squash
Your directory structure now looks like:
project-root/
├── .vendors/
│ └── playwright-cli/ # Git subtree
│ ├── skills/
│ │ └── playwright-cli/
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── request-mocking.md
│ │ ├── running-code.md
│ │ └── session-management.md
│ └── ...
├── .agents/
│ └── skills/
│ ├── blogging/ # Your own skill
│ │ └── SKILL.md
│ └── playwright-cli -> ../../.vendors/playwright-cli/skills/playwright-cli
└── .claude/
└── skills -> ../.agents/skills
This gives you several advantages:
git clone just works. No submodule init, no submodule update, no forgetting to pass --recurse-submodules. The vendored code is just files in the repogit subtree pull --prefix=.vendors/playwright-cli <remote> main --squash to pull the latest versionreferences/, scripts/, and assets/. No risk of missing files that SKILL.md referencesThe reference files matter more than you might think. The playwright-cli skill, for example, includes reference docs for request mocking, running code, and session management. If you copy just the SKILL.md and miss these, the agent will try to read files that don't exist — silently degrading the skill's usefulness. Subtrees avoid this entirely.
Git submodules also work for this pattern. They give you exact commit pinning and keep vendored code out of your repository's object store, which matters if the third-party repo is large. But submodules add friction: every collaborator needs to remember git clone --recurse-submodules (or run git submodule init && git submodule update after cloning), CI pipelines need the same treatment, and the .gitmodules file adds another moving part. For most skill repos — which are small by nature — subtrees are the simpler choice.
Here's the complete setup from scratch.
On Linux/macOS:
# 1. Write your AGENTS.md
cat > AGENTS.md << 'EOF'
# AGENTS.md
This file provides guidance to AI coding agents working with code
in this repository. It is symlinked as `CLAUDE.md` for Claude Code
compatibility.
## Commands
...your project instructions here...
EOF
# 2. Symlink for Claude Code
ln -s AGENTS.md CLAUDE.md
# 3. Create the canonical skills directory
mkdir -p .agents/skills
# 4. Symlink for Claude Code skills
mkdir -p .claude
cd .claude && ln -s ../.agents/skills skills && cd ..
# 5. Add a third-party skill via subtree
git subtree add --prefix=.vendors/playwright-cli https://github.com/microsoft/playwright-cli main --squash
cd .agents/skills && ln -s ../../.vendors/playwright-cli/skills/playwright-cli playwright-cli && cd ../..
# 6. Commit everything
git add -A && git commit -m "Add cross-compatible agent configuration"
On Windows (cmd.exe):
REM 1. Write your AGENTS.md (use your editor of choice)
REM 2. Symlink for Claude Code
mklink CLAUDE.md AGENTS.md
REM 3. Create the canonical skills directory
mkdir .agents\skills
REM 4. Symlink for Claude Code skills
mkdir .claude
mklink /D .claude\skills ...agents\skills
REM 5. Add a third-party skill via subtree
git subtree add --prefix=.vendors/playwright-cli https://github.com/microsoft/playwright-cli main --squash
mklink /D .agents\skills\playwright-cli .....vendors\playwright-cli\skills\playwright-cli
REM 6. Commit everything
git add -A && git commit -m "Add cross-compatible agent configuration"
Reminder for Windows users: Ensure Developer Mode is enabled and run git config --global core.symlinks true before creating any symlinks. Without this, git will store symlinks as plain text files containing the target path, and the links won't work for other collaborators.
| What | Canonical Location | Symlinked For |
|---|---|---|
| Project instructions | AGENTS.md | CLAUDE.md (Claude Code) |
| Agent skills | .agents/skills/ | .claude/skills (Claude Code) |
| Third-party skills | .vendors/<repo>/ (subtree) | .agents/skills/<skill-name> |
The AI coding agent ecosystem is converging on shared standards, but we're not fully there yet. AGENTS.md has near-universal adoption, Agent Skills are gaining traction, and the gap between tool-specific conventions is shrinking. In the meantime, symlinks are the bridge.
The pattern is simple: maintain one canonical source of truth, then symlink it wherever each tool expects to find it. For third-party skills, git subtrees provide synchronization without copy-paste fragility. The result is a repository that works seamlessly with Claude Code, opencode, GitHub Copilot, and the rest of the ecosystem — with zero duplication.
It's a small amount of upfront setup that saves real time and prevents real bugs. If you're using more than one AI coding tool, it's worth the time investment.
AGENTS.md. (2025). AGENTS.md. https://agents.md/
Agent Skills. (2025). Specification. https://agentskills.io/specification
Linux Foundation. (2025, December 9). Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF), Anchored by New Project Contributions Including Model Context Protocol (MCP), goose and AGENTS.md. https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation
Microsoft. (2025). playwright-cli. https://github.com/microsoft/playwright-cli
OpenAI. (2025). OpenAI co-founds the Agentic AI Foundation under the Linux Foundation. https://openai.com/index/agentic-ai-foundation/