---
name: readme-updater
description: Detect when a commit changes how a project runs (env vars, CLI flags, routes, config keys, dependencies, scripts, version requirements) and update README.md and related docs to match. Shows a unified diff for review before writing anything.
---

# README Updater

Keep documentation in sync with the codebase. Run this after a commit — or on
demand — to find documentation drift introduced by `HEAD` and propose the
smallest doc edits that close the gap.

This skill is read-only until you approve the diff.

## When to run

- Invoked explicitly: `Run readme-updater skill on HEAD`
- Automatically from a Git `post-commit` hook (see **Install the Git hook** below)
- Before opening a pull request, to catch drift locally first

## Procedure

1. **Pick the range.** Default to the last commit.
   - `git show --stat HEAD` for the summary.
   - `git diff HEAD~1 HEAD` for the patch. If `HEAD~1` does not exist (first
     commit), use `git diff --cached` or `git show HEAD`.
   - If the user names a range (`main..HEAD`, a SHA), use that instead.

2. **Filter noise.** Ignore, before analysis:
   - Lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `poetry.lock`, `Cargo.lock`, …)
   - Generated / vendored paths (`dist/`, `build/`, `vendor/`, `node_modules/`, `*.min.*`)
   - Binary blobs
   - Pure whitespace / formatting / import-reorder changes
   - Comment-only edits
   - Test files (`*_test.*`, `*.test.*`, `tests/`, `__tests__/`) — unless the
     test is the only place a documented example lives

3. **Extract structural signals** — the things that change how someone runs or
   configures the project:
   - Environment variables (added, removed, renamed, default changed)
   - CLI flags, subcommands, positional arguments
   - HTTP routes / endpoints / webhook paths
   - Config-file keys (`*.toml`, `*.yaml`, `*.json`, `settings.*`)
   - Added or removed dependencies, services, or external APIs
   - Task-runner scripts (`package.json` `scripts`, `Makefile`, `justfile`, `Taskfile`)
   - Minimum runtime / language / tool version requirements
   - Ports, health-check paths, container entrypoints

4. **Load the docs.** `README.md` plus, if present: `docs/**/*.md`,
   `CONTRIBUTING.md`, `.env.example`, `docs/configuration.*`.

5. **Diff intent vs. docs.** For each signal, check whether the docs already
   cover it correctly. Collect only the ones that are missing, wrong, or stale.

6. **Draft the smallest edit.** Put each change in the section that already
   exists for it (the env-var table, the CLI reference, the "Configuration"
   list). Do not restructure the file, do not add new top-level headings, and
   match the surrounding tone, table style, and formatting.

7. **Show, don't write.** Print:
   - A short list of the signals found (or `README is in sync.` and stop).
   - A unified diff (```diff fenced block) per file.
   - One line on what to review most carefully.

8. **Apply on approval.** Write the approved edits. If this run was triggered by
   the `post-commit` hook and the user asks, stage the docs and
   `git commit --amend --no-edit` so the documentation fix travels with the code
   commit rather than trailing it.

## Output format

```
Signals found:
  - Added env var: REDIS_CACHE_URL (default redis://localhost:6379)
  - New CLI flag: --enable-metrics

README.md
```diff
 | Variable | Description | Default |
 | :--- | :--- | :--- |
 | LLM_PROVIDER | Model backend | gemini |
+| REDIS_CACHE_URL | Redis cache host URL | redis://localhost:6379 |
```

Review: confirm the default matches config.py, then approve to write.
```

## Rules

- Never invent behavior. Document only what the diff and the code actually show.
- Prefer editing an existing table or list over adding prose or a new heading.
- If nothing structural changed, exit quietly with `README is in sync.`
- Keep every change reviewable — one diff, no silent writes.
- Do not touch files outside the docs set without saying so.

## Install (one-click)

```sh
mkdir -p .claude/skills/readme-updater && curl -fsSL https://readme2.kamipresents.com/skills/readme-updater/SKILL.md -o .claude/skills/readme-updater/SKILL.md
```

## Install the Git hook (optional auto-trigger)

```sh
cat << 'EOF' > .git/hooks/post-commit
#!/bin/sh
claude "Run readme-updater skill on HEAD"
EOF
chmod +x .git/hooks/post-commit
```

The hook runs the skill after every commit. It only ever prints a diff; nothing
is written or amended without your say-so.