docs-writing

ドキュメントの作成

• 対象: ドキュメントサイト、API リファレンス、ドキュメントサイトのチュートリアル、ハウツードキュメント、既存の README を対象に、技術ドキュメントの品質（Diataxis のドキュメントタイプ、文体、構成、明瞭さ、実行可能なコード、書式、ナビゲーション、コンテンツの健全性、エージェントが読み取りやすいドキュメント）を作成・監査します。
• 対象外: 編集記事形式のブログチュートリアルや記事（外部の ghostwriter スキルでプラットフォーム blog を使用）、ゼロからの README 作成や README 全体の書き直し（readme-creator を使用。文章をその場で修正する README はここで扱います）、AGENTS.md または CLAUDE.md の指示（agents-md を使用）、マーケティングやランディングページのコピー（copywriting を使用）、公開エージェント対応スコアカード（agent-ready を使用）、Next.js の llms.txt／Markdown ルート（seo を使用）、製品独自のエラーメッセージや CLI 出力（dx-audit を使用。このスキルでは、それらを説明するドキュメントを扱います）。

モードの振り分け

• ドキュメントをレビューしますか？ → 監査ワークフロー。
• ページを作成または書き直しますか？ → 執筆ワークフロー。
• ドキュメントを「改善」または「修正」しますか？ → まず監査し、その後自分で修正を適用します。

何よりも先に分類する

ドキュメントタイプによって適用するルールが決まるため、まず各ファイルを分類します。Diataxis の指針に従い、ページが行動（実行）と認知（理解）のどちらを目的とするか、また読者がスキルを習得するのか、スキルを応用するのかを判断します。

	習得（学習）	応用（作業）
行動	チュートリアル	ハウツーガイド
認知	解説	リファレンス

セクションごとに目的が異なるページは混合型です。分割には structure-diataxis を使用します。ファイル名ではなく、読者のタスクに基づいて分類します。README は概要を示すことも、リファレンスとなることもあります。スタートガイドはチュートリアルにも、目標指向のハウツーにもなり得ます。

監査ワークフロー

このチェックリストに沿って進めます。

Docs audit progress:
- [ ] Step 1: Scope to changed files unless a full sweep was requested
- [ ] Step 2: Classify each doc with the compass; name the audience
- [ ] Step 3: Run CRITICAL categories (voice-, structure-), skipping rules the type-gating table excludes
- [ ] Step 4: Run HIGH categories (clarity-, code-)
- [ ] Step 5: Run remaining in-scope categories (format-, nav-, scan-, hygiene-, review-)
- [ ] Step 6: Report per the output contract, by severity

対象となるカテゴリに限り、カテゴリのプレフィックスごとにルールファイルを読み込みます（rules/voice-*.md、次に rules/structure-*.md、……）。修正を適用した後、最終確認の前に、指摘が見つかったルールを再実行します。

執筆ワークフロー

このチェックリストに沿って進めます。

Docs writing progress:
- [ ] Step 1: Pick one Diataxis type per file with the compass; name the audience and what they can do afterwards
- [ ] Step 2: Read the defaults bundles (voice-defaults, clarity-defaults, scan-defaults) plus the structure- and code- rules the type-gating table keeps
- [ ] Step 3: Draft: bottom line up front, quick start for getting-started docs, runnable example per concept, next steps for tutorials and how-tos
- [ ] Step 4: Apply the type-relevant rules to concrete weaknesses in the draft
- [ ] Step 5: Verify: run every example, resolve every link, confirm parameter names and defaults against the implementation; quote the command output

ステップ 5 が完了条件です。例が実行でき、リンクが解決できたらドキュメントを公開できます。「読みやすい」だけでは不十分です。長さはテンプレートではなく、読者が行う作業に合わせます。ページに不要なセクションは、埋めるのではなく削除します。

タイプ別適用ルールの表

これらのルールは、記載されているタイプにのみ適用されます。それ以外の場所で指摘すると、Diataxis の構成に従うよう作成者に求めることになります。

ルール	適用対象
structure-quick-start	スタートガイド、README
structure-next-steps、structure-procedures	チュートリアル、ハウツーガイド
code-multiple-languages	複数 SDK に対応する API のリファレンスおよびハウツーページ
scan-three-column-api	API リファレンス
hygiene-experimental-label、hygiene-planned-label	不安定な機能または未リリースの機能を扱うリファレンスおよびハウツーページ
nav-agent-readable	ドキュメントサイト（単独の README は対象外）

