sync-agents-md — команда для Claude Code: что делает и как установить
Команда sync-agents-md перегенерирует AGENTS.md из CLAUDE.md, чтобы документация для Codex CLI не отставала от конфигурации проекта. Полезно после правок конфига или добавления скилла.
MIT ★ 907 обновлён 2025-11-12
.claude/commands/sync-agents-md.mdЧто делает sync-agents-md
Команда перегенерирует AGENTS.md из CLAUDE.md через скилл codex-cli-bridge. Сначала проверяет, что Codex CLI установлен и файл CLAUDE.md лежит в проекте, потом разбирает структуру: сколько скиллов в .claude/skills/, сколько субагентов в .claude/agents/, какие разделы есть в конфиге. На выходе AGENTS.md перезаписывается целиком.
Обновляются обзор проекта, список скиллов с примерами для Codex CLI, дерево папок, паттерны воркфлоу и таблица соответствия слэш-команд. Флаги меняют поведение: --validate только проверяет окружение и ничего не пишет, --status показывает дату последней синхронизации и перечень задокументированных скиллов и агентов.
Codex CLI нужен на первом шаге — без него команда останавливается с ошибкой, и AGENTS.md останется старым. Править AGENTS.md руками нет смысла: следующая синхронизация его перезапишет. Источник правды тут CLAUDE.md.
Какие задачи решает
- Обновить
AGENTS.mdпосле правок вCLAUDE.md - Добавить новый скилл в документацию для Codex CLI
- Проверить окружение перед генерацией, не трогая файл
- Посмотреть, когда
AGENTS.mdсинхронизировали в последний раз - Поймать рассинхрон конфига до коммита
Примеры запросов агенту
- Прогони
/sync-agents-md, я поправилCLAUDE.mdи хочу обновить документацию для Claude CLI. - Проверь окружение без генерации:
/sync-agents-md --validate. - Покажи статус синхронизации:
/sync-agents-md --status.
Как установить sync-agents-md
Вручную: положить файлы
.claude/commands/sync-agents-md.mdВызов — /sync-agents-md. Для всех проектов — ~/.claude/commands/
Вручную: положить файлы
~/.codex/prompts/sync-agents-md.mdВызов — /prompts:sync-agents-md. В Codex этот формат помечен устаревшим, замена — скиллы
Вручную: положить файлы
.github/prompts/sync-agents-md.prompt.mdВручную: положить файлы
.gemini/commands/sync-agents-md.tomlGemini хранит команды в TOML: текст запроса — в поле prompt
Вопросы о sync-agents-md
Как установить sync-agents-md в Claude Code?
Положите файл команды в проект по пути .claude/commands/sync-agents-md.md. После этого вызов /sync-agents-md станет доступен.
Что делает sync-agents-md?
Собирает AGENTS.md заново из CLAUDE.md: обзор проекта, список скиллов и субагентов, структуру папок, воркфлоу и таблицу соответствия команд Claude и Claude CLI.
Что нужно, чтобы команда сработала?
Установленный Claude CLI и CLAUDE.md в проекте. Если чего-то нет, проверка окружения падает и файл не перезаписывается.
Исходный текст
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