update-docs

Original：🇺🇸 English

Translated

Analyse code changes since the last docs update and refresh the project's documentation files. Use when code has changed and documentation needs to be updated, after implementing new features, or before a milestone commit.

3installs

Sourcea-green-hand-jack/ml-research-skills

Added on2026-05-02

NPX Install

npx skill4agent add a-green-hand-jack/ml-research-skills update-docs

SKILL.md Content

View Translation Comparison →

Update Docs Workflow

Use this workflow whenever code has changed and the project documentation needs to be brought up to date. The agent uses

git

to detect what changed since the last documentation commit, analyses the diff, and updates only the affected docs.

This workflow is project-agnostic: it auto-detects the project root and documentation location.

Step 1 — Orient: detect the project

// turbo Run the following to establish the project root and basic structure:

bash

# Project root and current branch
git rev-parse --show-toplevel && git branch --show-current

# Last 5 commits (so we can pick the baseline)
git log --oneline -5

Then find where the documentation lives:

bash

# Look for common doc directory patterns
find "$(git rev-parse --show-toplevel)" -maxdepth 3 -type d \
  \( -name "docs" -o -name "doc" -o -name "wiki" -o -name "pages" \) \
  ! -path "*/.git/*" ! -path "*/node_modules/*" ! -path "*/.venv/*"

# Also check for top-level markdown files
find "$(git rev-parse --show-toplevel)" -maxdepth 1 -name "*.md" -type f

From the results, identify:

$ROOT
: the git root directory
$DOCS_DIR
: where the documentation files are (e.g.
```
docs/src/
```
,
```
docs/
```
,
```
wiki/
```
)

If

$DOCS_DIR

cannot be determined automatically, ask the user: "Where are your documentation files? (e.g.
docs/
,
docs/src/
, or
README.md
only)"

Step 2 — Find the baseline commit

// turbo Find the most recent commit that touched the documentation directory:

bash

git log --oneline --all -- "$DOCS_DIR" | head -5

Note the first hash — call it

<baseline>

. This is the last point in time when docs were current.

If no doc commits exist, use the initial commit as baseline:

bash

git log --oneline --all | tail -1

Step 3 — Get the code diff since the baseline

// turbo First, a compact summary of what changed in source code (not docs):

bash

git diff <baseline> HEAD --stat -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

If the diff is manageable, get the full diff:

bash

git diff <baseline> HEAD -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

Tip: If the diff exceeds ~400 lines, analyse it file by file using:
bash
git diff <baseline> HEAD -- path/to/file.py
Focus on: new/deleted classes or functions, changed method signatures, new modules, changed configuration keys, new data files.

Step 4 — Discover existing documentation structure

Read the documentation files discovered in Step 1. Understand:

What topics each file covers
What module/component/concept each file documents
The writing style (language, heading level, use of code blocks, tables)

Maintain the same style and language as the existing docs when making edits.

Step 5 — Map changes to affected docs

For each changed file or module, determine which documentation file(s) need updating.

General mapping heuristics (adapt to the specific project structure):

Type of code change	What to update
New class or module added	Add it to whichever architecture/overview doc covers that layer; update dependency diagrams
Class or function deleted	Remove or strike from all docs that mention it
Method signature / parameter changed	Update code examples, parameter tables
New config key or environment variable	Update configuration docs
New external dependency added	Update setup/installation docs
Data schema changed (DB, JSON, Pydantic, etc.)	Update data model docs
New CLI command or flag	Update CLI reference / usage docs
Behaviour change (algorithm, business logic)	Update design/architecture docs
New test coverage (major new tests)	No doc update usually needed unless testing guide exists

Step 6 — Make surgical edits to affected docs

Update only the sections that are out of date. Do not rewrite sections that are still accurate.

Edit rules:

Add new items (classes, methods, parameters, config keys) that appeared in the diff
Remove or revise descriptions of things that were renamed, deleted, or refactored
Update flow diagrams, step-by-step pipelines, and tables to reflect new reality
Preserve all sections not touched by the diff — no gratuitous rewrites
Match the writing style of the existing doc exactly (language, formatting, code fence style)

Step 7 — Summarise changes and optionally commit

After all edits, display a brief summary:

Which doc files were modified
What was added / removed / updated in each

Then ask the user: "文档已更新。是否要将这些改动提交到 Git？(Y/n)"

If yes, suggest a commit message in the format:

docs: update <DOCS_DIR> to reflect changes since <baseline-short-hash>

Then run (replace

<DOCS_DIR>

and

<message>

accordingly):

bash

git add <DOCS_DIR> && git commit -m "<message>"

If no, remind the user that all files are already saved and can be committed later with:

bash

git add <DOCS_DIR> && git commit -m "docs: ..."

update-docs

NPX Install

Tags

SKILL.md Content

Update Docs Workflow

Step 1 — Orient: detect the project

Step 2 — Find the baseline commit

Step 3 — Get the code diff since the baseline

Step 4 — Discover existing documentation structure

Step 5 — Map changes to affected docs

Step 6 — Make surgical edits to affected docs

Step 7 — Summarise changes and optionally commit