跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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: 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 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 lint only 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 proposal style).
  • Docs modified only on explicit user approval; doc-refs.json regenerated 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 to oma-translation in diff-sync mode.

lint mode:

  • Style issues grouped by rule / language / file, as markdown summary or --json. Report-only: restructuring goes through oma-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-adds docs/generated/ to .gitignore so generated artifacts are never committed.
  • docs/generated/url-drift.json: lychee-produced URL drift report (written by background lychee spawn; gitignored under the same docs/generated/ rule).
  • lychee: external Rust tool for URL link checking. Detected on PATH; install via brew install lychee or 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), and docs.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, or lint.
  • 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
阅读完整来源 ↗