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.
first-fluke · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add first-fluke/oh-my-agent --skill oma-docs技能说明
name: oma-docs description: 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.
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: trueand runsoma docs verify --jsonat 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 git diff, to discover which docs reference the changed files and may need updating.
- After updating English source docs (
web/docs), to find translations (web/i18n/{lang}/...) that drifted or went missing. - Before a docs release, to lint CJK translations for content-level anti-patterns.
- Routine drift check on any docs-heavy repo.
When NOT to use
- Generating docs from scratch for undocumented features → v2 create mode.
- Actually translating or restructuring docs → use
oma-translation(oma docs i18n/oma docs lintonly detect; they never edit translations). - Symbol-level semantic drift (function signature changes not reflected in prose) → v2 L3 mode.
- CI-blocking enforcement → v2 block mode (v1 is warn-only).
- Explaining a code change as an educational document → use
oma-explanation(this skill detects drift; it does not author explainers).
Expected inputs
verify mode: Optional glob path (default **/*.md), optional --json flag, optional --report-file <path>.
sync mode: Optional git diff range (default --cached, fallback HEAD~1..HEAD).
i18n mode: Optional --min-severity <CRITICAL|HIGH|MEDIUM|LOW> (default MEDIUM), optional --json.
lint mode: Optional --locales <list> (comma-separated CJK locales for the cjk-em-dash rule, default ko,ja,zh), optional --json. The default wrong-language rule always scans every locale under web/i18n/ and is not narrowed by --locales.
Expected outputs
verify mode:
- Markdown drift report to stdout (default), or raw JSON with
--json, or full markdown written to file with--report-file. - Exit code 0 if clean, 1 if any broken refs found.
sync mode:
- Per-doc patch proposals drafted by the host LLM from the CLI's candidate-doc list, confirmed per doc (
[y] apply [n] skip [d] diff [s] full proposalstyle). - Docs modified only on explicit user approval;
doc-refs.jsonregenerated after applies.
i18n mode:
- Per-pair structural drift signals (line count, heading count, EN-newer recency flag) with severity, as markdown summary or
--json. Report-only: drifting pairs are handed tooma-translationin diff-sync mode.
lint mode:
- Style issues grouped by rule / language / file, as markdown summary or
--json. Report-only: restructuring goes throughoma-translation.
Dependencies
cli/commands/docs/extract.ts: markdown AST + L2 pattern extractor.cli/commands/docs/resolve.ts: deterministic broken-ref checker.cli/commands/docs/reporter.ts: deterministic markdown/JSON report renderer (no LLM call; host LLM does narrative synthesis).cli/commands/docs/sync-propose.ts: git diff intake, reverse lookup, candidate-doc selector with secret redaction (no LLM call; host LLM drafts patches).cli/commands/docs/i18n-drift.ts: EN↔translation structural drift detector (line/heading counts, last-commit recency; no LLM call).cli/commands/docs/lint-i18n.ts: translated-doc linter for selected-locale CJK em-dash style and all-locale wrong-language placeholders (no LLM call, no auto-fix).docs/generated/doc-refs.json: single-direction reference index, regenerated on every verify run. Gitignored — the CLI force-addsdocs/generated/to.gitignoreso generated artifacts are never committed.docs/generated/url-drift.json: lychee-produced URL drift report (written by background lychee spawn; gitignored under the samedocs/generated/rule).lychee: external Rust tool for URL link checking. Detected on PATH; install viabrew install lycheeor see https://github.com/lycheeverse/lychee#installation. Optional but recommended..agents/oma-config.yaml:docs.auto_verify(workflow hook opt-in),docs.check_urls(URL checking on/off, default true), anddocs.exclude(glob list of markdown trees the walker must not scan — benchmark artifacts, translation mirrors, etc.; default[]) toggles.
Control-flow features
- Mode is selected from the first argument:
verify,sync,i18n, orlint. - verify: extract → resolve → report (fully deterministic CLI; host LLM adds narrative summary on top of the JSON/markdown output).
- sync: git diff → reverse lookup → candidate list (CLI) → host-LLM patch proposals → interactive accept/reject.
- i18n / lint: fully deterministic CLI reports; host LLM routes drifting pairs / style issues to `oma