What happens if a file has no existing docs?

The tool detects the file language from its extension and applies the appropriate doc style or adds a first docblock that matches the language's conventions.

Are README.md, CHANGELOG.md, or LICENSE touched?

No. The workflow explicitly avoids modifying these files.

How is the final output delivered?

A concise report is produced listing modified files, docblocks added/updated, and summary counts.

update-docs

Scanned

npx machina-cli add skill anilcancakir/claude-code-plugins/update-docs --openclaw

Files (1)

SKILL.md

1.1 KB

Documentation Update Task

Update documentation for all uncommitted code changes.

Steps

Run git diff --name-only to identify modified files
For each code file:
- Detect existing documentation style (see references/doc-patterns.md)
- Find new/modified functions, classes, methods
- Add or update documentation blocks
If /docs folder exists:
- Check if changed code has corresponding docs
- Update affected documentation files
- Do NOT modify README.md, CHANGELOG.md, LICENSE
Report all changes made

Reference Documents

For documentation patterns by language, read:

references/doc-patterns.md - Format examples for each stack

Documentation Style Matching

Always match the existing documentation style in the file:

If PHPDoc exists, use PHPDoc
If JSDoc exists, use JSDoc
If no existing docs, detect from file extension

Output Requirements

Return a report listing:

Files modified
Docblocks added/updated
Summary counts

Source

git clone https://github.com/anilcancakir/claude-code-plugins/blob/main/pre-commit-flow/skills/update-docs/SKILL.mdView on GitHub

Overview

Automatically syncs inline documentation with code changes. It scans for modified files, detects the current documentation style (PHPDoc, JSDoc, or language-based), and updates or adds docblocks for new or altered functions, classes, and methods. This helps maintain accurate docs and speeds up code reviews.

How This Skill Works

Using git diff --name-only, it identifies modified files, then scans each code file to detect new or changed functions, classes, and methods. It chooses the existing documentation style (PHPDoc, JSDoc, or language-based) by consulting references/doc-patterns.md, and adds or updates the relevant docblocks. If a /docs folder exists, it updates affected docs and reports all changes, while never touching README.md, CHANGELOG.md, or LICENSE.

When to Use It

After coding changes that introduce or modify functions, classes, or methods
Before submitting a PR to ensure docs reflect the latest changes
When documentation lags behind code in multi-language repos
When a /docs folder exists and needs syncing with code changes
During code reviews to verify docblocks match the existing style

Quick Start

Step 1: Run git diff --name-only to identify modified files
Step 2: For each code file, detect existing doc style and update/add docblocks
Step 3: If /docs exists, verify and update corresponding docs; review the generated report

Best Practices

Always align new/updated docblocks with the existing style (PHPDoc, JSDoc, etc.) as per references/doc-patterns.md
Use git diff --name-only to scope changes and focus only on touched files
Do not modify README.md, CHANGELOG.md, or LICENSE as required by the workflow
Ensure every modified symbol (function, class, method) has an appropriate docblock
Generate and review the final report that lists modified files, docblocks updated, and counts

Example Use Cases

Python: update docstring for modified compute() in src/utils/math.py
PHP: add PHPDoc block for new method in app/Services/UserService.php
JavaScript: insert JSDoc for updated class in src/components/Chart.js
Java: generate Javadoc for changed method calculateTotal in src/finance/Invoice.java
TypeScript: align interface comments for modified model.ts

Frequently Asked Questions

Add this skill to your agents