This post will age like sour milk, because Anthropic will eventually adopt the company-agnostic AGENTS.md standard.
For those that do not know, AGENTS.md is like robots.txt, but for providing plain text context to any AI agent working in your codebase.
It’s very stupid really. It’s not even worthy of being called a “standard”. The only rule is the name of the file.
Anthropic champions CLAUDE.md, named after their own agent Claude. Insisting on that stupid convention is like Google forcing websites to use googlebot.txt instead of robots.txt, or Microsoft clippy.txt.
Anyway, since this post will become irrelevant very soon, here are some AI-generated instructions on how to migrate your CLAUDE.md files to AGENTS.md.
Why Migrate?
- Open Standard: AGENTS.md is an open standard that works with multiple AI systems
- Interoperability: Maintains backward compatibility through symlinks
- Future-Proof: Not tied to a specific AI platform or tool
- Consistency: Standardizes agent instructions across the codebase
Actual Migration Commands Used
Step 1: Rename Files
The following commands were used to rename existing CLAUDE.md files to AGENTS.md:
# Find all CLAUDE.md files and rename them to AGENTS.md
find . -name "CLAUDE.md" -type f -exec sh -c 'mv "$1" "${1%CLAUDE.md}AGENTS.md"' _ {} \;
Step 2: Update Content
Replace Claude-specific references with agent-agnostic language:
# Update file headers in all AGENTS.md files
find . -name "AGENTS.md" -type f -exec sed -i '' 's/This file provides guidance to Claude Code (claude.ai\/code)/This file provides guidance to AI agents/g' {} \;
Step 3: Update .gitignore
Add these lines to .gitignore to ignore symlinked CLAUDE.md files:
# Add to .gitignore
cat >> .gitignore << 'EOF'
# CLAUDE.md files (automatically generated from AGENTS.md via symlinks)
CLAUDE.md
**/CLAUDE.md
EOF
Step 4: Create Symlink Setup Script
Create utils/setup-claude-symlinks.sh with the following content:
#!/bin/bash
# Script to create CLAUDE.md symlinks to AGENTS.md files
# This allows CLAUDE.md files to exist locally without being committed to git
set -e
echo "Setting up CLAUDE.md symlinks..."
# Change to repository root
cd "$(git rev-parse --show-toplevel)"
# Find all AGENTS.md files and create corresponding CLAUDE.md symlinks
git ls-files | grep "AGENTS\.md$" | while read -r file; do
dir=$(dirname "$file")
claude_file="${file/AGENTS.md/CLAUDE.md}"
# Remove existing CLAUDE.md file/link if it exists
if [ -e "$claude_file" ] || [ -L "$claude_file" ]; then
rm "$claude_file"
echo "Removed existing $claude_file"
fi
# Create symlink
if [ "$dir" = "." ]; then
ln -s "AGENTS.md" "CLAUDE.md"
echo "Created symlink: CLAUDE.md -> AGENTS.md"
else
ln -s "AGENTS.md" "$claude_file"
echo "Created symlink: $claude_file -> AGENTS.md"
fi
done
echo ""
echo "✓ CLAUDE.md symlinks setup complete!"
echo " - CLAUDE.md files are ignored by git"
echo " - They will automatically stay in sync with AGENTS.md files"
echo " - Run this script again if you add new AGENTS.md files"
Step 5: Run Symlink Setup
Make the script executable and run it:
chmod +x utils/setup-claude-symlinks.sh
./utils/setup-claude-symlinks.sh
Top-Level AGENTS.md Note
Add this note to the main AGENTS.md file:
**Note**: This project uses the open AGENTS.md standard. These files are symlinked to CLAUDE.md files in the same directory for interoperability with Claude Code. Any agent instructions or memory features should be saved to AGENTS.md files instead of CLAUDE.md files.
Directory Structure After Migration
project/
├── AGENTS.md # Primary agent instructions
├── CLAUDE.md # Symlink to AGENTS.md (git ignored)
├── utils/
│ └── setup-claude-symlinks.sh # Symlink setup script
├── backend/
│ ├── AGENTS.md # Backend-specific instructions
│ └── CLAUDE.md # Symlink to AGENTS.md (git ignored)
└── apps/
├── AGENTS.md # Frontend-specific instructions
├── CLAUDE.md # Symlink to AGENTS.md (git ignored)
└── web/
├── AGENTS.md # App-specific instructions
└── CLAUDE.md # Symlink to AGENTS.md (git ignored)
Content Update Examples
Before Migration
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
After Migration
# AGENTS.md
This file provides guidance to AI agents when working with code in this repository.
Verification Commands
Verify the migration worked correctly:
# Check all AGENTS.md files exist
find . -name "AGENTS.md" -type f
# Verify symlinks are created
find . -name "CLAUDE.md" -type l
# Check symlinks point to correct files
find . -name "CLAUDE.md" -type l -exec ls -la {} \;
# Verify content is agent-agnostic
grep -r "Claude Code (claude.ai/code)" . --include="*.md" | grep AGENTS.md
Maintenance
Adding New AGENTS.md Files
When you add new AGENTS.md files, run the symlink setup script:
./utils/setup-claude-symlinks.sh
Checking Symlink Status
# List all symlinks
find . -name "CLAUDE.md" -type l -exec ls -la {} \;
# Check for broken symlinks
find . -name "CLAUDE.md" -type l ! -exec test -e {} \; -print
Benefits of This Approach
- Backward Compatibility: Existing tools expecting CLAUDE.md files continue to work
- Git Clean: CLAUDE.md files are not tracked in version control
- Automatic Sync: Symlinks ensure CLAUDE.md always matches AGENTS.md
- Easy Maintenance: Single script handles all symlink creation/updates
- Open Standard: Future-proof with the open AGENTS.md standard
Troubleshooting
Broken Symlinks
# Remove all CLAUDE.md symlinks and recreate
find . -name "CLAUDE.md" -type l -delete
./utils/setup-claude-symlinks.sh
Permission Issues
# Make sure script is executable
chmod +x utils/setup-claude-symlinks.sh
This migration preserves all existing functionality while adopting the open AGENTS.md standard for better interoperability.
.png)
3 hours ago
1
