oma-docs
Verify documentation references against the current codebase, propose updates for diff-affected docs, detect i18n translation drift, and lint translated docs for CJK style issues. Use to check if docs still match reality (broken file paths, CLI commands, config keys, env vars, scripts), to surface docs that may need updating after code changes, or to find stale or style-broken translations.
npx skills add first-fluke/oh-my-agent --skill oma-docs --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
- Verifies documentation references against the current codebase to find broken file paths, CLI commands, config keys, env vars, and scripts.
- In sync mode, surfaces doc patches that are affected by a git diff and drafts patches for these docs.
- In i18n mode, detects structural drift between English source docs and translations and reports drift without editing translations.
- In lint mode, lints translated docs for CJK style issues and wrong-language placeholders; reports without auto-fixing.
How it works
- The skill operates in four modes selected by the first argument: verify, sync, i18n, or lint.
- It uses an extractor to regenerate a doc-refs.json index from Markdown files, or builds a reverse index in sync mode.
- It deterministically resolves references or matches changed files to candidate docs; in verify, it renders a drift report; in sync, it outputs candidate docs and delegates patch drafting to a host LLM.
- For i18n and lint, it detects drift or style issues without performing translation edits itself.
- Outputs can be JSON (--json) and/or a file-lived report (--report-file). URL checks may be delegated to lychee when in verify mode.
When to use it
- After refactors, renames, or deletions to identify stale doc references.
- Before releases to confirm docs reflect existing CLI commands, file paths, and config keys.
- After significant diffs to surface docs that reference changed files and may require updates.
- To identify translations that drifted or to lint translated docs for CJK style issues.
What it can touch
- Reads repo Markdown files (**/*.md) to produce doc-refs.json.
- Writes docs/generated/doc-refs.json (regenerated on verify).
- May apply patches only in the sync flow after user approval (via git apply) and related doc edits.
- Interacts with external tools via host LLM for patch drafting and translation routing.
Caveats
- No auto-fix is performed in i18n or lint modes; patches are drafted or suggested for user review.
- The host LLM handles natural-language synthesis; the CLI itself remains deterministic for reporting.
- URL checking is delegated to lychee when enabled; failures or delays in URL checks do not block core reference verification.
# oma-docs - Documentation Drift Detector ## Scheduling ### Goal Detect broken references in repo markdown — default glob `**/*.md` (verify mode), propose LLM-generated patch proposals for docs affected by recent code changes (sync mode), detect structural drift between English source docs and their translations (i18n mode), and lint translated docs for CJK style anti-patterns (lint mode). All modes run on-demand; sync is always interactive. ### Intent signature - User asks to check if docs are up to date, find broken doc links, verify file paths referenced in docs, or detect documentation drift. - User asks to update docs after a code change, propose doc patches for a git diff, or sync affected docs. - User asks whether translations are stale, which i18n docs drifted from the English source, or to lint translated docs for style issues (em-dashes in CJK targets, etc.). - A workflow hook checks `docs.auto_verify: true` and runs `oma docs verify --json` at completion. ### When to use - After a refactor, rename, or file deletion, to find stale references in docs. - Before a release, to confirm that CLI commands, file paths, and config keys in docs still exist. - After a significant gi
- Scheduling
- Goal
- Intent signature
- When to use
- When NOT to use
- Expected inputs
- Expected outputs
- Dependencies
- Control-flow features
- Structural Flow
- Entry
- Scenes
- Transitions
- Failure and recovery
render markdown to stdout. URL link checking is delegated to lychee in the background oma docs verify Narrow to a path or glob (uses minimatch) oma docs verify "docs/**/*.md" oma docs verify cli/README.md Machine-readable output for CI / hooks oma docs verify --json Persist full markdown report to a file (works alongside --json too) oma docs verify --report-file ./drift-report.md
What does the oma-docs skill do?
Verify documentation references against the current codebase, propose updates for diff-affected docs, detect i18n translation drift, and lint translated docs for CJK style issues. Use to check if docs still match reality (broken file paths, CLI commands, config keys, env vars, scripts), to surface docs that may need updating after code changes, or to find stale or style-broken translations.
How do I install it?
Run `npx skills add first-fluke/oh-my-agent --skill oma-docs --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From first-fluke/oh-my-agent, a repository with 1,204 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.