Documentation Maintainer

Keep project documentation aligned with the implementation.

Documentation Maintainer reviews repository code and configuration, finds documentation drift, and updates maintained documentation when requested.

What it does

• Checks documentation changed since the last review.
• Audits all maintained documentation across a repository.
• Updates stale, missing, or contradictory documentation.
• Initializes a complete documentation baseline for a new repository.
• Reviews maintained Mermaid and UML sources against the implementation.
• Validates links, commands, paths, examples, and terminology.

Install

Install directly from GitHub with npx skills:

npx skills add Noah-Martinez/documentation-maintainer-skill

Install globally:

npx skills add Noah-Martinez/documentation-maintainer-skill -g

Install for a specific agent with -a:

npx skills add Noah-Martinez/documentation-maintainer-skill -a codex

Use

Invoke the skill and choose a mode:

Use $documentation-maintainer to check documentation.

Supported modes:

• check-since-update — review changes since the last-doc-generation tag.
• check-full — audit all maintained documentation.
• update-docs — review and update documentation incrementally.
• initialize-docs — create full documentation, then commit it and create the initial baseline tag.

If no mode is specified, the skill uses check-since-update.

Requirements

• Git repository
• Git history for incremental reviews
• last-doc-generation tag for check-since-update and update-docs

Baseline

last-doc-generation points to the repository commit used for the latest documentation generation. It is the authoritative incremental-review baseline, even when its commit is no longer an ancestor after a squash merge.

For incremental work, compare repository snapshots:

git fetch --tags
git diff last-doc-generation HEAD

Do not use git log last-doc-generation..HEAD as the baseline comparison.

First generation

Use initialize-docs when last-doc-generation does not exist. It reviews the whole repository and generates the initial documentation. After reviewing and committing those changes, the maintainer creates the tag on that documentation commit:

git add <documentation-paths>
git commit -m "docs: initialize project documentation"
git tag last-doc-generation HEAD
git push origin last-doc-generation

check-since-update and update-docs require this tag. Use check-full for a read-only full audit when no baseline exists.

Subsequent generations

Use update-docs for recurring incremental updates. After merging the documentation change, move the baseline to the commit representing the new documented state:

git tag -f last-doc-generation <new-baseline-sha>
git push --force origin last-doc-generation

If the change was squash-merged, use the resulting squash commit. Protect this mutable tag so only the documentation process or an authorized maintainer can update it.

Traceability

Optionally record the baseline commit in the project README:

Documentation generated from commit: <commit-sha>
Baseline tag: last-doc-generation

The tag remains authoritative; the commit SHA and date are human-readable traceability only.

License

MIT. See LICENSE.