Cross-Tool Compatibility¶

Samuel works with any AI coding assistant through the AGENTS.md standard.

Supported Tools¶

Setup Options¶

Option 1: Symlink (Recommended)¶

Creates a link so both files are always identical:

ln -s CLAUDE.md AGENTS.md

New-Item -ItemType SymbolicLink -Path AGENTS.md -Target CLAUDE.md

Pros:

• Zero maintenance
• Always in sync
• No duplication

Cons:

• Windows requires admin privileges
• Some tools may not follow symlinks

Option 2: Generate Standalone¶

Create a separate AGENTS.md with operations-only content:

@.claude/skills/generate-agents-md/SKILL.md

Pros:

• Works everywhere
• Can customize per-tool
• Simpler content for some tools

Cons:

• Manual updates needed
• Potential drift from CLAUDE.md

Option 3: Copy¶

Simply copy CLAUDE.md:

cp CLAUDE.md AGENTS.md

Pros:

• Works everywhere
• Simple

Cons:

• Manual sync needed
• Easy to forget updates

Tool-Specific Setup¶

Claude Code¶

Claude Code reads CLAUDE.md automatically. No additional setup needed.

your-project/
├── CLAUDE.md       ← Loaded automatically
└── .claude/         ← Language guides, workflows

Cursor¶

Cursor reads .cursorrules or AGENTS.md:

Option A: Symlink CLAUDE.md

ln -s CLAUDE.md .cursorrules
# or
ln -s CLAUDE.md AGENTS.md

Option B: Create .cursorrules

@.claude/skills/generate-agents-md/SKILL.md

Generate .cursorrules for Cursor

GitHub Copilot¶

Copilot can read AGENTS.md for context:

ln -s CLAUDE.md AGENTS.md

OpenAI Codex / ChatGPT¶

Use AGENTS.md:

ln -s CLAUDE.md AGENTS.md

Multi-Tool Teams¶

When team members use different tools:

Recommended Setup¶

1. Keep CLAUDE.md as source of truth
2. Create symlink: ln -s CLAUDE.md AGENTS.md
3. Add both to git

git add CLAUDE.md AGENTS.md
git commit -m "chore: add AI coding instructions"

Team Workflow¶

1. Edit only CLAUDE.md - Never edit AGENTS.md directly
2. Symlink stays updated - Changes propagate automatically
3. All tools see same rules - Consistent behavior

For Windows Users¶

If symlinks don't work:

@.claude/skills/generate-agents-md/SKILL.md

Generate standalone AGENTS.md

Add to .gitattributes:

AGENTS.md merge=ours

This prevents merge conflicts when regenerating.

File Comparison¶

CLAUDE.md (Full - ~500 lines)¶

Contains everything:

• Operations (commands)
• Boundaries (protected files)
• Quick Reference
• Core Guardrails (35+ rules)
• 4D Methodology
• SDLC stages
• Context System
• Anti-Patterns

AGENTS.md (Operations - ~200 lines)¶

Contains essentials:

• Operations (commands)
• Boundaries (protected files)
• Quick Reference

Maintaining Sync¶

With Symlink¶

Automatic - no action needed.

With Standalone AGENTS.md¶

Add to your workflow:

1. PR Checklist:

2. If CLAUDE.md changed, regenerate AGENTS.md

3. CI Check (optional):

   - name: Check AGENTS.md is current
     run: |
       # Generate expected AGENTS.md
       # Compare with committed version
       # Fail if different
   

4. Pre-commit hook (optional):

   #!/bin/bash
   if git diff --cached --name-only | grep -q "CLAUDE.md"; then
     echo "CLAUDE.md changed - regenerate AGENTS.md"
   fi
   

Troubleshooting¶

Symlink Not Working¶

Windows: Requires admin privileges or Developer Mode enabled.

Git: Ensure core.symlinks=true:

git config core.symlinks true

Tool Ignoring Instructions¶

1. Check file location (must be in project root)
2. Check file name (exact match required)
3. Restart the tool
4. Explicitly reference: "Follow instructions in CLAUDE.md"

Different Behavior Between Tools¶

Each tool interprets instructions differently. For consistent results:

1. Keep rules specific and testable
2. Use guardrails that can be verified
3. Test with each tool your team uses

Best Practices¶

Do¶

• Use symlink when possible
• Keep CLAUDE.md as source of truth
• Test with all tools your team uses
• Document which tools are supported

Don't¶

• Edit AGENTS.md directly (edit CLAUDE.md)
• Maintain two different instruction sets
• Assume all tools behave identically
• Ignore tool-specific limitations

Related¶