Update Project Docs

Documentation Updater

Guides you through updating project documentation based on code changes on the active branch. Works with any project regardless of language, framework, or documentation format.

> Important: For first-time runs or updates spanning a long period, it is strongly recommended to use the most capable model with thinking/extended thinking enabled and effort set to maximum. The first run performs a full-project audit that determines the baseline for all future incremental updates — any documentation gaps missed during this run will not be caught by subsequent incremental diffs, since incremental mode only reviews code changes after the recorded sync point. Investing in thoroughness up front pays off in every future run.

Quick Start

1. Pre-flight check: Verify the working tree is clean and find the last sync point
2. Discover project structure: Find documentation directories, formats, and conventions
3. Determine run mode:

• First run (no .docs-sync record): Perform a full-project audit — read the entire codebase, compare with existing docs, fill every gap. Do not rely on git diff.
• Incremental run (sync record exists): Read the recorded commit hash, then resolve the effective diff base. If the commit immediately after the recorded hash updates the sync record, use that commit as the diff base; otherwise use the recorded hash itself.

1. Map code to docs: Identify which documentation is missing, outdated, or affected
2. Scaffold missing doc infrastructure (first run only, if needed): Create the doc site skeleton
3. Review and update each doc: Walk through updates with user confirmation
4. Validate: Run the project's lint/build checks
5. Record sync point: Save the current code-sync commit hash
6. Commit: Stage the documentation changes and sync record together

Workflow: Pre-flight Check

Always run this before any other workflow step.

Step 1: Check the working tree

git status --porcelain

If the output is non-empty, there are uncommitted changes (modified, staged, or untracked files). Stop and ask the user how to proceed before continuing. Present these options:

1. Commit first, then continue — The user commits or stashes their changes, then re-invokes the skill. This ensures uncommitted edits are included in the doc update.
2. Ignore uncommitted changes — Proceed using only committed history. Uncommitted edits will not be reflected in the documentation update.

Use the AskUserQuestion tool to present this choice. Do not silently include or exclude uncommitted changes — the user must decide explicitly.

Step 2: Find the last sync point

The skill records the commit hash of the code state that the documentation is synced to in a tracking file so subsequent runs can do incremental updates instead of re-scanning the entire codebase.

Look for the sync record in this order:

1. Dedicated tracking file at the repository root or docs root:

• .docs-sync
• docs/.docs-sync
• .claude/docs-sync

1. Frontmatter field on a docs index page (e.g., last_synced_commit: in docs/index.md)
2. HTML comment in a docs README (e.g., ``)

The file format records both the end and start commits of the most recent documentation sync, plus a timestamp:

end_commit: abc1234567890def...
start_commit: 7890fedcba0987...
synced_at: 2026-04-11T10:30:00Z

• end_commit: HEAD at the moment the documentation sync was committed. This is the primary sync point — the incremental run uses it as the diff base.
• start_commit: The diff base of the run that produced this record (i.e. the commit the docs were synced from in the previous round). It exists as a fallback for when end_commit is gone — most often after a squash-merge of a feature branch erases the end_commit that lived only on that branch, while start_commit (which sat on the long-lived base branch) survives. On the very first run there is no prior diff base, so start_commit may be omitted or set equal to end_commit.
• synced_at: ISO-8601 timestamp of when the sync was recorded (informational; not used for diff resolution).

For backwards compatibility, older sync records may contain only a bare commit hash (and optional timestamp) on its own line — in that case, treat the hash as end_commit with no start_commit.

Decide the run mode based on what you find:

Incremental run (sync record exists)

Resolve a usable diff base by trying candidates in order: end_commit first, then start_commit, and only if both fail prompt the user.

For each candidate hash, run both validation checks:

