Project Documentation Sync

Update all project documentation files in one pass by delegating to specialized skills.

Workflow

1. Analyze codebase → 2. CLAUDE.md + AGENTS.md → 3. README.md → 4. SKILLS.md → 5. CHANGELOG.md → 6. Summary

2. Analyze Codebase

Before updating any docs, gather project state:

Project type signals

ls package.json go.mod pyproject.toml Cargo.toml Dockerfile *.tf 2>/dev/null

Current doc state

ls CLAUDE.md AGENTS.md README.md SKILLS.md 2>/dev/null

Recent changes since docs were last updated

git log --oneline -20

Plugin/skill count if marketplace repo

ls plugins/ 2>/dev/null | wc -l

2. CLAUDE.md + AGENTS.md

CRITICAL: Never manually edit the AGENTS.md directory tree. It uses non-breaking spaces (\xa0 ) from the tree command that the Edit tool cannot match. Always use the script — it regenerates the tree from scratch.

Run validate_docs.py --fix from the doc-claude-md skill:

python3 ~/.claude/skills/doc-claude-md/scripts/validate_docs.py --path <project> --fix

This handles:

• Regenerating the directory tree (from tree command)

• Validating CLAUDE.md (pointer file)

• Checking AGENTS.md structure and codebase consistency

• Updating last_validated timestamp

After the script runs, manually update any non-tree content in AGENTS.md (e.g., skill counts in prose, new naming conventions).

3. README.md

Delegate to doc-readme skill:

Skill(skill="doc-readme")

This handles:

• Creating or updating README.md

• Syncing with current codebase state (features, structure, install steps)

4. SKILLS.md

Delegate to doc-skills-md skill:

Skill(skill="doc-skills-md")

This handles:

• Analyzing project to recommend relevant marketplace plugins

• Creating or updating Required/Recommended tables

• Updating plugin counts

Skip this step if the project does not use a plugin marketplace.

5. CHANGELOG.md

Delegate to doc-changelog skill:

Skill(skill="doc-changelog")

This handles:

• Generating changelog entries from git history since last release/tag

• Classifying commits by type (Added, Changed, Fixed, Removed)

• Enriching entries with PR references

• Updating the Unreleased section

Skip this step if the project does not maintain a CHANGELOG.md.

6. Summary

After all updates, report what changed:

Documentation Updated

Modes

Full Sync (default)

Update all five files. Use for initial setup or after major changes.

"Update all project docs"

Selective

Update only specified files. Name them explicitly.

"Update AGENTS.md and README.md"

Validate Only

Check docs without modifying. Report what's stale.

"Check if project docs are up to date"

For validate-only, read each file and compare against codebase state. Report discrepancies without editing.