Skip to content
Skills Library
Programming · Automation

sync-docs

/sync-docs

Use when the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, and README.md to reflect recent commits or PRs. Triggers on phrases like "sync docs", "update CLAUDE.md", "update AGENTS.md", "update SKILL.md", "update README", "reflect recent changes", or "document the recent PRs".

Repository
rk-skills ↗
Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, and README.md to reflect recent commits or PRs. Triggers on phrases like "sync docs", "update CLAUDE.md", "update AGENTS.md", "update SKILL.md", "update README", "reflect recent changes", or "document the recent PRs".

Triggers from the description

sync docsupdate CLAUDE.mdupdate AGENTS.mdupdate SKILL.mdupdate READMEreflect recent changesdocument the recent PRs
Original author description

Use when the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, and README.md to reflect recent commits or PRs. Triggers on phrases like "sync docs", "update CLAUDE.md", "update AGENTS.md", "update SKILL.md", "update README", "reflect recent changes", or "document the recent PRs".

How it works

  1. Steps
Original SKILL.md headings · 40 lines, 1,250 words
SKILL.md preview
---
name: sync-docs
description: Use when the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, and README.md to reflect recent commits or PRs. Triggers on phrases like "sync docs", "update CLAUDE.md", "update AGENTS.md", "update SKILL.md", "update README", "reflect recent changes", or "document the recent PRs".
---

# sync-docs

Keep CLAUDE.md, AGENTS.md, SKILL.md, and README.md accurate after new commits land: find the last docs-sync point, classify every commit since then, and write targeted edits. Syncing is bidirectional: add what is new, and **remove or correct anything the current codebase contradicts**.

Edit the docs that exist; never create a new top-level doc (AGENTS.md, CHANGELOG.md, SKILL.md) during a sync. If one seems warranted, tell the user.

Audiences: **CLAUDE.md** is the dense agent reference (architecture, symbol and file names, `file:line` cues) and describes current behavior, never history. **AGENTS.md** mirrors it for other agent tools (step 5). **SKILL.md** is operator-facing and imperative (config keys, setup, CLI flows); no symbol or field names in its tables. **README.md** is the newcomer entry point and changes only when the public surface changes. **CHANGELOG.md**, when present, holds per-issue rationale and migration history.

Preconditions: `gh auth status` succeeds. Resolve `DEFAULT=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)`, run `git fetch origin`, record the range end `T0=$(git rev-parse "origin/$DEFAULT")`, and create a worktree off that tip with the harness branch prefix (`cc/` on Claude Code): `git worktree add .claude/worktrees/cc+sync-docs-<YYYY-MM-DD> -b cc/sync-docs-<YYYY-MM-DD> "$T0"`. Every range below ends at `$T0`, never at a later `origin/$DEFAULT`. When that branch already exists locally or on `origin`, never delete or reuse it: add the next free suffix to the branch and the worktree name (`-2`, then `-3`). Read, edit, and run every git command in that worktree (`-C <worktree>`), never in the main checkout.

## Steps

1. **Baseline.** `git log --oneline "origin/$DEFAULT" | grep -m1 -E '^[0-9a-f]+ ([Ss]ync docs\b|docs(\([^)]*\))?: sync\b|docs\(sync\):)'`. A sync is a `docs:` or `docs(<scope>):` subject that begins with "sync", a `docs(sync):` scope, or a subject that begins with "sync docs"; a commit that mentions "sync docs" later in its subject is no sync, and a docs commit that only names CLAUDE.md or SKILL.md is no sync. The matched commit `M` is the baseline unless it records a range end: read `git log -1 --format=%B <M>` for a `Docs-sync-range-end: <sha>` line; when the body has none and the subject ends with `(#N)` (a squash merge), read `gh pr view <N> --json body -q .body` for that line. When a recorded `<sha>` exists and `git merge-base --is-ancestor <sha> "origin/$DEFAULT"` holds, the baseline is `<sha>`; otherwise it is `M`. If none, ask the user for the last-known-good tag or SHA, or use the initial commit for a first sync.
2. **Range.** `git log <baseline>.."$T0" --oneline`. Skip pure CI, workflow, and chore commits unless they change agent- or operator-facing behavior.
3. **Classify each commit** (an unrelated-areas commit is classified per area):

| Category | Docs target | Action |
|----------|-------------|--------|
| New config field / flag | CLAUDE.md config; SKILL.md settings table; README.md only for a public top-level setting | Add field description |
| Changed default behavior | CLAUDE.md patterns; SKILL.md; README.md only if a documented example now contradicts the code | Update; note old vs new |
| New pluggable unit (plugin, command, integration, provider, theme) | Every doc that enumerates the set | Add one entry per doc |
| Bug fix (behavior change) | CLAUDE.md patterns, if pattern-level | Update the bullet |
| New CLI command / flag | SKILL.md commands; README.md Getting Started only if part of setup | Add usage |
| Setup / install flow change | README.md Getting Started; SKILL.md if operator-facing | Update the block |
| Removed field | Whichever doc lists it | Delete the row or bullet |
| Behavior reversal (fix reverted) | Whichever doc carries it | Note the revert explicitly |
| Internal refactor / test | Skip | none |
| Release milestone | Project notes file, if one exists (step 9) | Append version entry |
| Rationale or migration history (CHANGELOG.md exists) | CHANGELOG.md | Keyed entry there; CLAUDE.md keeps only the current invariant |
| Doc claim contradicted by code | Whichever doc carries the claim | Correct or delete it |

