Use cases at a glance
Documentation is the part of the codebase that falls behind fastest. Code moves, APIs change, README files go stale — and no one has the time to keep every doc in sync by hand. These five agents automate the most time-consuming parts: generating changelogs, flagging stale docs, detecting README drift, summarising API changes, and producing weekly engineering digests.
📝 Changelog Generator
Auto-generate a formatted CHANGELOG.md section from merged PRs and commits since the last release tag. Groups by type: features, fixes, maintenance.
⚠️ Stale Docs Detector
Compare last-modified dates of doc files against the code they document. Flag docs where source code changed more recently than the docs.
📋 README Sync Checker
Detect when key files like package.json or requirements.txt change and flag README sections that likely need updating.
🔀 API Docs Diff
Compare your OpenAPI/Swagger spec between releases. Summarise added endpoints, changed parameters, and removed routes for release notes.
📊 Weekly Engineering Digest
Combine commit activity, PRs merged, issues closed, and open doc debt into a single Friday afternoon team digest sent to Telegram or Slack.
What it can and cannot do
✅ Can do
- Generate changelog entries from commit messages and PR titles
- Group changelog entries by conventional commit type
- Flag docs whose source files were modified more recently
- Detect version number drift between README and package files
- Compare OpenAPI spec files between two git refs
- Output a diff summary as a structured Markdown report
- Send weekly engineering digests via Telegram or Slack
- Link changelog entries to their PRs and issues
❌ Cannot do
- Understand the semantic meaning of doc content
- Rewrite documentation automatically (read-only by default)
- Detect that a doc is factually wrong — only that it may be stale
- Understand diagrams, images, or embedded media in docs
- Push to your repo without a write-enabled token and explicit write step
- Resolve ambiguous conventional commit messages into clear categories
Changelog generator
This is the most-used agent in the docs series. It reads all merged PRs and commits since your last release tag, categorises them by conventional commit prefix (or PR label, if you don't use conventional commits), and outputs a ready-to-paste CHANGELOG.md section.
Conventional commit type mapping
By default OpenClaw maps commit prefixes to these changelog sections:
| Commit prefix | Changelog section | Example |
|---|---|---|
feat: / feature: | ✨ Features | feat: add dark mode toggle |
fix: | 🐛 Bug Fixes | fix: correct pagination offset |
perf: | ⚡ Performance | perf: cache user lookup results |
docs: | 📝 Documentation | docs: update API reference |
chore: / build: / ci: | 🔧 Maintenance | chore: bump Node to v22 |
refactor: | ♻️ Refactoring | refactor: extract auth middleware |
security: / sec: | 🔒 Security | security: patch XSS in comment field |
| (no prefix) | 🔄 Other Changes | Grouped at the bottom |
Add this to your AGENTS.md:
Trigger it manually or on tag push
You can run the changelog agent on demand before each release, or set it to trigger automatically when a new version tag is pushed. For on-demand runs, add a HEARTBEAT that checks for new tags since the last run:
group_by: label and configure your label_map to match your GitHub label names. Entries without a matching label will fall into "Other Changes". You can also set group_by: none to get a flat chronological list.
Stale documentation detector
The stale docs agent compares the git log timestamps of your documentation files against the source files they describe. When a source file is modified more recently than its corresponding doc file, that doc is flagged as potentially stale.
It uses a path_map to link source directories to doc directories. Configure it to match your repo structure:
source: "src/auth/session.ts" → docs: "docs/authentication.md". Mix folder-level and file-level entries in the same path_map.
README sync checker
READMEs drift in three common ways: a version number gets bumped in package.json but not the README, a new required environment variable appears in .env.example but isn't documented, or the installation commands change. This agent watches for those mismatches.
The agent outputs a report like: "package.json version changed from 2.1.0 → 2.2.0 in the last 30 days. README sections 'Installation' and 'Getting Started' were not modified in the same period and may be out of date." It does not rewrite the README — it gives you the context to update it yourself quickly.
API documentation diff
If your project maintains an OpenAPI or Swagger spec, this agent compares the spec between two git refs (typically the last release tag and HEAD) and summarises what changed: new endpoints, removed routes, changed parameters, updated response schemas. Use it as a pre-release checklist item.
breaking_change_detection is true, the agent flags removed endpoints and newly required parameters as breaking changes and surfaces them at the top of the report. This is a heuristic — review the output before publishing release notes.
Non-OpenAPI projects
If you don't use an OpenAPI spec, you can still get a useful diff by pointing the agent at any structured file that tracks your API surface — a GraphQL schema, a TypeScript type file, or even a plain Markdown API reference. Set spec_format: raw and OpenClaw will output a unified diff summary instead of a structured API change report.
Weekly engineering digest
This agent pulls together everything from the developer series into one Friday afternoon report: merged PRs, closed issues, new CVEs from the dependency agent, any stale docs flagged, and CI/CD health from the week. Output it to Telegram, Slack, or email.
0 16 * * 5 — Fridays at 4pm local time. Your team gets the digest before the weekend without it getting buried in Monday's inbox.
HEARTBEAT templates
Copy these into your AGENTS.md under the heartbeats key:
Sample changelog output
Here is an example of what the changelog generator produces for a typical two-week sprint:
FAQ
Can OpenClaw write changelogs automatically?
Yes — but it outputs the generated content as a report for you to review. It does not push to your repo by default. To automate the commit, you'd need a write-enabled token and a write step in your config. We recommend the review-first workflow to avoid mistakes in public-facing docs.
Does my project need to use conventional commits?
No. Conventional commits produce the cleanest grouped changelogs, but you can use group_by: label with GitHub PR labels, or group_by: none for a flat list. Any commit history works.
How does stale documentation detection work?
It compares git log timestamps for doc files against the source files they document. If source code was modified more recently than its corresponding doc, the doc is flagged. It uses your path_map config to connect source paths to doc paths — it cannot infer links between files with very different names.
Can OpenClaw update README files automatically?
It can generate a proposed diff — for example, flagging that the Node.js version in the README doesn't match package.json. Automatically committing changes requires a write-enabled token and explicit write step. Review the diff manually first.