/sync-agents-md

/sync-agents-md - Regenerate AGENTS.md from CLAUDE.md

**Synchronize AGENTS.md with current CLAUDE.md using the codex-cli-bridge skill.**

---

Usage

/sync-agents-md
/sync-agents-md --validate
/sync-agents-md --status

---

What This Command Does

**Default** (`/sync-agents-md`):

• Runs the **codex-cli-bridge** skill
• Validates environment (Codex CLI + CLAUDE.md)
• Parses CLAUDE.md and project structure
• Regenerates AGENTS.md with latest changes
• Overwrites existing AGENTS.md

**With `--validate`**:

• Validates environment only (no regeneration)
• Checks Codex CLI installation
• Checks CLAUDE.md exists
• Shows status report

**With `--status`**:

• Shows current sync status
• Displays when AGENTS.md was last updated
• Lists documented skills and agents

---

When to Use

**Run this command when**:

• ✅ CLAUDE.md has been updated
• ✅ New skills added to `.claude/skills/`
• ✅ New agents added to `.claude/agents/`
• ✅ Project structure changed
• ✅ AGENTS.md is out of sync
• ✅ Team needs latest Codex CLI documentation

**Don't need to run when**:

• ❌ Only code changes (no config changes)
• ❌ AGENTS.md already current
• ❌ Working only with Claude Code (not Codex CLI)

---

How It Works

Step 1: Environment Validation

🔍 Checking Codex CLI installation...
   ✅ Found: /path/to/codex
   Version: codex-cli 0.50.0

📄 Checking CLAUDE.md...
   ✅ Found: /project/CLAUDE.md

✅ All safety checks passed!

Step 2: Project Analysis

📖 Parsing Claude Code project...
   ✅ Found 13 skills
   ✅ Found 59 agents
   ✅ Found 58 CLAUDE.md sections

📊 Project: your-project
📁 Type: GREENFIELD_NEW

Step 3: AGENTS.md Generation

📝 Generating AGENTS.md...
   ✅ AGENTS.md generated successfully

📄 Output: /project/AGENTS.md
📊 Skills documented: 13
🤖 Agents documented: 59

---

Examples

Example 1: Basic Sync

**User**:

/sync-agents-md

**What happens**: 1. Validates Codex CLI installed 2. Checks CLAUDE.md exists 3. Parses project structure 4. Regenerates AGENTS.md 5. Success message with statistics

**Output**:

✅ SUCCESS - AGENTS.MD REGENERATED

📄 Output: AGENTS.md
📊 Skills documented: 13
🤖 Agents documented: 59

AGENTS.md is now in sync with CLAUDE.md

---

Example 2: Validate Only

**User**:

/sync-agents-md --validate

**What happens**: 1. Checks Codex CLI installation 2. Checks CLAUDE.md exists 3. Shows status report 4. **Does NOT regenerate AGENTS.md**

**Output**:

✅ VALIDATION PASSED

Environment is ready for AGENTS.md generation.

Codex CLI: v0.50.0 ✅
CLAUDE.md: Found ✅
AGENTS.md: Exists (last updated: 2025-10-30)

To regenerate: /sync-agents-md

---

Example 3: Status Check

**User**:

/sync-agents-md --status

**What happens**: Shows current project status

**Output**:

📊 SYNC STATUS

Project: claude-code-skills-factory
CLAUDE.md: ✅ Exists
AGENTS.md: ✅ Exists (in sync)
Last updated: 2025-10-30 15:52

Skills: 13 (8 functional, 5 prompt-based)
Agents: 59
Codex CLI: v0.50.0 installed

---

What Gets Updated

When you run `/sync-agents-md`, the following sections in AGENTS.md are regenerated:

✅ Updated Sections

1. **Project Overview**

• From CLAUDE.md Repository Purpose section
• Project type (GREENFIELD_NEW, etc.)
• Description

2. **Available Skills**

• All skills from `.claude/skills/`
• Skills from `~/.claude/skills/`
• Generated skills from `generated-skills/`
• With Codex CLI usage examples

3. **Project Structure**

• Current folder layout
• Key files
• Documentation references

4. **Workflow Patterns**

• Slash commands → Codex CLI equivalents
• Based on CLAUDE.md workflows section

5. **Command Reference**

• Updated command mapping table
• Claude Code ↔ Codex CLI

❌ What Doesn't Change

• Skill implementation files (unchanged)
• CLAUDE.md (source of truth)
• Project code
• Documentation files (just referenced)

---

Common Workflows

Workflow 1: After Updating CLAUDE.md

# 1. Edit CLAUDE.md
vim CLAUDE.md

# 2. Sync AGENTS.md
/sync-agents-md

# 3. Commit both files
git add CLAUDE.md AGENTS.md
git commit -m "docs: Update project configuration"

---

Workflow 2: After Adding New Skill

# 1. Create skill
/build skill
[Generated: .claude/skills/my-new-skill]

# 2. Sync AGENTS.md (documents new skill)
/sync-agents-md

# 3. Verify
cat AGENTS.md | grep "my-new-skill"

---

Workflow 3: Validate Before CI/CD

# In CI/CD pipeline

# 1. Validate environment
/sync-agents-md --validate

# 2. If valid, proceed with build
# 3. If invalid, fail pipeline

---

Integration with Other Commands

This command works seamlessly with:

`/init` - Auto-sync after initialization

/init
→ Creates CLAUDE.md
→ Auto-runs /sync-agents-md
→ Both files ready

`/update-claude` - Auto-sync after update

/update-claude
→ Updates CLAUDE.md
→ Auto-runs /sync-agents-md
→ AGENTS.md stays in sync

`/check-docs` - Validates sync status

/check-docs
→ Checks CLAUDE.md current
→ Checks AGENTS.md in sync
→ Suggests /sync-agents-md if needed

---

Troubleshooting

Error: "Codex CLI not found"

**Symptom**:

❌ Codex CLI not found!

**Solution**:

# Install Codex CLI
# Visit: https://github.com/openai/codex

# Verify
codex --version

---

Error: "CLAUDE.md not found"

**Symptom**:

⚠️  CLAUDE.md not found

**Solution**:

# Option 1: Run /init to create CLAUDE.md
/init

# Option 2: Create manually
# Then run /sync-agents-md

---

AGENTS.md Out of Date

**Symptom**: Changes to CLAUDE.md not reflected in AGENTS.md

**Solution**:

# Simply regenerate
/sync-agents-md

# AGENTS.md now updated with latest changes

---

Permission Denied

**Symptom**:

❌ Failed to write AGENTS.md: Permission denied

**Solution**:

# Check permissions
ls -l AGENTS.md

# Fix if needed
chmod 644 AGENTS.md

# Try again
/sync-agents-md

---

Best Practices