readme-sync

---
name: readme-sync
description: Automatically synchronize README.md with actual project components. Scans .codex directory and updates Agents, Skills, Hooks, Commands sections.
license: MIT
---

# README Sync Skill

Automatically keeps README.md synchronized with actual project components. Scans the `.codex` directory structure and updates documentation to match reality.

## Usage

```bash
/readme-sync [--section <name>] [--validate] [--dry-run]
```

### Options

| Option | Description |
|--------|-------------|
| `--section <name>` | Sync specific section: agents, skills, hooks, commands, stats |
| `--validate` | Check for mismatches without making changes |
| `--dry-run` | Show what would change without actually changing |
| (default) | Sync all sections |

## What Gets Synced

### 1. Agents Section
Scans `.codex/agents/*.md` and updates:
- Agent count
- Agent table with names, purposes, keywords
- Auto-detects from frontmatter: `name`, `description`

### 2. Skills Section
Scans `.codex/skills/*/SKILL.md` and `.codex/skills/*.md`:
- Skill count
- Skill table with usage, description
- Auto-detects from frontmatter

### 3. Hooks Section
Scans `.codex/hooks/*.sh` and `.codex/hooks/*.md`:
- Hook count
- Hook table with events, purposes
- Auto-detects from frontmatter or comments

### 4. Commands Section
Scans `.codex/commands/*.md` and `.codex/commands/*/`:
- Command count
- Command table with descriptions
- Includes subcommand files

### 5. Stats Section
Updates summary statistics:
```markdown
| Category | Count |
|----------|-------|
| Agents | 16 |
| Skills | 14 |
| Hooks | 4 |
| Commands | 2 |
| Templates | 5 |
| **Total** | **41** |
```

## Workflow

### Step 1: Scan Components
```bash
# Scan all .codex directories
find .codex/agents -name "*.md" -type f
find .codex/skills -name "SKILL.md" -o -name "*.md" -type f
find .codex/hooks -name "*.sh" -o -name "*.md" -type f
find .codex/commands -name "*.md" -type f
```

### Step 2: Extract Metadata
For each file, extract:
```yaml
# From frontmatter
name: component-name
description: Brief description
tools: [Tool1, Tool2]  # for agents
keywords: [key1, key2]
```

### Step 3: Generate Section Content
```markdown
## Sub-Agents (16)

### Development & Analysis

| Agent | Purpose | Keywords |
|-------|---------|----------|
| `project-analyzer` | Analyze project structure | "analyze", "structure" |
| `code-reviewer` | Review code quality | "review", "PR" |
...
```

### Step 4: Update README
- Find existing section by header
- Replace content between headers
- Preserve custom content outside synced sections

## Section Markers

Use these markers to define sync boundaries:

```markdown
<!-- README-SYNC:agents:start -->
## Sub-Agents (16)
...content auto-generated...
<!-- README-SYNC:agents:end -->

<!-- README-SYNC:skills:start -->
## Skills (14)
...content auto-generated...
<!-- README-SYNC:skills:end -->
```

Without markers, the skill will find sections by `## Sub-Agents` or `## Agents` headers.

## Output Examples

### Sync Report
```
📝 README-SYNC: Synchronizing README.md...

[1/4] Scanning agents...
      Found: 16 agents
      New: file-explorer (+1)
      Removed: none

[2/4] Scanning skills...
      Found: 14 skills
      New: agile-sync, readme-sync (+2)
      Removed: none

[3/4] Scanning hooks...
      Found: 4 hooks
      New: auto-doc-sync (+1)
      Removed: none

[4/4] Updating stats...
      Total: 36 → 40 (+4)

📝 README-SYNC: Complete!
   Sections updated: 4
   Components added: 4
   Components removed: 0
```

### Validation Report
```
📝 README-SYNC: Validation Report

## Agents
✅ 16 agents in README matches 16 files
⚠️ `old-agent` in README but file not found

## Skills
❌ README shows 12 skills, found 14 files
   Missing in README:
   - agile-sync
   - readme-sync

## Hooks
✅ All hooks accounted for

## Stats
❌ Stats section outdated
   README: 33 total
   Actual: 40 total

Issues: 3
Recommendations:
- Run `/readme-sync` to fix mismatches
- Remove reference to `old-agent`
```

## Configuration

### Auto-Sync Settings
```json
{
  "readme-sync": {
    "auto_on_change": true,
    "sections": ["agents", "skills", "hooks", "commands", "stats"],
    "preserve_custom": true,
    "use_markers": true,
    "table_format": "markdown"
  }
}
```

### Section Templates
```yaml
# .codex/readme-sync-config.yml
sections:
  agents:
    header: "## Sub-Agents ({count})"
    columns:
      - name: "Agent"
        source: "name"
        format: "`{value}`"
      - name: "Purpose"
        source: "description"
        truncate: 50
      - name: "Keywords"
        source: "keywords"
        format: "\"{value}\""

  skills:
    header: "## Skills ({count})"
    group_by: "category"
    columns:
      - name: "Skill"
        source: "name"
      - name: "Usage"
        source: "usage"
      - name: "Description"
        source: "description"
```

## Integration

### With auto-doc-sync Hook
```bash
# Hook triggers readme-sync when .codex files change
# In hooks/auto-doc-sync.sh:
if [[ "$TOOL_INPUT" == *".codex/"* ]]; then
    # Trigger README sync suggestion
fi
```

### With /agile-sync
```bash
# agile-sync includes readme-sync as step 3
/agile-sync  # Includes README stats update
```

### Manual Trigger
```bash
# Full sync
/readme-sync

# Specific section
/readme-sync --section skills

# Validate only
/readme-sync --validate
```

## Best Practices

### DO
- ✅ Use section markers for precise updates
- ✅ Run after adding new agents/skills
- ✅ Include in PR checklist
- ✅ Keep frontmatter accurate in source files

### DON'T
- ❌ Manually edit synced sections (will be overwritten)
- ❌ Remove section markers
- ❌ Skip validation before releases

## Troubleshooting

### "Section not found in README"
```bash
# Add section markers or headers:
## Sub-Agents
<!-- or -->
<!-- README-SYNC:agents:start -->
<!-- README-SYNC:agents:end -->
```

### "Component not detected"
```bash
# Ensure frontmatter is valid:
---
name: my-component
description: Brief description
---
```

### "Stats mismatch"
```bash
# Force full recalculation:
/readme-sync --section stats
```

## Related Skills

| Skill | Purpose |
|-------|---------|
| `/agile-sync` | Full agile artifact sync |
| `/init` | Project initialization |
| `/doc` | Documentation generation |