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
.claude/commands/sync-agents-md.mdWhat 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.mdafter editingCLAUDE.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.mdbefore a commit
Example prompts for the agent
- Run
/sync-agents-md; I editedCLAUDE.mdand 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.mdCall it with /sync-agents-md. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/sync-agents-md.mdCall it with /prompts:sync-agents-md. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/sync-agents-md.prompt.mdManually: put the files in place
.gemini/commands/sync-agents-md.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
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