Skip to main content
command CX Codex

sync-agents-md — Claude Code command: what it does, how to install

sync-agents-md rebuilds AGENTS.md from CLAUDE.md so the Claude CLI docs in a repo follow the project config. Handy after config edits or a new skill.

MIT ★ 907 updated 2025-11-12

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/sync-agents-md.md
Open on GitHub

What sync-agents-md does

The command drives the Claude-cli-bridge skill. It first confirms that Claude CLI is on the machine and that CLAUDE.md sits in the project, then reads the layout: skills under .claude/skills/, subagents under .claude/agents/, sections of the config file. AGENTS.md is then written from scratch, replacing the old one.

What lands in the new file: a project overview, the skill list with Claude CLI examples, the folder tree, workflow patterns, and a table mapping Claude slash commands to their Claude CLI counterparts. Two flags change the behaviour. --validate runs the environment checks only and writes nothing; --status reports when the file was last refreshed and which skills and agents it documents.

Codex CLI is a hard requirement: when it is missing the command stops at the first check and AGENTS.md stays as it was. Hand edits to AGENTS.md do not survive, because every run overwrites it. Keep changes in CLAUDE.md.

What it helps with

  • Refresh AGENTS.md after editing CLAUDE.md
  • Document a newly added skill for Claude CLI
  • Check the environment without rewriting the file
  • See when the two files last matched
  • Catch a stale AGENTS.md before a commit

Example prompts for the agent

  • Run /sync-agents-md; I edited CLAUDE.md and want the Claude docs updated.
  • Check the setup first with /sync-agents-md --validate.
  • Show me the sync status with /sync-agents-md --status.

How to install sync-agents-md

Manually: put the files in place

.claude/commands/sync-agents-md.md

Call it with /sync-agents-md. For all projects use ~/.claude/commands/

Questions about sync-agents-md

How do I install sync-agents-md in Claude Code?

Put the command file at .claude/commands/sync-agents-md.md inside your project. The /sync-agents-md call becomes available right after that.

What does sync-agents-md do?

It rewrites AGENTS.md from CLAUDE.md, covering the project overview, skills, folder layout, workflows and the command mapping table.

Why did the command stop before writing the file?

The first step needs Claude CLI installed and CLAUDE.md present in the project. Run /sync-agents-md --validate to see which of the two is missing without touching AGENTS.md.

Source text

sync-agents-md.md · MIT
# /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**:
```bash
# 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**:
```bash
# Check permissions
ls -l AGENTS.md

# Fix if needed
chmod 644 AGENTS.md

# Try again
/sync-agents-md
```

---

## Best Practices

### 1. Keep CLAUDE.md as Source of Truth

✅ **DO**:
- Edit CLAUDE.md for all configuration changes
- Run `/sync-agents-md` after editing
- Commit both CLAUDE.md and AGENTS.md together

❌ **DON'T**:
- Edit AGENTS.md directly (will be overwritten)
- Forget to sync after CLAUDE.md changes
- Commit CLAUDE.md without regenerating AGENTS.md

---

### 2. Sync After Major Changes

**Always sync when**:
- Adding/removing skills
- Updating project description
- Changing project type
- Modifying workflows
- Adding agents

---

### 3. Validate in CI/CD

```yaml
# .github/workflows/validate-docs.yml
name: Validate Documentation

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Validate AGENTS.md sync
        run: |
          # Regenerate AGENTS.md
          python generated-skills/codex-cli-bridge/bridge.py

          # Check if changed
          git diff --exit-code AGENTS.md || {
            echo "❌ AGENTS.md is out of sync with CLAUDE.md"
            echo "Run: /sync-agents-md"
            exit 1
          }
```

---

### 4. Use in Pre-commit Hook

```bash
# .git/hooks/pre-commit
#!/bin/bash

# Check if CLAUDE.md was modified
if git diff --cached --name-only | grep -q "CLAUDE.md"; then
  echo "CLAUDE.md changed, regenerating AGENTS.md..."
  /sync-agents-md
  git add AGENTS.md
  echo "✅ AGENTS.md updated and staged"
fi
```

---

## Technical Details

**Command Type**: Slash command
**Skill Used**: codex-cli-bridge
**Python Script**: `generated-skills/codex-cli-bridge/bridge.py`
**Output**: AGENTS.md in project root
**Approach**: Reference-based (no file duplication)
**Sync Direction**: One-way (CLAUDE.md → AGENTS.md)

---

## Related Commands

| Command | Purpose |
|---------|---------|
| `/init` | Initialize project with CLAUDE.md (auto-syncs AGENTS.md) |
| `/update-claude` | Update CLAUDE.md from code changes (auto-syncs AGENTS.md) |
| `/check-docs` | Validate all documentation is current |
| `/sync-agents-md` | Manually regenerate AGENTS.md |

---

## See Also

- **SKILL.md**: codex-cli-bridge skill documentation
- **HOW_TO_USE.md**: Comprehensive usage guide
- **AGENTS.md**: Example output (this repository)
- **CLAUDE.md**: Source configuration file

---

**Version**: 1.0.0
**Last Updated**: 2025-10-30
**Maintained For**: Cross-tool team collaboration (Claude Code ↔ Codex CLI)

---

**Keep your documentation in sync!** 🔄

© alirezarezvani · MIT · alirezarezvani/claude-code-skill-factory

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set36

The whole set →
sync-todos-to-github sync-todos-to-github turns a TodoWrite task list into a GitHub planning issue and starts follow-up automation. Useful for sprint plans and saved work checkpoints. CX Codex +1 ★ 907repo stars validate-output validate-output runs a checklist over a freshly generated skill, prompt, subagent or hook and names what needs fixing. A skill that passes gets zipped. CX Codex +1 ★ 907repo stars agent-factory agent-factory generates production-ready Claude Code sub-agent files with YAML frontmatter, tool permissions, and MCP server integrations. CX Codex +1 ★ 907repo stars content-trend-researcher content-trend-researcher studies topic signals and audience intent across content platforms, then builds article outlines. Use it to validate ideas and spot underserved subjects. CX Codex +1 ★ 907repo stars skills-guide Guides you through a quick questionnaire to build and package multi-file Claude skills with YAML frontmatter, Python code, and docs. CX Codex ★ 907repo stars codex-cli-bridge The codex-cli-bridge skill connects Claude Code projects with Codex CLI by creating AGENTS.md from CLAUDE.md and providing helpers to run Codex tasks. Use it when both tools are part of your workflow. CX Codex +1 ★ 907repo stars prompts-guide prompts-guide — a subagent that helps build prompts for any model via prompt-factory skill: pick from 69 presets or build a custom one through 5–7 questions. CX Codex ★ 907repo stars codex-exec codex-exec runs Codex CLI tasks directly inside Claude Code sessions. It applies proper sandboxing modes, reasoning flags, and selects between GPT-5 models. CX Codex +1 ★ 907repo stars

Project sponsors

Companies that keep this analytics open