OpenClaw ドキュメント
概要
このスキルは、OpenClawの開発者向けドキュメント（API、SDK、CLIツール、統合、クイックスタート、プラットフォームガイド、技術製品ドキュメントなど）の作成、編集、レビューを行う際に使用します。
簡潔で役に立ち、かつ包括的なドキュメントを作成してください。初回成功を迅速に、本番環境では正確に、デバッグ時には簡単にスキャンできることを目指します。
コアモデル
Write the Docsの原則に基づいたOpenClawドキュメントモデルを使用します。
- 開発者が何をしようとしているかを先頭に持ってくる。
- 代替案の前に推奨パスを1つ提示する。
- 実行可能で現実的な例を示す。
- ガイドはタスク指向に、リファレンスは網羅的に。
- 開発者が間違いやすい箇所に、本番環境のリスクを正確に説明する。
- コンセプト、ガイド、APIリファレンス、SDK、テスト、トラブルシューティングを相互にリンクし、読者が再読なしで移動できるようにする。
- ドキュメントを製品ライフサイクルの一部として扱う。実装前または実装と並行してドラフトを作成し、コードとともにレビューし、最新の状態に保つ。
- 各ページを発見可能、アドレス可能、累積的、明示された範囲内で完全、そしてスキムしやすいものにする。
構造
ページタイプを記述する前に選択してください。
- 概要：読者を適切な製品、統合パス、またはガイドに誘導する。
- クイックスタート：最小限の安全な手順で新規ユーザーを動作可能な結果に導く。
- トピックページ：主要なドメインエンティティのエンドツーエンドの概要を提供する。セットアップ、主要なサブトピック、トラブルシューティング、詳細なリファレンスへのリンクを含む。
- ガイド：前提条件から本番環境対応までの1つのワークフローを説明する。
- APIリファレンス：すべてのオブジェクト、エンドポイント、パラメータ、列挙型、レスポンス、エラー、バージョンルールを定義する。
- SDKまたはCLIリファレンス：インストール、認証、コマンドまたはメソッド、オプション、例、障害モードを文書化する。
- テストガイド：サンドボックスのセットアップ、フィクスチャ、テストデータ、シミュレートされた障害、ライブモードの違いを示す。
- トラブルシューティングガイド：症状をチェック、原因、修正にマッピングする。
以下のデフォルトのトピックページ構造を使用します。
- タイトル：主要なエンティティまたはサーフェスに名前を付ける。
- 冒頭の概要：それが何であるか、何を所有し、何を所有しないかを説明する、見出しのない数文から始める。ページ自体が概要インデックスでない限り、
## 概要見出しは追加しない。 - 要件：セットアップに特定のアカウント、バージョン、権限、プラグイン、オペレーティングシステム、または資格情報が必要な場合にのみ含める。
- クイックスタート：推奨されるセットアップパスと最小限の信頼性のある検証方法を示す。
- 設定：サーフェスを使用するために必要な最小限の設定、ユーザーが選択する必要がある一般的なバリアント、および各オプションが設定される場所（CLI、設定ファイル、環境変数、プラグインマニフェスト、ダッシュボード、またはAPI）を示す。
- 主要なサブトピック：読者の意図に基づいて、エンティティの主要な概念、ワークフロー、および決定事項を整理する。各主要サブトピックは独自の見出しの下に配置し、一般的な
## サブトピックセクションでラップしない。 - トラブルシューティング：明示的な
## トラブルシューティング見出しの下で、一般的に観察可能な障害を診断する。 - 関連：ガイド、リファレンス、コマンド、概念、隣接するトピックへのリンク。
トピックページはクイックスタートより長くなる場合がありますが、網羅的なリファレンスにしてはいけません。フィールドテーブル、APIコントラクト、狭い内部実装、レガシーな詳細、およびまれなデバッグワークフローは、エンドツーエンドの概要を中断する場合、リンクされたリファレンスまたはトラブルシューティングページに移動してください。
設定については、タスククリティカルなオプションをインラインに保ちます。完全なオプションリスト、デフォルト、列挙型、生成されたスキーマ、および詳細設定についてはリファレンスドキュメントにリンクします。トピックページ自体がリファレンスでない限り、トピックページに網羅的な設定リファレンステーブルを複製しないでください。
以下のデフォルトのガイド構造を使用します。
- タイトル：実装の詳細ではなく成果に名前を付ける。
- 冒頭：読者が達成できることを1、2文で述べる。
- 始める前に：アカウント、キー、権限、バージョン、ツール、前提条件をリストする。
- パスを選択：読者が決定する必要がある場合にのみオプションを比較する。
- 手順：動詞から始まる見出しとコード、期待される出力、チェックを使用する。
- テスト：統合が機能する最も信頼性の低い証拠を示す。
- 本番環境対応：セキュリティ、冪等性、リトライ、制限、可観測性、移行、クリーンアップをカバーする。
- トラブルシューティング：ワークフローの原因となる箇所の近くに、一般的なエラーを含める。
- 関連項目：概念、APIリファレンス、SDKドキュメント、隣接するガイドへのリンク。
ナビゲーションはユーザーの意図に基づいて維持します。読者がタスクを選択する前に内部の製品分類を理解することを強制しないでください。
ドキュメントライフサイクル
ドキュメントをコードと同じ規律で作成および維持します。
- 不明瞭な製品、API、CLI、または設定設計を明らかにするために、早期にドラフトを作成する。
- リポジトリのレイアウトが許す場合、ドキュメントのソースをそれが記述するコード、設定、コマンド、プラグイン、またはプロトコルの近くに配置する。
- 重複する真実を避ける。同じコントラクトが複数の場所に現れる場合は、正規のページを選び、そこにリンクする。
- 動作、設定、API、CLI、プラグイン、またはトラブルシューティングの変更と同じ変更でドキュメントを更新する。
- 古いドキュメントは削除、リダイレクト、または明確にマークする。間違ったドキュメントは、ドキュメントがないことよりも悪い。
- 適切なレビュー担当者を関与させる：コード所有者（動作）、サポートまたはQA（ユーザーの障害モード）、ドキュメントメンテナー（構造とスタイル）。
- 古いバージョンのガイダンスは、ユーザーに必要な場合のみ保存する。それ以外の場合は、現在サポートされている動作を文書化する。
FAQを無関係な資料の捨て場所として使用しないでください。繰り返し発生する質問は、タスク、コンセプト、トラブルシューティング、またはリファレンスページに昇格させてください。
ライティングスタイル
直接的で実用的な口調で記述します。
- 現在形と能動態を使用する。
- 指示を与えるときは、読者を「あなた」として扱う。
- 短い段落とスキャンしやすいリストを好む。
- 具体的な名詞を使用する：「エージェントプロファイル」「ゲートウェイウェブフック」「プラグインマニフェスト」「セッション状態」。
- 注意点は、それが影響する手順の正確な場所に配置する。
- マーケティング用語、誇大広告、一般的なメリット、曖昧な主張を避ける。
- 最初の実行可能な手順の前に、長い概念的な前置きを避ける。
- 製品に非標準のコントラクトがない限り、一般的な開発者向けの概念を過剰に説明しない。
- OpenClaw固有の専門用語と略語は、最初に使用する前に定義する。
- 見出しには文の大文字小文字を使用する。ただし、OpenClawの製品名、コマンド、または識別子で大文字が必要な場合は除く。
- リンク先またはアクションを説明する説明的なリンクテキストを使用する。「このページ」や「ここをクリック」などの曖昧なリンクは避ける。
- 文化的に固有の慣用句、暴力的な慣用句、ドキュメントの翻訳やスキャンを難しくするジョークを避ける。
- アクセシブルな散文を書く：色、スクリーンショット、視覚的な位置だけに依存して指示を理解させない。
アクションまたはリファレンスサーフェスを説明する見出しを使用します。
- 良い例：「エージェントを作成する」「Slackチャンネルを設定する」「プラグインインストールを修復する」
- 避けるべき例：「仕組み」「内部構造」「重要な注意点」（セクションが本当にその形を必要とする場合を除く）
正確なモーダル言語を使用します。
- 必須の動作には「must」を使用する。
- オプションの機能には「can」を使用する。
- デフォルトのパスには「recommended」を使用する。
- 既知の危険には「avoid」を使用する。
- 「なぜ」を説明するのは、それが開発者の決定を変更する場合のみ。
詳細レベル
ページタイプに応じて詳細を変えます。
- 概要ページ：簡潔に。読者が選択できるようにする。
- クイックスタート：手続き的に。初回成功に必要なものだけを含める。
- ガイド：1つのワークフローに対して完全に。決定事項、副作用、障害処理を含める。
- リファレンス：網羅的に。すべてのフィールド、デフォルト、列挙型、null許容値、制約、レスポンス、エラーを文書化する。
- トラブルシューティング：明確に。読者がブロックされていて、観察可能なチェックが必要だと想定する。
コストが高い間違いには深く掘り下げます。
- 認証とシークレットの処理
- 資金移動、課金、権限、元に戻せないアクション
- ウェブフック、リトライ、重複イベント、順序
- 冪等性と並行性
- サンドボックスと本番環境の違い
- バージョニング、移行、後方互換性
- 制限、レート制限、クォータ、タイムアウト
- エラーコードと復旧パス
- データ保持、プライバシー、コンプライアンスに敏感な動作
開発者がタスクを安全に完了するためにこの詳細が必要な場合、遠くのリファレンスに埋もれさせないでください。
例
テストデータであっても、本番環境を想定した例にします。
- コピー＆ペースト可能な完全なコマンドまたはスニペットを優先する。
- 現実的な変数名と値を使用する。
- プレースホルダーは
<API_KEY>や<CUSTOMER_ID>のように山括弧で明確にマークする。 - コマンドの後に期待される成功出力を示す。
- APIリファレンスでは、レスポンスの形状が重要な場合、完全なリクエストとレスポンスの例を示す。
- コードブロックごとに1つの概念単位を保持する。
- 言語固有のコードフェンスを使用する。
- 必要なセットアップ、認証、エラー処理、クリーンアップを隠すおもちゃの例を避ける。
複数の言語が有用な場合、読者が同等のものを比較できるように、同じシナリオを言語間で維持します。
発見可能性とナビゲーション
すべてのページを、読者がそれを見つけ、リンクし、自分の質問に答えるかどうかを迅速に判断できるように設計します。
- 検索キーワードに一致するゴール指向のタイトルと見出しを使用する。
- 各ページを「ここで何ができるか」に対する簡潔な答えで始める。
- OpenClawドキュメントインデックスに必要なメタデータまたはフロントマターを含める。
- OpenClawドキュメントページを作成または変更する際に、ドキュメントインデックスに参加する場合は、ドキュメントリストのルーティング用に「これを読むべき場合」のヒントを追加する。
- 可能性のあるエントリポイントからリンクする。近くの内部分類ページからのみリンクしない。
- セクション見出しを、Issue、PR、サポート返信、チャット回答からのリンクに対して十分に安定させる。
- チュートリアルと例を前提条件から高度なタスクへと並べる。リファレンスページは、ルックアップに役立つ場合はアルファベット順またはトピック別に並べる。
- ページが意図的に部分的である場合、その範囲を upfront に明記する。
APIリファレンスパターン
エンドポイント、メソッド、オブジェクト、またはコマンドについては、以下を含めます。
- 短い目的の説明。
- 認証または権限の要件。
- リクエストの形状。パス、クエリ、ヘッダー、ボディフィールドを含む。
- パラメータテーブル。型、必須/任意、デフォルト、制約、列挙値、副作用を含む。
- 戻り値の形状。オブジェクトのライフサイクル状態を含む。
- エラーケース。コード、原因、復旧ガイダンスを含む。
- 実行可能なリクエスト例。
- 代表的な成功レスポンス。
- 関連するガイドと隣接するリファレンスページ。
ネストされたオブジェクトについては、子フィールドを親の近くに文書化します。読者が単一のリクエストの形状を理解するためにページをまたいでジャンプする必要をなくします。
検証
ドキュメントの変更を製品変更と同様に検証します。
- 利用可能な場合は、関連するドキュメントビルド、ドキュメントインデックス、フォーマッター、リンクチェッカー、生成ドキュメントチェックを実行する。
- ページがユーザーに実行するよう指示しているコマンド、スニペット、例を、実行可能な場合は実行する。
- スクリーンショット、UIラベル、CLI出力、設定キー、フラグ、デフォルト、エラー、ファイルパスが現在の動作と一致することを確認する。
- API、CLI、設定、生成リファレンス、トラブルシューティングドキュメントについては、散文のみのレビューよりも実行可能なチェックを優先する。
- 検証手順が実行不可能な場合は、何が検証されなかったのか、およびその理由を記載する。
完全性チェック
ページを最終化する前に、以下を確認します。
- 最初の画面で、読者が何を達成できるかがわかる。
- 推奨パスが明確である。
- 前提条件が明示的かつテスト可能である。
- 例が文書化された入力で実行できる。
- ページに明確な対象読者がいる：ユーザー、オペレーター、プラグイン作成者、コントリビューター、またはメンテナー。
- テストモードと本番モードの動作が分離されている。
- セキュリティに敏感な値が例で公開されていない。
- すべての警告が、それが重要となる手順に付随している。
- エッジケースが実装に影響を与える箇所で文書化されている。
- APIフィールドに型、デフォルト、制約、エラーが含まれている。
- トラブルシューティングが観察可能な症状から始まっている。
- 関連リンクが、ページを複製せずに読者が読み進めるのに役立つ。
- サポートを受けたり、Issueを報告したり、貢献したりする場所が、読者の次のステップに関連する場合に記載されている。
- ページが主張する範囲に対して完全であるか、またはその制限が upfront に記載されている。
レビューパス
以下の順序で編集します。
- 繰り返しと一般的な説明を削除する。
- 概念的な背景は、正しく選択するために必要な場合を除き、最初の有用なアクションの下に移動する。
- 受動的または抽象的な表現を具体的な指示に置き換える。
- 見出しを、アウトラインがタスクマップのように読めるまで締める。
- 本番環境の安全性のために、欠落している運用上の詳細を追加する。
- コピー＆ペーストの正確性について例を確認する。
- ガイド、リファレンス、SDK、テスト、トラブルシューティングのサーフェス間にリンクを追加する。
- 発見可能性、アドレス可能性、アクセシビリティ、およびドキュメントをコードとして扱う検証を確認する。