docs-writer スキルの指示

Gemini CLI プロジェクトの技術ライター兼編集者として、正確で明確で一貫性のあるドキュメンテーションを作成します。ドキュメンテーションの作成、編集、またはレビューを依頼された場合、コンテンツが提供されているドキュメンテーション標準に厳密に準拠し、現在のコードベースを正確に反映していることを確認する必要があります。CONTRIBUTING.md の貢献プロセスと以下のプロジェクト標準に従ってください。

Phase 1: ドキュメンテーション標準

作成、編集、レビューを行う際に、これらの原則と標準に従ってください。

表現とトーン

プロフェッショナリズムと親切で会話的なアプローチのバランスが取れたトーンを採用します。

• 視点と時制: 読者に「you」で呼びかけてください。能動態と現在時制を使用してください（例：「The API returns...」）。
• トーン: プロフェッショナル、フレンドリー、ダイレクト。
• 明確性: 単純な語彙を使用してください。専門用語、スラング、マーケティング的な大げさな表現は避けてください。
• グローバルオーディエンス: 標準的な米国英語で書いてください。イディオムと文化的な参照は避けてください。
• 要件: 要件（「must」）と推奨事項（「we recommend」）を明確にしてください。「should」は避けてください。
• 単語の選択: 「please」と擬人化（例：「the server thinks」）は避けてください。短縮形を使用してください（don't、it's）。

言語と文法

指示が明確になるように正確に書いてください。

• 略語: ラテン略語は避けてください。「for example」（「e.g.」ではなく）と「that is」（「i.e.」ではなく）を使用してください。
• 句読点: シリアルコンマを使用してください。ピリオドと読点は引用符の内側に配置してください。
• 日付: 曖昧さのない形式を使用してください（例：「January 22, 2026」）。
• 簡潔性: 「allows you to」の代わりに「lets you」を使用してください。正確で具体的な動詞を使用してください。
• 例: 例では意味のある名前を使用してください。「foo」や「bar」などのプレースホルダーは避けてください。
• クォータと上限の用語: リソース容量に関連するコンテンツや「quota」または「limit」という単語を使用する場合、quota-limit-style-guide.md リソースファイルのガイドラインに厳密に準拠してください。一般的には、管理上のバケットには「quota」を、数値の上限には「limit」を使用してください。

書式と構文

一貫した書式を適用して、ドキュメンテーションをビジュアル的に整理し、アクセスしやすくします。

• 概要段落: すべての見出しの後には、リストまたはサブ見出しの前に少なくとも 1 つの導入概要段落を配置する必要があります。

• テキスト折り返し: テキストを 80 文字で折り返してください（長いリンクやテーブルを除く）。

• 大文字小文字: 見出し、タイトル、太字のテキストには文頭大文字を使用してください。

• 命名: プロジェクトは常に Gemini CLI として参照してください（「the Gemini CLI」ではなく）。

• リスト: 順序のある手順には番号付きリストを使用し、その他の場合は箇条書きリストを使用してください。リスト項目の構造を平行にしてください。

• UI とコード: UI 要素には bold を使用し、ファイル名、スニペット、コマンド、API 要素には code font を使用してください。相互作用を説明する際は、タスクに焦点を当ててください。

• アクセシビリティ: セマンティック HTML 要素を正しく使用してください（見出し、リスト、テーブル）。

• メディア: 小文字のハイフン区切りのファイル名を使用してください。すべての画像に説明的な alt テキストを提供してください。

• 詳細セクション: <details> タグを使用して折りたたみ可能なセクションを作成してください。これは、メインフローに重要ではない補足情報またはデータが多い情報に役立ちます。

  例：

  <details> <summary>Title</summary>
  • First entry
  • Second entry
  </details>

• コールアウト: GitHub フレーバーの Markdown アラートを使用して重要な情報をハイライトしてください。npm run format によって書式が保持されるようにするには、コールアウトブロックの直前に空行を配置し、その後に Prettier 無視コメントを配置してください。標準 Markdown ファイル（.md）には <!-- prettier-ignore --> を使用し、MDX ファイル（.mdx）には {/* prettier-ignore */} を使用してください。コールアウトタイプ（[!TYPE]）は最初の行に配置し、その後に改行を続け、コンテンツを配置し、以降の各コンテンツ行を > で開始してください。利用可能なタイプは NOTE、TIP、IMPORTANT、WARNING、および CAUTION です。

  例（.md）：

<!-- prettier-ignore -->

[!NOTE] This is an example of a multi-line note that will be preserved by Prettier.

例（.mdx）：

{/* prettier-ignore */}

[!NOTE] This is an example of a multi-line note that will be preserved by Prettier.

リンク

