What triggers update-docs?

Explicit user instruction to update docs or a request to sync docs with code changes.

Which files can be updated?

Target human-edited Markdown files such as README.md and docs/, while skipping auto-generated and restricted files unless you explicitly approve.

How are changes scoped?

Updates focus on sections affected by the changes; use git diff/git log to isolate relevant commits and avoid rewriting whole documents.

update-docs

npx machina-cli add skill rohailaltaf/claude-skills/update-docs --openclaw

Files (1)

SKILL.md

3.4 KB

Update Documentation

Update human-edited markdown documentation files after completing a piece of work.

When to Use

Only when the user explicitly requests documentation updates (e.g., "update the docs", "sync documentation", "refresh the readme").

Process

Ask what to review - Before analyzing code, ask the user:
- Uncommitted changes only (staged + unstaged)
- Committed changes (all commits on current branch)
- Both uncommitted and committed changes
- Whole repo (review entire codebase, not just recent changes)
For uncommitted/committed/both:
- Use git diff for uncommitted changes
- For committed changes, review all commits unique to the current branch (use git log main..HEAD or similar)
- Focus documentation updates on what changed
For "Whole repo" option:
- Explore the codebase structure (key directories, main files, entry points)
- Identify features, APIs, and components
- Compare existing documentation against actual code
- Look for undocumented features, outdated information, or missing sections
- This is useful for documentation audits or when docs have drifted significantly from code
Identify documentation files - Search for:
- README.md files (root and nested)
- docs/ or documentation/ folders
- agents.md, claude.md, or similar project-specific docs
- Any other .md files that appear to be human-edited
Filter out auto-generated and special files - Skip:
- Auto-generated documentation (look for generation comments/headers)
- LICENSE, LICENSE.md
- CONTRIBUTING.md
- CHANGELOG.md, HISTORY.md
- CODE_OF_CONDUCT.md
- Files with "auto-generated" or "do not edit" markers
If the user wants these files updated, ask for explicit confirmation first.
Review existing conventions - Before making changes:
- Read the existing documentation style and formatting
- Match the tone (formal vs casual)
- Follow existing heading structures
- Preserve any existing patterns for code examples, links, etc.
If no documentation exists - Work with the user to initialize:
- Ask what documentation they want to create
- Suggest a basic structure based on the project type
- Start minimal and expand based on feedback
Make targeted updates:
- For change-based reviews: only update sections relevant to the changes
- For whole repo reviews: address gaps, outdated info, and missing documentation
- Don't rewrite entire documents unnecessarily
- Add new sections for undocumented features
- Update existing sections if behavior differs from docs
- Remove outdated information

What to Document

Based on the work completed, consider updating:

Features/Usage: New functionality, how to use it, examples
Installation/Setup: New dependencies, configuration options
API Reference: New endpoints, functions, parameters
Architecture: Structural changes, new components
Examples: Working code snippets demonstrating changes

Guidelines

Keep documentation concise and scannable
Use code blocks with appropriate language tags
Prefer examples over lengthy explanations
Link to related documentation rather than duplicating
Maintain consistent formatting with existing docs

Source

git clone https://github.com/rohailaltaf/claude-skills/blob/main/update-docs/skills/update-docs/SKILL.mdView on GitHub

Overview

Update human-edited markdown documentation files after completing a piece of work. The skill helps keep docs aligned with code changes, whether you’re refreshing a README, syncing API docs, or auditing an entire repository. It applies targeted changes based on what actually changed in code and user requests.

How This Skill Works

Identify relevant Markdown files (README.md, docs/ and project-specific docs) and determine sections that need updates. Filter out auto-generated or restricted files, review existing conventions, and apply targeted updates that reflect code changes. Use git diff for uncommitted changes and git log to isolate commits on the current branch, focusing only on what changed.

When to Use It

The user explicitly requests documentation updates (e.g., 'update the docs').
Code changes have been completed and docs must reflect them.
Refreshing or syncing the README or docs after a feature release.
Audit the entire repository to find outdated or missing documentation.
Document undocumented features or behavior drift between code and docs.

Quick Start

Step 1: Clarify scope and which changes to review (uncommitted, committed, or whole repo).
Step 2: Locate relevant Markdown docs (READMEs, docs/ directories, project docs).
Step 3: Update impacted sections, following existing styles and conventions; avoid boilerplate.

Best Practices

Match tone and structure to existing docs.
Review only sections affected by changes; avoid rewrites.
Use code blocks with examples and link to related docs.
Prefer updating existing sections over adding duplicates.
Verify exclusions: auto-generated and restricted files unless explicitly approved.

Example Use Cases

Update API usage section after a new endpoint is added.
Sync docs following a bug fix that changes behavior.
Add a missing README section for a new module.
Audit and trim outdated notes across docs/ folders.
Document deployment or setup option changes after configuration updates.

Frequently Asked Questions

Add this skill to your agents