update-project-docs_skill

Overview

This skill keeps CLAUDE.md and AGENTS.md up to date after significant project changes. It targets project-level documentation so future AI sessions and contributors start with accurate, actionable context and setup steps.

How this skill works

When invoked, the skill confirms a CLAUDE.md or AGENTS.md exists in the project root and inspects recent changes (git diff or user summary). It compares the current repository state against documented content, flags stale or missing entries, and prepares focused edits that match the file's existing voice and structure. Finally, it summarizes the proposed updates for user review.

When to use it

• After adding new modules, packages, or top-level directories
• When renaming, moving, or deleting files referenced in CLAUDE.md/AGENTS.md
• After changing build, test, lint commands, or developer tooling
• When introducing new conventions, patterns, or documented entry points
• After reorganizing document structure or adding dependencies that need setup steps

Best practices

• Only run if a CLAUDE.md or AGENTS.md exists in the project root
• Use git diff or a concise change summary to identify what affects docs
• Preserve the original file's voice and structure; add to existing sections when possible
• Prefer short, scannable bullets; remove stale content rather than piling on
• Be specific with commands and paths; avoid implementation-level details

Example use cases

• Added a new top-level package 'payments' — append one-line description and any setup steps
• Renamed src/api.py to src/service/api.py — update file paths and any referenced commands
• Switched test runner from pytest to tox — update test commands and required tooling notes
• Introduced a new contribution convention (commit message format) — add a concise guideline entry
• Added a dependency requiring environment variables or installation steps — add a Setup or Prerequisites bullet