update-project — Claude Code skill: keep docs in sync with code
This skill compares AGENTS.md, CLAUDE.md and README.md against recent commits and fixes the stale parts. Run it after big changes or before a release.
npx skills add tartinerlabs/skills --skill update-project -a claude-codeWhat update-project does
The skill works in three steps. First it reads git log --oneline -20 and git diff to see what actually changed, and checks which instruction files the project has. Then it opens its own rule files — rules/agent-docs.md for documentation, rules/components.md for agents, skills and rules — and applies the edits. Last step: it runs the commands the docs mention to confirm they still work.
AGENTS.md is treated as the main instruction file, read by Claude, Codex and other hosts. CLAUDE.md is legacy here: the skill maintains one if it exists but never creates a new one. When both are present it suggests consolidating into AGENTS.md instead of keeping two divergent copies. Components follow the same split — .claude/ for Claude, .agents/skills/ for the rest.
One rule shapes everything: touch only what the project really changed. Every claim gets checked against the file tree before it is written, and sections that cannot be verified are left alone. So read the diff afterwards — the skill deliberately skips anything it is unsure about. It works with Read, Glob, Edit, Write and Bash(git:*).
What it helps with
- update the README after a command or path was renamed
- drop a removed dependency from AGENTS.md
- merge CLAUDE.md and AGENTS.md into one instruction file
- confirm the commands listed in the docs still run
- refresh the skills and rules section after adding new ones
Example prompts for the agent
- update the project docs based on the latest commits
- sync AGENTS.md and README with the current state of the code
- check whether the instructions in CLAUDE.md are stale
How to install update-project
1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill update-project -a claude-code2Manually: put the files in place
~/.claude/skills/update-project/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/update-project/
1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill update-project -a codex2Manually: put the files in place
.agents/skills/update-project/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill update-project -a cursor2Manually: put the files in place
.cursor/skills/update-project/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tartinerlabs/skills update-project2Manually: put the files in place
.github/skills/update-project/SKILL.md1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill update-project -a gemini-cli2Platform CLI
gemini skills install https://github.com/tartinerlabs/skills --path plugins/tooling/skills/update-projectManually: put the files in place
.devin/skills/update-project/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill update-project -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about update-project
How do I install update-project in Claude?
Run npx skills add tartinerlabs/skills --skill update-project -a claude-code. The skill lands in ~/.claude/skills/update-project/SKILL.md.
What does update-project do?
It compares project documentation with recent code and git changes, then fixes stale sections in AGENTS.md, CLAUDE.md and README.md. It also verifies that the commands mentioned in the docs still run.
How does it treat AGENTS.md versus CLAUDE.md?
AGENTS.md is the cross-agent standard read by Claude, Codex and other hosts. CLAUDE.md counts as legacy: the skill maintains an existing one but never creates a new one, and proposes merging both into AGENTS.md.
Source text
SKILL.md · MIT
--- name: update-project description: Use when updating docs, syncing AGENTS.md, CLAUDE.md, or README.md, fixing stale documentation, or refreshing project rules and skills. Keeps docs aligned with code changes. license: MIT allowed-tools: Read Glob Edit Write Bash(git:*) model: haiku effort: low compatibility: Any project with agent docs (AGENTS.md, or a legacy CLAUDE.md) and/or a README; language-agnostic metadata: short-description: Keep docs in sync with code. --- You keep project documentation synchronized with recent code changes and git commits. Run after significant code changes, before a release, or whenever docs may be stale. Update only what the project actually changed. Verify a claim against the tree before you write it, and leave sections you cannot verify alone. `AGENTS.md` is the agent instruction file — the cross-agent standard, read by Claude Code, Codex, and other hosts. Treat `CLAUDE.md` as legacy: maintain one that exists, but do not create a new one. Component directories follow the same split — `.claude/` for Claude Code, `.agents/skills/` for Codex and other hosts that use the cross-agent skills path. Do not invent `.agents/agents` or `.agents/rules`. ## Rules Overview | Rule | Impact | File | |------|--------|------| | Agent docs (AGENTS.md / CLAUDE.md / README.md) | HIGH | `rules/agent-docs.md` | | Components (agents, skills, rules) | MEDIUM | `rules/components.md` | ## Workflow ### Step 1: Detect - Run `git log --oneline -20` and `git diff` to identify recent changes - Check which agent instruction files exist (`AGENTS.md`, `CLAUDE.md`) and whether README.md exists (create if missing) - Scan `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.claude/rules/*.md`, and `.agents/skills/*/SKILL.md` - Compare documented instructions against actual project state to find stale sections - Flag any new tools, removed dependencies, changed paths, or renamed commands ### Step 2: Update Read the relevant rule file and apply updates: - `rules/agent-docs.md` for AGENTS.md / CLAUDE.md / README.md changes - `rules/components.md` for `.claude/` agents, skills, and rules, and for `.agents/skills/` ### Step 3: Validate - Run project commands mentioned in docs to verify they work - Check that instructions match current project setup - Ensure the agent instruction file (AGENTS.md), README.md, agents, skills, and rules complement each other without duplication - If both AGENTS.md and CLAUDE.md exist, propose consolidating into AGENTS.md per `rules/agent-docs.md` rather than keeping divergent copies
© tartinerlabs · MIT · tartinerlabs/skills
