Sync Agent Context

Command: /sync-agent-context

Purpose: Permanently merge all AGENTS.md files in the project into CLAUDE.md under a dedicated section, ensuring agent-specific instructions are always loaded alongside project context.

What This Command Does

1. Finds all AGENTS.md files in the current project directory (searches recursively)
2. Reads each AGENTS.md file and extracts its content
3. Updates CLAUDE.md by adding or updating the "## Agent-Specific Instructions" section
4. Maintains both files: Keeps original AGENTS.md files as the source of truth
5. Creates backup: Saves a backup of CLAUDE.md before making changes

Execution Steps

Step 1: Find All AGENTS.md Files

Search the current project for all files named AGENTS.md:

find . -name "AGENTS.md" -type f

Expected output:

./AGENTS.md
./subproject/AGENTS.md

Step 2: Read Each AGENTS.md File

For each found file, read its full content using the Read tool:

File: ./AGENTS.md
Content: [full content of AGENTS.md]

File: ./subproject/AGENTS.md
Content: [full content of subproject AGENTS.md]

Step 3: Check if CLAUDE.md Exists

if [ -f "./CLAUDE.md" ]; then
    echo "CLAUDE.md found - will update"
else
    echo "CLAUDE.md not found - will create new file"
fi

Step 4: Create Backup of CLAUDE.md

cp CLAUDE.md CLAUDE.md.backup.$(date +%Y%m%d-%H%M%S)

Example: CLAUDE.md.backup.20251023-143022

Step 5: Merge AGENTS.md into CLAUDE.md

Add or update the following section in CLAUDE.md:

---

## Agent-Specific Instructions

<!-- AUTO-SYNCED from AGENTS.md files - Last updated: 2025-10-23 14:30:22 -->
<!-- Source files: ./AGENTS.md, ./subproject/AGENTS.md -->

### Root Directory Agent Rules (./AGENTS.md)

[Content from ./AGENTS.md]

### Subproject Agent Rules (./subproject/AGENTS.md)

[Content from ./subproject/AGENTS.md]

---

Step 6: Verify and Report

✅ Agent Context Sync Complete!

📋 Summary:
- Found 2 AGENTS.md files
- Created backup: CLAUDE.md.backup.20251023-143022
- Updated CLAUDE.md with agent-specific instructions

📂 Synced files:
1. ./AGENTS.md → CLAUDE.md (Section: Root Directory Agent Rules)
2. ./subproject/AGENTS.md → CLAUDE.md (Section: Subproject Agent Rules)

⚠️ Note: Original AGENTS.md files remain unchanged (source of truth)

💡 Next time you start Claude Code, both CLAUDE.md and AGENTS.md will be loaded automatically.

When to Use This Command

Use /sync-agent-context when:

1. Initial setup: First time using agent-specific instructions
2. AGENTS.md not auto-loading: If the proactive skill isn't triggering
3. Permanent merge desired: Want agent rules always in CLAUDE.md
4. Multiple AGENTS.md files: Have agent rules across different directories
5. Manual control preferred: Want explicit control over when rules are merged

Don't use this command if:

• Automatic loading is working fine (skill handles it)
• You want AGENTS.md and CLAUDE.md to remain separate
• You frequently update AGENTS.md (would require re-running sync)

Merge Strategy

If "Agent-Specific Instructions" section exists in CLAUDE.md:

Replace the existing section with updated content from all AGENTS.md files.

## Agent-Specific Instructions
<!-- OLD CONTENT - WILL BE REPLACED -->

↓↓↓ BECOMES ↓↓↓

## Agent-Specific Instructions
<!-- NEW CONTENT FROM AGENTS.MD FILES -->

If "Agent-Specific Instructions" section doesn't exist:

Append new section to the end of CLAUDE.md.

[Existing CLAUDE.md content]

---

## Agent-Specific Instructions
<!-- NEW SECTION ADDED -->
[Content from AGENTS.md files]

Conflict Resolution

If both CLAUDE.md and AGENTS.md have conflicting rules:

The sync command will:

1. Keep original CLAUDE.md content intact
2. Add AGENTS.md content in dedicated section
3. Document in the header: "In case of conflicts, Agent-Specific Instructions take precedence"

Example merged output:

# CLAUDE.md

## General Project Instructions
- Use TypeScript for all code (from original CLAUDE.md)

---

## Agent-Specific Instructions
<!-- In case of conflicts, these rules take precedence for agent workflows -->

- Use JavaScript for agent-generated code (from AGENTS.md)