4. **Audit docs near in-scope commits.** Verify surrounding claims: paths exist, symbol names match, defaults and versions are current, CLI flags accept the documented args. Delete or correct what the code contradicts; grep first, and never remove a claim you haven't verified is wrong. Stay scoped; if the docs look broadly drifted, flag it instead of rewriting. Check "current/active/default" claims against the deciding switch (build target, feature-flag default, active-environment key), never against the doc's own prior text. When a commit touches a directory of pluggable items, `ls` it and diff against every catalog, index, and README list. When one item is promoted and another retired, confirm the active state (self-referencing URLs, indexing directives, flags, defaults) flipped on both; if that invariant is real but undocumented, add a short rule.
5. **Edit CLAUDE.md, then mirror into AGENTS.md.** Edit only changed sections; terse bullets, one behavioral change each; update any schema or config version constant a migration bumped; rewrite PR descriptions as imperative phrases. Then `ls -l AGENTS.md`: symlink to CLAUDE.md, skip it and never open it for writing; real file, apply every CLAUDE.md body edit verbatim, keep its own intro line, and audit it per step 4; absent, skip.
6. **Edit SKILL.md** (only if the repo has one). Add new keys to the settings table and the upgrade or post-update reference; update commands, reload scope, and safety-control sections when those surfaces change.
7. **Edit README.md** (only if the public surface changed). Default to no edit. Touch it only for a new supported feature or integration, a new public unit in an enumerated list, a new top-level CLI subcommand, a setup or install change, or a public config example the code now contradicts. Tutorial tone: no `file:line` cues, internals, or PR numbers; one line per list item in the existing format. Always check its enumerated lists for new public units.
8. **Size check.** `wc -c CLAUDE.md`. Above **35000** bytes, condense in place to under **30000**; never split it. Keep symbol and file names, field lists, enum values, defaults, version numbers, gotchas, concurrency and ordering rules, live behavior, the Environment, Setup, Build & Deploy, and Testing blocks, lookup tables of IDs, paths, or prefixes, and repo-defined format conventions. Drop "why" prose where the rule alone is actionable, shipped-migration narrative, resolved-incident stories, duplicates, and examples that restate a rule; move history to CHANGELOG.md when it exists. Re-run `wc -c` and report old and new counts. Still over 40000, list the largest sections and ask the user which to cut.
9. **Project notes file**, if the repo keeps one with a Releases section and the range includes a version tag or release PR: append `- **vX.Y.Z** — YYYY-MM-DD: <summary> (PRs #N, #M)`.
10. **Land the edits through a PR.** `git status` in the worktree. Stage only the doc files this sync changed, by name. Nothing staged: report "no doc changes", remove the worktree and delete its unpushed local branch (`git branch -D <branch>`), and stop. Otherwise commit with a subject that matches the step 1 baseline pattern (`docs: sync <what> after <range>`, or `docs(sync): ...`), a body line `Docs-sync-range-end: $T0` (the full SHA), and the repo's commit footer, push the branch, open a PR against `$DEFAULT` whose title begins with that same subject (plus any title suffix the repo's PR convention requires, such as `[C<score>, <model>, <effort>]`) and whose body follows the repo's PR body rules and carries the same `Docs-sync-range-end: $T0` line, and report its number and URL. A standalone run leaves the PR open for review; a caller such as `sync-docs-release` owns the merge decision.

Versions

RepositoryScoreLicence
This page · richkuo/rk-skills100MIT
OutlineDriven/outline-driven-development100Apache-2.0
rawbytess/hissab100MIT
mysticaltech/terraform-hcloud-kube-hetzner100MIT
joaquimscosta/arkhe-claude-plugins100MIT
gosuda/dalcom-skills95Apache-2.0
moonklabs/aiwf90MIT
whchoi98/harness-eval90MIT

Database snapshot: 13.11.2026 · package version 380ca7019867 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100update-readme
    Updates README.md and README.zh-CN.md to reflect the project's current state. Use this skill whenever the user asks to "update the README", "sync the docs", "update documentation", "reflect latest changes in README", or wants both the English and Chinese READMEs to match the current project.
  • 100update-docs
    Use after an epic completes, after a substantive merge, when documentation is out of sync with the code, or when the user asks to update docs / regenerate the README / refresh stale documentation. Invokes the doc-writer agent to update project documentation based on the recent…
  • 100docs
    Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit. Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs".
  • 100docs
    Sync docs with code. Updates README, CLAUDE.md or AGENTS.md, docs/, API docs, changelog, ADRs, env examples and agent memory after a change; a drift-check mode reports mismatches without editing. Use when docs are stale, update the docs, sync README, docs out of date, after…
  • 100update-documents
    Synchronizes documentation between CLAUDE.md, README.md, and docs/. Resolves documentation inconsistencies across project files with configurable sync rules and whitespace-tolerant comparison. Use when the user asks to "sync the docs", "update documentation", "make README and…
  • 90check-docs
    Check if documentation (README.md, AGENTS.md, docs/) is up to date with recent code changes. Use when code has been modified and docs may be stale.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.