それ以外のルールは、すべてのタイプに適用されます。チュートリアルには voice-defaults の we 使用許可が追加で適用されます。リファレンスページには structure-heading-overview のシグネチャーブロック使用許可が適用されます。

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス	ルール数
1	文体とトーン	重大	voice-	4
2	構成と整理	重大	structure-	9
3	明瞭さと言葉遣い	高	clarity-	5
4	コード例	高	code-	8
5	書式と構文	中〜高	format-	7
6	ナビゲーションとリンク	中〜高	nav-	7
7	スキャンのしやすさと読みやすさ	中	scan-	2
8	コンテンツの健全性	中	hygiene-	6
9	レビューとテスト	低〜中	review-	3

カテゴリごとのルール一覧は rules/_sections.md を参照してください。*-defaults.md ファイル（voice、clarity、scan、review）は、各 2〜5 件の基本チェックを含む複数チェック用バンドルです。

出力契約（監査モード）

## Documentation Audit Findings

### path/to/file.md
- [CRITICAL] `voice-defaults`: Passive voice obscures who performs the action.
  - Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

### path/to/clean-file.md
- ✓ pass

• ファイルごとにグループ化し、各ファイル内では重要度順に並べます。
• 可能な場合は file:line を使用します。
• 各指摘にはルール名、問題点、修正案を記載します。修正案のない指摘は報告対象外です。
• 確認済みで問題のないファイルは ✓ pass と記載します。

注意点

• ドキュメント種別の誤分類は、誤検出の最大の原因です。解説ページにクイックスタートがないことや、リファレンスページに「次のステップ」セクションが求められることは、Diátaxis に反する指摘であり、Diátaxis を支持する指摘ではありません。報告する前に、種別判定テーブルを確認してください。
• *-defaults.md バンドルでは、ファイル名だけでなく、該当するチェック項目（例：「voice-defaults：受動態」）を具体的に示してください。そうしないと、作成者が問題箇所を特定できません。
• 対象範囲に含まれるカテゴリのルールファイルだけを、プレフィックスを使って読み込んでください。対象範囲が確定する前にフォルダー全体を読み込むと、コンテキストがあふれ、CRITICAL の指摘が MEDIUM の指摘に埋もれてしまいます。
• 「should」はバグではありません。Google の現在の用語リストでは、「should」は推奨事項、「must」は要件を表します。「should」が要件を示す文で使われている場合に限り、指摘してください。すべての「should」を指摘すると、誤検出だらけになります。
• 実際に有効そうなサンプルキー（sk_live_... など）は、実際のコードに貼り付けられ、シークレットスキャナーに検出されるおそれがあります。サンプル認証情報には、プロバイダーのテスト用プレフィックス（sk_test_...）または説明を添えたプレースホルダー（YOUR_API_KEY）を使ってください。code-placeholders を参照してください。
• 誰も更新しない手書きの「最終更新日：2024-03-01」は、「放置された」という印象を与え、日付がない場合よりも悪影響です。日付をビルドまたは VCS から取得できる場合に限り、hygiene-update-metadata を推奨してください。
• ドキュメントサイトの各ページ冒頭にある「このガイドは X シリーズの一部です」という文は、サイトがすでに表示しているサイドバーやパンくずリストと重複します。nav-breadcrumb-context は、リポジトリ内の通常の Markdown と、読者が満たしていなければならない前提条件があるページに適用します。
• レビューを依頼されたコンテンツを書き換えてはいけません。ユーザーが「改善」または「修正」と依頼していない限り、問題点を報告し、修正案を提示してください。
• 全体的な確認を明示的に依頼されていない限り、変更されていないファイルは監査しないでください。範囲外の指摘は、本当に対処が必要な問題を埋もれさせます。

関連スキル

• readme-creator：README を一から作成する場合や、全面的に書き直す場合に使います。このスキルは既存の README を監査し、その場で修正します。
• agents-md：AGENTS.md／CLAUDE.md の指示ファイル向けです（読者向けドキュメントではなく、実行を優先するファイル）。
• copywriting：マーケティング、ランディングページ、製品紹介のコピー向けです。
• dx-audit：製品自体のエラーメッセージ、CLI 出力、API の使いやすさを扱います。このスキルは、それらをドキュメントでどう説明するかを対象とします。
• agent-ready：Mintlify／AFDocs、Is Agentic、Is It Agent Ready の契約を扱います。nav-agent-readable はコンテンツのルールです。
• seo：クローラーのポリシー、サイトマップ、ランキング、Next.js の llms.txt／Markdown ルートを扱います。これらは nav-agent-readable が求めるものです。
• オプションの外部スキル ghostwriter（インストール済みの場合）：blog プラットフォームプロファイルを使って作成する、編集記事、チュートリアル、ハウツー記事、ソートリーダーシップ記事、長文記事向けです。
• オプションの外部スキル blodemd（インストール済みの場合）：MDX ドキュメントサイトのひな型作成とデプロイを行います。このスキルは、その中のコンテンツ品質を扱います。

保守専用：evals/evals.json には、このスキルへの変更に関する回帰シナリオが含まれています。ユーザーのタスク中には読み込まれません。