1. Existence: git cat-file -e — the commit object is in the local repo
2. Reachability: git merge-base --is-ancestor HEAD — the commit is on the ancestry of the current branch. The existence check alone passes for any commit in the object database (including ones on unrelated branches or detached from the current branch's ancestry), which would silently produce a wrong diff range, so the reachability check is required.

Resolution flow:

• If end_commit passes both checks, use it as the diff base. Then refine: find the commit immediately after end_commit on the current branch with git rev-list --ancestry-path --first-parent --reverse ..HEAD | head -n 1.
• If that immediate next commit updates the sync record, treat that commit as the effective diff base. This skips the previous documentation-sync commit instead of reprocessing it on every run.
• If that immediate next commit does not update the sync record, use end_commit itself as the diff base and include that commit in the review.
• Use the effective base for review: git diff ...HEAD
• If end_commit fails but start_commit exists in the record and passes both checks, fall back to start_commit as the diff base. Inform the user this fallback is being used (so they understand why already-reviewed code may reappear in the diff) — typically this happens after a squash-merge erased end_commit, and start_commit is the still-reachable ancestor on the base branch.

Then apply a squash-merge skip when it can be proven safe:

• Find the commit immediately after start_commit on the current branch: git rev-list --ancestry-path --first-parent --reverse ..HEAD | head -n 1.
• That commit qualifies as the squash-merge of the previous round if all of the following hold:

1. It updated the sync record file (git diff-tree on that commit shows the sync record path), and
2. The start_commit field inside the updated sync record (read it from that commit's tree, e.g. git show :) resolves to the same commit as our current start_commit.

• When both conditions hold, treat that immediate next commit as the effective diff base (skip it). It is the squashed result of the previous doc-sync round, and the assumption is that the pre-merge code review already verified the docs were updated comprehensively for that round, so re-reviewing the squashed code changes here would add no value.
• When either condition fails, do not skip. Use start_commit itself as the diff base and include the immediate next commit in the review — the equality check on the recorded start_commit is what distinguishes "this is the squash of the round that started from us" from "this is some unrelated later doc-sync commit that just happens to be next".

Whether or not the skip applies, the diff range may still redundantly include code already reviewed in the previous round (e.g., commits that landed after the squash-merge but were not part of it) — accept that as the price of avoiding a full audit.

• If both end_commit and start_commit are unusable (missing, unreachable, or the record predates the start/end format and only had a single hash that itself failed), stop and ask the user how to proceed via AskUserQuestion. Present these options:

1. Specify a different commit hash — the user provides a replacement commit (e.g., a known-good earlier sync point, the last release tag, or a commit they remember the docs were accurate at). Re-validate the new hash with both cat-file -e and merge-base --is-ancestor, then continue with the incremental flow using that hash as the diff base. After the run completes, the sync record is updated to the new HEAD as usual.
2. Fall back to first-run / full-project audit — perform a complete audit, then record HEAD as the new sync point.

Falling back to a full audit is significantly more expensive than incremental review, so giving the user a chance to point at a still-reachable earlier commit is often the right escape hatch. If a project's .docs-sync is frequently invalidated all the way through start_commit, surface that to the user (likely caused by force-push / rebase habits, repeated history rewrites, or shallow clones) rather than silently re-scanning the entire codebase on every run.

First run (no sync record)

Do not use git diff as the entry point. A first run means the documentation has never been audited against the current codebase — there may be missing, outdated, or stale documentation regardless of recent git history. Even if git diff origin/main...HEAD is empty, the docs may still need substantial work.

Instead, perform a full-project audit (see the "First-Run Full Audit" workflow below). After the audit is complete and documentation is updated, record the current HEAD as the code-sync point so subsequent runs can switch to incremental mode.

Workflow: Discover Project Structure

Before analyzing changes, understand the project's documentation setup.

Step 1: Find the base branch

# Detect the default branch
git remote show origin | grep 'HEAD branch'

# Or check common names
git branch -a | grep -E 'main|master|develop'

Step 2: Find documentation directories

Use the Glob tool to search for common documentation locations:

• docs/, documentation/, doc/
• site/, website/, content/
• wiki/, guides/, manual/
• Co-located README.md files alongside source code
• api-docs/, api-reference/

Also check for documentation build configuration files that reveal the doc root:

• mkdocs.yml (MkDocs)
• docusaurus.config.js / docusaurus.config.ts (Docusaurus)
• conf.py (Sphinx)
• book.toml (mdBook)
• antora.yml (Antora)
• .vitepress/ (VitePress)
• _config.yml with docs theme (Jekyll)

Step 3: Identify documentation format

| Format | Extensions | Common In | | ----------- | -------------------- | ------------------------------- | | Markdown | .md | Most projects | | MDX | .mdx | React-based doc sites | | reStructuredText | .rst | Python projects (Sphinx) | | AsciiDoc | .adoc, .asciidoc | Java/enterprise projects | | HTML | .html | Legacy or generated docs |

Step 4: Discover sidebar / navigation structure

Many documentation systems use a sidebar or navigation config that defines the canonical hierarchy and ordering of pages. If one exists, it is the single source of truth for how documentation files should be organized on disk. Check for:

| Config File | System | | ---------------------------- | --------------- | | sidebars.js / sidebars.ts | Docusaurus | | mkdocs.yml → nav: section | MkDocs | | SUMMARY.md | mdBook | | _sidebar.md | Docsify | | _toc.yml | Jupyter Book | | .vitepress/config.* → sidebar | VitePress | | antora.yml → nav: | Antora | | _data/navigation.yml | Jekyll | | book.json / book.js | GitBook |

When a sidebar config is found:

1. Parse its hierarchy — understand the tree structure (sections, groups, ordering)
2. Map it to the file system — note how sidebar entries map to directories and file paths
3. Use it as the default organization rule — when creating or moving documentation files, place them according to the sidebar hierarchy unless the user explicitly provides different instructions
4. Keep sidebar and directories in sync — if the sidebar groups topics into sections like Getting Started > Installation, the corresponding file should live in a directory path that reflects that grouping (e.g., docs/getting-started/installation.md)

If no sidebar config is found, fall back to the existing directory structure as the organizational guide.

Step 5: Discover validation commands

Check for lint/build commands in:

• package.json (scripts section) — look for lint, docs:build, docs:lint
• Makefile / justfile — look for docs, lint-docs, build-docs targets
• tox.ini / noxfile.py — look for docs environments
• CI config (.github/workflows/, .gitlab-ci.yml) — look for doc validation steps

Workflow: First-Run Full Audit

Use this workflow when no sync record exists. The goal is to bring documentation up to parity with the current state of the codebase, not to review recent changes.

Step 1: Enumerate the codebase

Build a picture of what the project actually contains. Use Glob and Read (or delegate to the Explore subagent for larger codebases) to identify:

• Public APIs: exported functions, classes, modules, CLI commands, HTTP endpoints
• Configuration surface: config files, environment variables, CLI flags
• User-facing features: anything a consumer of this project would need to know about
• Entry points: main modules, __init__.py, index.*, main.*, cli.*
• Project metadata: pyproject.toml, package.json, Cargo.toml, go.mod, etc. for project purpose and dependencies

Ignore internal-only utilities, test fixtures, and build artifacts.

Step 2: Enumerate existing documentation

List every existing documentation file and note what each covers:

• All files under the doc root (docs/, etc.)
• README.md at the project root
• Co-located README files in source directories
• Any sidebar/navigation config (it tells you what docs the project intends to have)

Step 3: Build a gap analysis

Compare the codebase to the docs and categorize. Documentation maintenance is not just about adding and updating — deleting obsolete docs and merging redundant ones are equally important to keep the documentation concise, accurate, and maintainable.

| Status | Meaning | Action | | ------------- | ----------------------------------------------------- | ------------------------------- | | Missing | Feature/API exists in code but has no documentation | Create a new doc | | Outdated | Doc exists but references removed/changed code | Update the doc | | Obsolete | Doc describes a feature/workflow that no longer exists or is no longer relevant to the project | Delete — remove the file, remove its sidebar entry, remove links pointing to it | | Redundant | Multiple docs cover the same topic with overlapping content, or a single topic is fragmented across files unnecessarily | Merge — consolidate into one doc, delete the duplicates, update all links | | Orphaned | Doc exists on disk but is not referenced by sidebar or any other doc | Evaluate: add to sidebar, merge into another doc, or delete | | Accurate | Doc matches current code | Leave alone |

Also check whether the doc site itself is complete:

• Is there an index/home page?
• Is there a sidebar/navigation config?
• Does the sidebar reference files that don't exist?
• Are there essential infrastructure files missing (e.g., `index.

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OpenGHz
• Source: OpenGHz/AgentSkills
• License: MIT

Install and usage instructions live in the source repository linked above.