# Sync Docs

> Update all README.md and CLAUDE.md files to reflect current codebase state. Combines update-docs and update-claudes. Also archives completed active plans.

- Skill: `kazhou/sync-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kazhou/sync-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kazhou/sync-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kazhou (https://skillmd.com/u/kazhou)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/kazhou/sync-docs

---


# Sync Docs

Recursively update all README.md and CLAUDE.md files, then archive completed active plans.

## Part 1: Update READMEs

### What belongs in READMEs

READMEs are for humans:
- What the directory/project does (purpose)
- File/directory listing with brief descriptions
- Setup/usage instructions
- Links to sub-READMEs and related docs
- Data format descriptions (for data/ dirs)

### Steps

1. **Find README.md files**
   - If `$ARGUMENTS` is provided, scope to that directory's README only
   - Otherwise, use Glob to find all `**/README.md` in the project
   - Exclude `node_modules/`, `.venv/`, `.git/`, `agent_dev/`

2. **Audit each README against its directory**
   - List the actual files and subdirectories (using `ls`)
   - Compare against what the README documents
   - Flag:
     - **Stale references** — files/dirs mentioned that no longer exist
     - **Undocumented entries** — files/dirs that exist but aren't mentioned
   - Ignore: `.gitignore`, `__pycache__`, `.DS_Store`, `*.pyc`

3. **Verify internal links (root README especially)**
   - Check that all markdown links resolve to existing files
   - Check that directory tree diagrams match reality
   - Flag broken links and outdated tree diagrams

4. **Update each README**
   - Add brief entries for undocumented files/dirs
   - Remove or mark references to deleted files
   - Fix broken internal links
   - Update directory tree diagrams to match current structure
   - Keep descriptions concise — don't over-document
   - Preserve existing style and tone

## Part 2: Update CLAUDE.md Files

### What belongs in CLAUDE.md

CLAUDE.md files are for agents:
- Instructions and constraints for working in this directory
- Commands to run (test, build, lint, etc.)
- Conventions to follow
- `# Insights` section (append-only — never modify)

Keep CLAUDE.md files CONCISE. Favor pointing to where information can be found. No code snippets; reference files and line numbers instead (e.g., `file:line`).

### Steps

1. **Find CLAUDE.md files**
   - If `$ARGUMENTS` is provided, scope to that directory's CLAUDE.md only
   - Otherwise, use Glob to find all `**/CLAUDE.md` in the project
   - Exclude `node_modules/`, `.venv/`, `.git/`, `agent_dev/`
   - Also check for `.claude/CLAUDE.md` variants

2. **Audit each CLAUDE.md for accuracy**
   - **File/path references** — do referenced files and directories still exist?
   - **Command references** — do referenced commands still work?
     - Check `pyproject.toml` `[project.scripts]` and `[tool.uv.scripts]`
     - Check `Makefile` targets if referenced
     - Check `package.json` scripts if referenced
   - **Skill references** — are referenced skills still installed? (check `global_settings/claude/skills/` and `.claude/skills/`)
   - **Directory descriptions** — do they match current directory contents?

3. **Update each CLAUDE.md**
   - Fix stale file/path references
   - Update command references to match current config
   - Remove references to deleted directories or tools
   - Update directory descriptions if structure changed
   - **DO NOT touch `# Insights` sections** — these are append-only
   - Preserve existing style and structure

## Part 3: Archive Completed Plans

1. **Scan `agent_dev/active/`** for plans where all tasks are checked off
2. **Move completed plans** to `agent_dev/archived/`
3. **Report** which plans were archived

## Summary

Show:
- Each README updated and what changed
- Each CLAUDE.md updated and what changed
- Plans archived (if any)
- Items that need human input