关于 oma-docs
oma-docs 是用于维护文档与仓库行为一致的文档维护 skill，面向引用验证、差异同步和翻译维护。它可通过 oma docs CLI 检查或报告问题，并按授权范围处理文档修正。
主要功能
- 01验证文档引用
- 02按代码差异同步文档
- 03检查本地化内容偏差
- 04检查本地化文案风格
- 05汇总发现与未完成检查
适用场景
- 01验证仓库文档中的文件引用
- 02根据代码变更更新文档
- 03检查翻译内容是否与源文一致
- 04对本地化文案进行风格检查
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/oma-docs确认已加载。
附带文件resources/commands.md
详细介绍
文档维护
调度
目标
使文档与仓库行为保持一致，并报告验证限制。
意图特征
检查引用、根据代码差异更新文档、识别翻译偏差，或检查本地化文本的风格。
适用场景
仓库文档验证、基于差异的同步和翻译维护。
不适用场景
- 一般性源代码研究 → oma-search。
- 应用实现 → 对应的专业工具。
- 翻译已知文本 → oma-translation。
预期输入
模式（verify、sync、i18n 或 lint）、目标路径或差异范围，以及获准的编辑范围。未指定模式时使用 verify。
预期输出
包含路径和证据的发现、请求时获准的补丁，以及尚未解决的检查项。CLI 报告与宿主撰写的解读应保持区分。
依赖项
oma docs CLI、用于基于差异开展工作的 Git，以及仓库文档。lychee 可选，用于验证 URL。读取 resources/commands.md，了解所选模式的标志和输出文件。
结构流程
转换
verify：提取并解析引用，然后总结报告。sync：获取候选项，阅读相关文档和差异，并且只应用获准的修正。i18n/lint：报告偏差或风格问题；对于获准的修正，使用 oma-translation。- 仅审阅的请求应生成提案。现有的、范围明确的编辑请求已授权应用这些修正，无需再逐文件征求批准。
失败与恢复
| 失败 | 恢复 |
|---|---|
| 缺少 CLI | 首先说明自动检查不可用，然后仍然进行人工检查：列出目标 Markdown 文件，提取 [text](path)、 和 href/src 目标，逐一以其所在文件为基准解析，并报告哪些解析后的路径不存在。跳过 http(s) URL，并注明这些 URL 未经验证。将结果标记为“人工检查 — 未运行 oma docs verify”；绝不要将其称为 CLI 输出，也不要将安装 CLI 设为前置条件 |
| 缺少 lychee 或 URL 扫描不完整 | 报告核心结果和未经验证的 URL 范围 |
| 无法解析某个文档 | 记录跳过的文件，并继续检查其他文档 |
| 补丁无法应用 | 重新读取受影响的当前内容，并进行等效且获准的修正 |
| 索引写入失败 | 报告失败；不要声称索引或检查已完成 |
退出
报告已验证的发现、所做的编辑和剩余问题。引用扫描无误并不能证明语义正确或翻译质量完整。
逻辑操作
标准命令流程
- 根据请求选择模式、路径/差异和授权范围。只读取
resources/commands.md中匹配的部分。 - 根据具体情况运行
oma docs verify --json、oma docs sync <range> --json、oma docs i18n --json或oma docs lint --json。对于 sync，使用请求指定的范围；否则使用已暂存的更改，然后使用HEAD~1..HEAD。 - 检查结构化结果。根据当前代码和文档上下文验证每项拟议修正。从补丁和报告中排除包含机密的文件和值。
- 应用用户或分配的任务已授权的修正。在进行中的 OMA 文档同步工作流中，先使用
docs.sync-patch-approval记录每个补丁实际执行的应用/跳过操作、理由和证据；将instanceId和验证--instance绑定到文档路径及当前补丁修订版本（工作流步骤 4 规定命令模板）。现有授权仍然有效。仅在缺少重要决策或涉及新范围时才询问；等待期间继续处理互不依赖的工作。 - 编辑后重新运行受影响的检查，并记录剩余失败。需要时，在一批补丁完成后重新生成一次引用索引。
资源范围和效果
验证会重新生成 docs/generated/doc-refs.json；可选的 URL 结果会写入 docs/generated/url-drift.json。同步的 CLI 会输出候选数据；宿主会起草并应用补丁。i18n/lint 命令仅报告结果。只有在启用 docs.auto_verify 时，工作流钩子才会运行，且仅发出警告。
防护措施
- 遵循
../_shared/core/execution-policy.md中的授权与完成要求。 - 对仅供审查的请求保持只读，且将更改限制在指定差异或验收标准范围内。
- 不要在差异报告中暴露包含机密的文件（
.env*、私钥、凭据）。 - CLI 会生成结构化数据；宿主负责自然语言综合。不要虚构 CLI 检查结果，也不要从文档 CLI 调用供应商的 LLM API。
- 遵守忽略块、
oma-docs: skip和已配置的排除项。缺失的 Git 忽略运行时输出应跳过，而不是视为失效引用。 - 应用本地化更正时，保留语言、术语和占位符。
参考资料
- 模式命令、标志和输出：
resources/commands.md（仅限所选操作）。 - 翻译：
../oma-translation/SKILL.md（本地化更正）。 - 授权：
../_shared/core/execution-policy.md（尚未提供时）。
评论
支持 Markdown