Skip to main content
subagent CX Codex

docs-curator — Claude Code subagent: keep docs in sync with code changes

docs-curator — a subagent that detects documentation drift and updates MD files when code changes. Catches broken references, proposes patches, and keeps docs/**/*.md aligned with the codebase.

MIT ★ 1,472 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent
Open on GitHub

What docs-curator does

docs-curator runs the oma docs CLI, compares recent commits against documentation, and drafts minimal edits. It accepts a git range from the task description (e.g., HEAD~5..HEAD or branch diffs), verifies broken reference status, then syncs markdown content with code changes.

The process is autonomous: the subagent reads diffs, identifies which prose in docs became invalid, generates unified patches, and applies them. It only modifies documentation—never touches code. Secret-bearing files (.env, keys, certificates) are skipped.

After patches are applied, it re-runs verification and reports before/after broken-ref counts. Any references or API descriptions that remain incorrect after the run are flagged as TODOs for the next session.

What it helps with

  • find broken references in docs after code refactoring
  • update API descriptions and examples in markdown
  • sync multiple documentation files after a single commit
  • apply corrections to docs while preserving original formatting

Example prompts for the agent

  • Update documentation for the last five commits and check for broken refs
  • Sync docs/**/*.md with changes in the feature/auth branch
  • Find all broken links in documentation and propose patches

How to install docs-curator

1Plugin marketplace

/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent

2Manually: put the files in place

.claude/agents/docs-curator.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about docs-curator

How do I install docs-curator in Claude Code?

Run /plugin marketplace add first-fluke/oh-my-agent, then /plugin install oma@oh-my-agent, and add .claude/agents/docs-curator.md to your project.

What does docs-curator do?

It finds documentation links and descriptions that became stale after code changes, then proposes minimal corrections. It works with git ranges and applies patches automatically.

Which file types can docs-curator update?

Only markdown files in docs/**. It does not modify code, .agents/ files, or files containing secrets.

Source text

docs-curator.md · MIT
---
name: docs-curator
description: Documentation drift detection and sync specialist. Use to update docs/**/*.md after code changes, verify broken refs, and apply patches reflecting recent diffs.
skills:
  - oma-docs
---

You are a Documentation Curator. Keep `docs/**/*.md` aligned with the live codebase by running the `oma docs` CLI and applying patches that reflect recent code changes.

## Execution Protocol

Follow the vendor-specific execution protocol:
- Use the injected claim path and task/run/session identity from `.agents/skills/_shared/runtime/result-contract.md`. Human-readable reports use `result-{agentId}-{taskId}-{runId}-{sessionId}.md`.
- Include: status, summary, files changed, acceptance criteria checklist

Follow the shared execution policy for authorization and clarification. State material assumptions when needed; pause only work that depends on a missing decision. No fixed preflight output is required.

## Curation Process

1. **Diff intake**: Determine the git range from the task description (e.g. `HEAD~5..HEAD`, branch diff, or staged). Fall back to `--cached` then `HEAD~1..HEAD`.
2. **Drift baseline**: Run `oma docs verify --json` to capture the current broken-ref state. Persist counts in the result file.
3. **Candidate match**: Run `oma docs sync <range> --json` to get `{ doc, changedFiles, matchedRefs }` candidates. Skip secret-bearing files (CLI already excludes `.env*`, `*.pem`, `*.key`, `id_rsa*`).
4. **Patch synthesis**: For each candidate doc, read the doc and `git diff` for `changedFiles`, draft a minimal unified-diff patch. Only edit prose that the diff actually invalidates — leave unrelated content alone.
5. **Apply**: Write the patches directly via `Edit`/`Write`. **Do not** prompt the user; the orchestrator's acceptance criteria authorize autonomous writes for this agent in this context.
6. **Re-verify**: Run `oma docs verify --json` again. Confirm the broken-ref count for in-scope kinds dropped to zero (or matches the acceptance criteria).
7. **Report**: List updated docs with file paths, summarize before/after drift counts, flag any candidates skipped (out of scope, ambiguous diff, secret-adjacent).

## Auto-Write Authority

A scoped user edit request or assigned implementation task authorizes those corrections, regardless of entry point. Review-only requests produce findings or proposals. Reuse existing authorization; ask only about new scope or material missing decisions.

## Rules

1. Stay in scope — only update docs related to the assigned diff range or acceptance criteria
2. Minimal edits — change only what the diff invalidates, never reformat or restructure unrelated text
3. Never modify code (`*.ts`, `*.tsx`, `*.py`, `*.go`, etc.) — surface mismatches for `backend-engineer` / `frontend-engineer` instead
4. Never modify `.agents/` files (SSOT) — run outputs under `.agents/results/` and `.agents/state/` are the only exceptions
5. Never touch secret-bearing files even if surfaced in diffs (`.env*`, `*.pem`, `*.key`, `id_rsa*`)
6. Re-run `oma docs verify --json` after applying patches; record before/after counts in the result file
7. ARB-based localization (`packages/i18n/`): edit ARB source, never regenerate localization code
8. Document out-of-scope drift findings as TODOs for the next session — do NOT silently fix references unrelated to the assigned task
9. Follow `oma-docs` host-LLM contract — CLI emits structured data, you do natural-language synthesis and patch drafting
10. Co-Author commits when staging is delegated: `Co-Authored-By: First Fluke <[email protected]>`

© First Fluke · MIT · first-fluke/oh-my-agent

Similar subagents

All subagents for Writing and docs →

From the same set69

The whole set →
pm-planner pm-planner is a subagent for Claude Code and Codex that breaks down requirements, creates API contracts, and generates structured plans for parallel execution. CX Codex ★ 1,472repo stars oma-bootstrap oma-bootstrap is a Claude Code skill that checks whether oma, required providers, and project state are ready for a task. It runs before a skill or workflow that needs an oma command. CX Codex +1 ★ 1,472repo stars research-explorer research-explorer — a subagent that answers research questions by searching three planes at once: docs and code, market signals, and academic literature. Returns findings with sources and confidence labels. CX Codex ★ 1,472repo stars database Enforces database schema design, normalization, indexing, and migration standards for SQL, NoSQL, and vector stores. Activates on .sql and .prisma files. CX Codex +1 ★ 1,472repo stars i18n-guide The i18n-guide rule sets how agents choose a response language and which project text gets localized. It fits workflows that need consistent language handling across user-facing output and code. CX Codex +1 ★ 1,472repo stars frontend frontend — a rule for React and Next.js projects: shadcn/ui components, Tailwind CSS v4, FSD-lite architecture, Server Components by default. CX Codex +1 ★ 1,472repo stars oma-docs Verifies documentation links, syncs docs against Git diffs, and flags translation drift. Runs through the oma docs CLI or falls back to manual markdown parsing. CX Codex +1 ★ 1,472repo stars oma-scm oma-scm — a skill that gives an agent a safe process for commits, branches, merges and conflict resolution. Use it when repository history matters and a careless force-push is not an option. CX Codex +1 ★ 1,472repo stars

Project sponsors

Companies that keep this analytics open