oma-docs について
oma-docsは、リポジトリの動作とドキュメントの整合性を保つための保守スキルです。参照の検証、差分に基づく同期、翻訳の保守に対応し、指摘の報告や許可範囲内での修正を行います。
主な機能
- 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、リポジトリのドキュメントです。URL 検証には lychee を任意で使用できます。選択したモードのフラグと出力ファイルについては、resources/commands.md を参照してください。
構造上のフロー
遷移
verify：参照を抽出して解決し、レポートを要約します。sync：候補を取得し、関連するドキュメントと差分を確認して、許可された修正のみを適用します。i18n/lint：ずれやスタイル上の問題を報告します。許可された修正には oma-translation を使用します。- レビューのみの依頼では、修正案を提示します。範囲を指定した編集依頼がすでにある場合は、ファイルごとに再承認を得なくても、それらの修正を適用できます。
失敗と復旧
| 失敗 | 復旧 |
|---|---|
| CLI がない | 自動チェックを利用できないことを最初に伝えたうえで、手動での確認も続けます。対象となる Markdown ファイルを列挙し、[text](path)、、および href / src の参照先を抽出して、それぞれを含んでいるファイルからの相対パスとして解決し、解決したパスのうち存在しないものを報告します。http(s) 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 に出力されます。Sync の 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（すでに提供されていない場合）。