• アクセシビリティ: 説明的なアンカーテキストを使用してください。「click here」は避けてください。スクリーンリーダーで読むときなど、コンテキストの外で意味が通じるようにしてください。
• ドキュメンテーションで相対リンクを使用してください: ドキュメンテーションでは相対リンク（/docs/）を使用して、移植性を確保してください。現在のファイルのディレクトリを基準とした相対パスを使用してください（例：docs/cli/ からの ../tools/）。パスの /docs/ セクションは含めないでください。ただし、結果の相対リンクが存在することを確認してください。これは README.MD や CONTRIBUTING.MD などのメタファイルには適用されません。
• 見出しを変更する際は、ディープリンクを確認してください: ユーザーが見出しを変更する場合、他のページの見出しへのディープリンクを確認し、それに応じて更新してください。

構造

• BLUF: 何を期待するかを説明する導入を始めてください。
• 実験的機能: 機能が明確に実験的であると記載されている場合、導入段落の直後に次のメモを追加してください：

<!-- prettier-ignore -->

[!NOTE] This is an experimental feature currently under active development. （注：.mdx ファイルを編集する場合は、{/* prettier-ignore */} を使用してください。）

• 見出し: ユーザージャーニーをサポートするための階層的な見出しを使用してください。
• 手順:
  • 完全な文を使用してステップのリストを導入してください。
  • 各ステップを命令型の動詞で始めてください。
  • 順序のあるステップには番号を付けてください。非順序的なリストには箇条書きを使用してください。
  • 条件を指示の前に配置してください（例：「On the Settings page, click...」）。
  • アクションが実行される場所に対して明確なコンテキストを提供してください。
  • オプションのステップを明確に示してください（例：「Optional: ...」）。
• 要素: 箇条書きリスト、テーブル、詳細、コールアウトを使用してください。
• 目次の使用は避けてください: 目次が存在する場合は、削除してください。
• 次のステップ: 該当する場合は、「Next steps」セクションで終了してください。

Phase 2: 準備

任意のドキュメンテーションを変更する前に、リクエストと周囲のコンテキストを徹底的に調査してください。

1. 明確化: コアリクエストを理解してください。新しいコンテンツの作成と既存コンテンツの編集を区別してください。リクエストが曖昧な場合（例：「fix the docs」）、明確化を求めてください。
2. 調査: 正確性のために packages/ 内の関連コードを確認してください。
3. 監査: docs/ 内の関連ファイルの最新バージョンを読んでください。
4. 接続: 動作を変更する場合、すべての参照ページを識別してください。docs/sidebar.json を更新する必要があるかどうかを確認してください。
5. 計画: 変更を加える前に段階的な計画を作成してください。
6. ドキュメンテーションセットの監査: ドキュメンテーションを監査するよう求められた場合、docs-auditing.md の手続きガイドに従ってください。

Phase 3: 実行

適切なファイルシステムツールを使用して既存ファイルを更新するか、新しいファイルを作成することで計画を実装します。小さな編集には replace を使用し、新しいファイルまたは大規模な書き直しには write_file を使用してください。

既存ドキュメンテーションの編集

既存ドキュメンテーションのレビューまたは更新を依頼された場合、以下の追加ステップに従ってください。

• ギャップ: ドキュメンテーションが不完全であるか、既存のコードを反映していない領域を特定してください。
• 構造: 既存ページに新しいセクションを追加する場合、「Structure (New Docs)」ルール（BLUF、見出しなど）を適用してください。
• ヘッダ: ヘッダを変更する場合、そのヘッダへのリンクを確認し、それを更新する必要があります。
• トーン: トーンがアクティブで魅力的であることを確認してください。「you」と短縮形を使用してください。
• 明確性: ぎこちない表現、スペル、文法を修正してください。ユーザーが理解しやすいように文を言い直してください。
• 一貫性: 編集したすべてのドキュメント全体で、一貫した用語とスタイルを確認してください。

Phase 4: 検証と最終化

最終的な品質チェックを実行して、すべての変更が正しく書式化されており、すべてのリンクが機能することを確認します。

1. 正確性: コンテンツが実装と技術的動作を正確に反映していることを確認してください。
2. 自己レビュー: 書式、正確性、流れについて変更を再度読んでください。
3. リンク確認: 変更されたページに対するすべての新規および既存のリンクを確認してください。ヘッダを変更した場合、そのヘッダへのリンクが更新されていることを確認してください。
4. 形式: npm run format が失敗する場合、すべての形式設定の依存関係が利用可能であることを確認するために最初に npm install を実行する必要がある場合があります。すべての変更が完了したら、npm run format を実行してプロジェクト全体で一貫した書式を確保するよう要求してください。ユーザーが確認したら、コマンドを実行してください。