authoring-api-reference

authoring-api-reference — SKILL.md

バリアント： 標準 · 使用する場面： 公開済みの利用者向け API リファレンスの作成（または改訂）。クライアント開発者が、API リファレンスだけで認証し、初回の呼び出しを成功させ、記載されたすべての操作を統合でき、すべてのエンドポイント、フィールド、エラーが上流の api-spec 契約と一致している状態を目指します（乖離や捏造がないこと）。

概要

このスキルは、優れた公開済みの利用者向け API リファレンスの書き方、つまり API を統合するクライアント開発者が API を呼び出す際に読むドキュメントの作成方法を説明します。ここで扱うのは、作成者の判断力、すなわち調査方法と品質基準であり、セクション一覧ではありません。協力者として、セクションの構成を提供するapi-reference template toolと、オンボーディングの説明、例、慣例を確立された公開 API ドキュメントの実践に基づいて作成するための深掘り調査機能を想定しています。作成者には、すべてのエンドポイント、フィールド、エラーの根拠となるエンジニアリング上のワイヤー契約である上流の api-specが渡されます。また、存在する場合は、各操作の用途という利用コンテキストを示すfeature-specと、認証やバージョン管理のコンテキストを示すarchitecture-docも渡されます。白紙から始めることはありません。達成すべき基準は、開発者がAPI リファレンスだけで認証し、初回の呼び出しを成功させ、すべての操作を正しく使用できること、そしてドキュメントに記載されたすべてのエンドポイント、データ構造、エラーの根拠を api-spec 契約までたどれることです。乖離や捏造があってはなりません。

API リファレンスは、api-spec 契約の上に重ねる説明・オンボーディング・実例のレイヤーです。導入の手順、認証の手順、実例、ページネーション、エラー、レート制限、非推奨に関するガイダンス、および契約では触れられていないトラブルシューティングを加えます。契約を再定義、置換、または矛盾するものではありません。

使用する場面

• クライアントが統合する操作を定義した上流の api-spec を基に、公開済みの利用者向け API リファレンスを作成するとき。
• エンドポイントごとの使い方（目的、型付きパラメーター、リクエストとレスポンスの実例、エラーレスポンス）に加え、導入と認証、API が出力する場合のイベント／Webhook、ページネーション、エラーとレート制限のガイド、コードサンプル、バージョン管理と非推奨化を文書化するとき。
• 調査に基づき、契約と整合し、実行可能なエンドポイントごとの内容を api-reference template に記入するとき。
• エンドポイントの一覧が OpenAPI から自動生成される API リファレンスに、人が作成した説明、例、乖離チェックを追加するとき。
• 上流の契約が変更された場合（エンドポイントの新規追加、変更、非推奨化）に、既存のリファレンスを改訂するとき。該当する箇所を同期し直します（ステップ 7 を参照）。

次の場合は使用しないでください：

• エンジニアリング上のワイヤー契約自体（操作、網羅的なスキーマ、内部エラーモデル）を作成するとき。これは上流の authoring-api-spec が対象です。api-reference は、その下流に位置し、契約と整合する公開向けドキュメントです。契約を参照しますが、契約を再導出するものではありません。
• エンドユーザー向け製品ガイド／開発者向け導入ガイド（製品のエンドユーザー向けのタスク説明や、SDK／CLI／プラットフォームの使い方）を作成するとき。対象読者が異なる別のスキル、authoring-user-guide／authoring-developer-guide が該当します。
• 永続化データモデルまたはシステムアーキテクチャを記述するとき。これらは別の上流の関心事です（authoring-data-model／authoring-architecture-doc）。
• 完成した api-reference をレビューまたは評価するとき。これは実行時のゲートである reviewing-api-reference が対象であり、このスキルは作成側専用です。
• プロジェクト固有のエンドポイント、SDK チュートリアル、またはその他の種類のドキュメントを作成するとき。

入力

計画で渡されたすべてのドキュメント（depends_on セット。このドキュメントに関係すると上流ドキュメントの調査で判断されたもの）を読み、このドキュメントの内容の出典をたどってください。

• 渡されたセットをすべて使ってください。入力を1つに固定しないでください。 上流の主要なドキュメントは api-spec です（エンジニアリング上の通信契約。REST では OpenAPI、イベントでは AsyncAPI / OpenAPI-3.1 webhooks、GraphQL では SDL、RPC では proto）。また、存在する場合は feature-spec（使用状況のコンテキスト）と architecture-doc（認証／バージョニングのコンテキスト）も読んでください。ここに挙げた一般的な上流ドキュメントは、手法の指針であり、受け取るドキュメントの上限ではありません。
• 改訂時には、既存のリファレンスと変更内容（変更後の契約／変更リクエスト）も渡されます。手順 7 を参照してください。
• すべてのエンドポイントは api-spec から導き出してください。 リファレンスに記載するエンドポイント、パラメーター、フィールド型、必須／任意の指定、エラーコード、イベント、認証方式はすべて、渡された契約に由来するものです。契約が示すのは事実です。調査で補うのは慣例（導入手順／エラードキュメント／レート制限／ページネーション／サンプルの形式）であり、エンドポイントではありません。
• 自己完結し、柔軟に対応してください。 実際に受け取ったコンテキストを使ってリファレンスを作成してください。想定される情報提供ドキュメント（独立した feature-spec など）がない場合は、api-spec のみを使って進め、不足している点を明示的な仮定として示してください。完全に見せるために、エンドポイント、パラメーター、フィールド、エラー、イベントを決して捏造しないでください。
• 利用可能な場合は、調査機能（deep-research）を使い、テンプレートを埋めるだけでなく、一般に公開されている API ドキュメントの確立された慣例を参照してください。調査機能が利用できない場合は、慣例を明示的に仮定として記載し、決して捏造しないでください。

ワークフロー

手順 1：構成はテンプレートツールから取得し、独自に考案しない

api-reference テンプレートツール（包括版）のセクション構成を取得してください。ここでセクション一覧を言い換えたり、再導出したりしないでください。このスキルが示すのは、それらのセクションを適切に埋める方法です。テンプレートが利用できない場合は、包括的な api-reference の構成を取得（依頼／生成するか、標準的な構成に従う：概要、導入手順、認証、ベース URL ＋ バージョニング ＋ 非推奨化、エンドポイントごとのリファレンス、イベント／webhook、主要オブジェクト、ページネーション／フィルタリング／ソート、エラー、レート制限、コードサンプル ＋ SDK、API バージョニング ＋ 変更履歴、ドキュメント自体の改訂履歴）してから進めてください。

手順 2：上流ドキュメントを読み込み、api-spec を基準に網羅性を確保する

上流の api-spec と、渡されたコンテキスト（feature-spec、architecture-doc）を読んでください。これらは、白紙から始めるのではなく、作成の入力となるものです。api-spec に記載された操作は、エンドポイント網羅性のチェックリストです。契約に記載された操作（および契約で宣言されたすべてのイベント／webhook）はリファレンスに含め、ドキュメント化するすべてのエンドポイント／イベントは契約に存在していなければなりません（契約にないエンドポイントを追加しないこと、欠落させないこと）。各操作のパラメーター、フィールド型、エラーレスポンス、認証方式は、契約から取得してください。再入力したり、契約と矛盾する内容を記載したりしないでください。上流ドキュメントの情報が不十分な場合（例：契約に操作名はあるが使用状況のコンテキストがない場合）、不足点を明示的な仮定として示し、形状を暗黙に創作しないでください。

ステップ 3：モードを選ぶ — 基本は文章主体、生成方法に応じて調整

プロジェクトがエンドポイントカタログをどのように表示しているかを確認します。

• 手書き（デフォルト）。 api-spec をもとに、利用者向けリファレンスを手作業で作成します。対象は、導入と認証に関する説明、リクエストとレスポンスの具体例、エンドポイントごとの説明、契約との整合性チェックです。
• OpenAPI から生成。 プロジェクトがエンドポイントカタログを自動生成している場合（Swagger UI、Redocly、Stoplight、Mintlify、Fern、Scalar）、生成されるためカタログは常に最新です。再入力しないでください（手作業で重複して入力すると、すぐに内容がずれてしまいます）。その分、あなたの価値は（i）ジェネレーターが作成しない、周辺の導入／認証に関する説明、（ii）例の品質（実行可能なリクエストとレスポンスの具体例、およびコードサンプル）、（iii）生成された出力の乖離／整合性チェックに移ります。さらに重要なのは、ドキュメントをコードとして管理し、単一の信頼できる情報源を保つという規律です。OpenAPI の記述が単一の信頼できる情報源（SSoT）であり、そこからカタログが生成され、契約テスト（実際のレスポンスが仕様に適合するかを検証すること）が自動的な乖離防止策になります。人による乖離チェックは、説明、例、手書きのセクションを補完します。

1 つのスキルで、同じ仕事の 2 つの表面に対応します。品質基準（ステップ 6）は、どちらのモードでも同じです。生成によって変わるのは、エンドポイント一覧を誰が入力するかであり、リファレンスが使いやすく、契約と整合しているべきかどうかではありません。

ステップ 4：調査を行い、説明と慣例の根拠を得る

詳細な調査を行い、確立された公開 API ドキュメントの実践（Stripe／Twilio のような水準）を参考にして、リファレンスの根拠を固めます。対象は、導入用クイックスタートの構成、認証の手順、エラーの説明に関する慣例、レート制限と再試行の慣例、ページネーションの慣例、非推奨化と提供終了の慣例、コードサンプルの慣例です。ただし、「API ドキュメント全般」ではなく、この製品が提供する機能を対象にします。調査するのは慣例であり、エンドポイントは契約に基づきます。調査機能を利用できない場合は、慣例、ステータスコード、上限を捏造せず、検証が必要な仮定として明示してください。

ステップ 5：セクションごとの手法を適用する

この手法に沿って、テンプレートの各セクションを埋めます。API が小さく、不要なセクションは省略し、規模に応じて調整してください。（各慣例の詳細は references/conventions-and-styles.md に記載されています。）

• 概要と利用開始 — 初回の呼び出しに成功するまで。 高度な機能に進む前に、利用開始のセクションを最初から最後まで実行し、1 回成功すること（キーを取得し、リクエストを 1 回送信し、レスポンスを確認すること）を必須とします。導入促進に最も大きな効果があるセクションです。
• 認証の手順 — フローの名称を示し、成功例と失敗例を説明する。 契約で使用する方式／フロー（静的なAPI キー、またはOAuth 2.0のどのフローか（Authorization-Code／Client-Credentials／PKCE））を明記します。スコープ（最小権限とし、必要に応じて段階的に要求）、認証情報の取得先、その正確な送信方法（具体的な例）、トークンのライフサイクル（有効期限と更新）、および成功時と認証失敗時（401／403）の両方のレスポンスを示します。（トークンを所持していることは委任された認可を示すものであり、本人確認の証明ではありません。）
• ベース URL、バージョニング、非推奨化、規約。 ベース URL、バージョンの表現方法、開発者がバージョンを固定／アップグレードする方法、破壊的変更に該当するもの、非推奨化／提供終了ポリシー（下記参照）、および事前に知っておくべき規約（コンテンツタイプ、日付形式、ID 形式、冪等性キー、リクエスト ID ヘッダー）を説明します。
• エンドポイントごとのリファレンス — すべての操作を、例を含めて完全に説明する。 契約に含まれる各操作について、メソッドとパス、目的の説明、型付きパラメーター（パス／クエリ／ボディの別、必須／任意、制約）、実値を使った具体的なリクエスト例、成功時と少なくとも 1 つの失敗時の具体的なレスポンス例、原因と対処法を含む返却されるエラー／ステータスコードを示します。操作が非推奨の場合は、非推奨化のマーカー（開始時期／提供終了時期／移行先）も付けます。200 のボディだけを示すブロックでは不十分です。（GraphQL ではスキーマに対する操作を、gRPC ではサービスメソッドを説明し、各操作について同じ基準を適用します。）
• イベント／Webhook — API がイベントを発行する場合。 イベントカタログ（すべてのイベントタイプ。操作とは逆方向）、イベントごとのペイロードスキーマと例、署名の検証（リプレイ防止のため、未加工のボディとタイムスタンプに対する HMAC）、および配信セマンティクス（少なくとも 1 回の配信 → 配信 ID を冪等性キーとして使用、バックオフを伴う再試行、N 秒以内の 2xx 応答による確認応答）を説明します。リクエスト／レスポンスのみの API では、規模に応じて省略します。
• コアオブジェクト／共通データ型 — 一度だけ定義する。 再利用可能なオブジェクトの各形状をコアオブジェクトのセクションで一度だけ定義し、エンドポイント／イベントごとのブロックから参照します。各エンドポイント内でリソースを再定義してはいけません。
• ページネーション／フィルタリング／ソート — モデルを一度説明する。 リスト操作のある API では、モデル（大量または変化するデータセットにはカーソル、小規模で安定したデータセットにはオフセット）、標準パラメーター名（limit、after／before、page／per_page）、レスポンスのメタデータ（可能な場合は has_more、next_cursor、total_count）、ページサイズのデフォルト値と文書化された最大値、最終ページのシグナル、および安定したタイブレーク付きソート（ページ間の順序を決定的にする一意な第 2 キー）を説明します。リストを取得する操作がなければ、省略します。
• エラーガイド — 第一級の項目として、標準を明示する。 一貫したエラーレスポンス形式を 1 つ定めて一度説明します（RFC 9457 Problem Details と application/problem+json を推奨。7807 の後継）。原因と対処法を記載したステータスコードの表、HTTP ステータスと区別される機械可読なエラー code、および意味的に正しいステータス（レート制限には 429、競合には 409、提供終了には 410）を明記します。2xx だけを説明するドキュメントでは、開発者は試行錯誤を通じて失敗時の動作を学ぶことになります。
• レート制限。 制限値、429 のシグナル、Retry-After（および、存在する場合は RateLimit-*／X-RateLimit-*。429 では Retry-After に置き換わることを明記）、指数バックオフとジッター、安全な再試行のための冪等性キーを記載します。
• コードサンプルと SDK。 主要な操作ごとに、curl と少なくとも 1 つの言語の例を示し、スキーマと正確に一致する値を使います。追加の言語を示すのは公式 SDK がある場合のみとします。クライアントを提供していない言語の例で水増ししないでください。
• API のバージョニングと変更履歴。 バージョニング／非推奨化ポリシーと、新しい順に記載した日付付きのAPI 変更履歴（API の仕様面での変更）を用意します。これはドキュメント自体の改訂履歴（ステップ 7／変更ログ）とは別のものです。

Step 6: 引き渡す前に、使いやすさと契約との一貫性の基準に照らしてセルフチェックする

以下のすべてを満たしていることを確認します（これはランタイムのレビューゲートで適用される基準です。作成者とゲートは同じ基準を参照するため、内容が食い違うことはありません）。cond-5 は最重要のチェックです。

1. 最初の呼び出しが可能 — はじめに + 認証の説明により（方式／フローが明記され、認証情報を取得して送信でき、認証失敗も示されている）、開発者が認証を行い、最初の呼び出しをエンドツーエンドで成功させられること。コピー＆ペーストで実行できること。
2. すべての操作を文書化 — すべての api-spec 操作（契約で宣言されたイベント／webhook を含む）について、目的 + 型付きパラメーター + リクエスト例 + レスポンス例 + エラーレスポンスが記載されていること。契約上の操作に欠落がなく、契約にない操作が文書化されていないこと。
3. エラーを第一級の要素として扱う — 一貫したエラー形式（Problem-Details 形式）+ 機械可読なコード + ステータスコードの表 + エンドポイントごとのエラー行 + 意味的に正しいステータスがあること。2xx のみを扱うリファレンスでは不十分です。
4. レート制限を文書化 — 制限、429、Retry-After、RateLimit-*、バックオフ + ジッター、冪等性キーを記載すること（API が制限を設けていない場合は、比例した記載とし、該当しない項目は含めません）。
5. 契約と一貫している — すべてのエンドポイント、フィールド型、必須／任意のフラグ、エラーコード、イベント、認証方式が api-spec にたどれること。食い違いや創作がなく、生成済みカタログを手作業で重複して記載していないこと。これが最重要のチェックです。
6. サンプルを実行でき、一貫している — 現実的な値を用いた curl + 1 つ以上の言語のサンプルがあり、スキーマと完全に一致していること。スキーマと矛盾する例は欠陥です。
7. バージョン管理 + 非推奨化を明記 — バージョン管理／非推奨化ポリシー（Sunset／Deprecation の仕組み、非推奨になった対象の移行手順）+ 日付付き API 変更履歴が記載されていること（比例した記載とし、v1 のみの API では簡潔でかまいません）。
8. 共通の型を一度だけ定義し、参照する — 再利用可能なオブジェクトはコアオブジェクトのセクションで一度だけ定義し、エンドポイントごとに再定義せずに参照すること。
9. 創作ではなく、根拠に基づく — エンドポイント／イベントは api-spec を反映し、規約は調査した慣例を反映すること。不明点は創作せず、前提として明示すること。
10. ページネーション／一覧表示の規約（比例した記載）— 一覧操作を持つ API では、モデル + 標準パラメーター + メタデータ + デフォルト値／最大値 + 同順位を安定して解決するソート方式を一度だけ記載すること。一覧操作のない API には記載しません。
11. 修正（修正時） — 変更された契約に差分を同期し、サンプルを再確認し、非推奨化／移行について記載し、ドキュメントのバージョン + 修正ログを更新すること（Step 7）。新規に初めて作成する場合は該当しません。

入力不足の場合のゲート： 契約に記載された操作をこの基準に沿って文書化できない場合（例：使用状況やエラーレスポンスの情報がなく、調査や信頼できる推定でも補えない場合）は、形式を創作するのではなく、ブロッカーとして提示します（「操作の文書化が不十分 — api-spec の作成者またはプロダクト側の判断が必要」）。エンドポイント、エラー、または例が推測に基づくリファレンスは、安全な統合には使えません。

Step 7: 既存のリファレンスを改訂する — アップストリームの変更に応じた再同期

既存のリファレンスと変更内容（多くの場合、アップストリームの api-spec コントラクトの変更）を受け取った場合は、差分を編集し、書き直さないでください。（詳しい説明と具体例は references/amend.md を参照してください。）

1. 変更範囲を特定する：影響を受けるエンドポイント／フィールド／エラー／イベント／認証に絞り、該当するブロックを編集して、変更のないカタログは保持します。
2. 変更後のコントラクトと再同期する：変更したブロックのみを対象に cond-5 の整合性チェックを再実行します。変更または追加されたエンドポイント／フィールド／エラーはすべて変更後の api-spec にたどれる必要があります。コントラクトから削除された操作は削除するか、非推奨として記載します。編集によってコントラクトの不足が判明した場合（ドキュメントで必要な操作がコントラクトに定義されていない場合）は、api-spec の作成者に報告してください。決して捏造してはいけません。
3. 内部への波及を反映する：共有オブジェクトの項目と、それを参照するすべてのエンドポイントを更新し、具体例とコードサンプルを新しいスキーマに照らして再確認します（古いサンプルは不備です）。エンドポイントごとのエラー行も更新します。
4. 非推奨から提供終了までのライフサイクルに対応する：削除または変更されたエンドポイントには、提供終了日と移行ガイド／置き換え先へのリンクを含めて、非推奨であることを明記します。移行期間中は記載を維持し、提供終了後にのみ削除します。黙って削除してはいけません。
5. バージョンと改訂ログを更新する：リファレンス文書自体のバージョンを上げ、改訂ログに作成者／日時／変更内容／理由を記録し、置き換えられた内容を明示します。これはAPI 変更履歴（API の変更内容）およびスキルのバージョンとは別のものです。

API スタイルごとのオーバーレイ（作成補助 — 比例的に適用し、成果で評価）

リファレンスの構成はAPI スタイルによって変わります。REST（デフォルト — リソースとエンドポイントごとのテーブル）、GraphQL（単一のエンドポイントと型付きスキーマ。パスのテーブルではなく、型とクエリ／ミューテーション／サブスクリプションを記載）、gRPC/RPC（proto、メソッド、ストリーミング）、webhook／イベント駆動型（上記のイベントカタログ）、ストリーミング／WebSocket／SSE（接続のライフサイクルとメッセージスキーマ）があります。これらは API の特性に応じた補助であり、比例的に適用します。求める水準は適応しますが、内容を不必要に膨らませてはいけません。（詳細は references/conventions-and-styles.md を参照してください。）**対象外（この Markdown 成果物ではなく、レンダリング済みドキュメントサイトが担うもの）：**全文検索／AI 検索、インタラクティブな「試す」機能／API エクスプローラー／Postman コレクション、ドキュメントサイトのアクセシビリティ／i18n です。この手法は媒体に依存しません。ここでこれらを提供しているかのように過大に主張しないでください。

ルール

必ず守るルール（例外なく遵守）：

• すべてのエンドポイントはコントラクトから導きます。 すべてのエンドポイント、パラメーター、フィールド型、エラーコード、イベント、認証方式は、提供された api-spec に基づきます。存在しないエンドポイントや捏造したエンドポイントを含めたり、コントラクトに記載された操作を漏らしたりしてはいけません。
• 捏造は厳禁です。 完全に見せるために、エンドポイント、パラメーター、フィールド、ステータスコード、エラー、イベント、制限を勝手に追加してはいけません。情報源がない場合は、検証が必要な仮定であることを明示してください。
• api-spec と整合させ、乖離させないでください。 フィールド型、必須／任意の設定、エラーコード、イベント、認証方式はコントラクトに一致させてください。リファレンスには説明、オンボーディング、実例を追加しますが、コントラクトの定義を変更したり、矛盾したりしてはいけません。コントラクトにないエンドポイントや、コントラクトに含まれないフィールドを記載するのは不備です。
• 成功パスだけでなく、エラーも記載してください。 一貫したエラー形式、ステータスコード表、エンドポイントごとのエラー行を含めてください。2xx のみを記載したリファレンスは不完全です。
• 最初の成功呼び出しまでたどり着けるようにしてください。 はじめにと認証の手順を最後まで実行すれば、成功を確認できるようにしてください。その後に高度な機能を説明します。
• 例をスキーマに一致させてください。 すべてのリクエスト／レスポンス例とコードサンプルで、コントラクトに定義されたフィールド名、型、ステータスコードを正確に使用してください。スキーマと矛盾する例は不備です。コントラクトを変更した後は、例も再確認してください。
• curl と 1 つ以上の言語を使い、不要な水増しはしないでください。 サンプルには curl と、少なくとも 1 つの言語を含めてください。公式 SDK がある場合に限り、ほかの言語も追加してください。
• データ構造は一度だけ定義してください。 共通オブジェクト型はコアオブジェクトのセクションにまとめ、参照してください。各エンドポイントの中でリソースを再定義してはいけません。
• 書き直すのではなく、再同期して改訂してください。 コントラクトの変更時は、該当する箇所を編集し、差分の整合性を再確認し、サンプルを見直し、非推奨化や移行について記載し、ドキュメントのバージョンを更新して変更履歴を修正してください。削除されたエンドポイントを何も告げずに削除してはいけません。移行方法とともに非推奨化してください。
• 重複させず、既存の構成に組み込んでください。 セクション構成はテンプレートツールに従ってください。このスキルは、その構成を埋めるための方法です。別の構成を貼り付けて競合させてはいけません。
• 対象読者は利用者です。通信コントラクトでも、エンドユーザー向けガイドでもありません。 公開する開発者向けリファレンスを作成してください。上流のエンジニアリング向け api-spec でも、対象読者の異なるエンドユーザー向け製品ガイドでも、実装そのものでもありません。

推奨事項（必要に応じて変更可能）：

• 「包括的」とは、出力の目標の高さを意味します。内容は相応の分量にしてください。薄い API では、不要なセクションを省略します（一覧取得がなければページネーションは不要、SDK が存在するまでは SDK の表は不要、ウェブフック／レート制限／非推奨化は該当するまでは不要、変更履歴は最初の 1 行から始めます）。基準となるのは開発者が統合できることです。文章量ではありません。
• リソースグループ内では、開発者が操作する順序（作成 → 取得 → 一覧表示 → 更新 → 削除）を優先してください。
• curl の例と同じ呼び出しを言語サンプルでも示し、開発者が両方で同じ操作を確認できるようにしてください。

注意点

• 契約からの乖離。 リファレンスが api-spec から気づかないうちに乖離すること——契約から削除されたエンドポイントが文書に残っている、契約で宣言されていないフィールドがリファレンスに記載されている、リファレンスにエラーが記載されていない、といった状態は、最も深刻な欠陥です。手作業で作成した場合も生成した場合も、同じ問題が発生します。ドリフトチェック（ステップ 6.5）で、どちらの場合も防止します。
• 正常系しかないエンドポイント。 200 のレスポンスボディだけを示して終わるのは、リファレンスで最もよく見られる欠陥です。各エンドポイントでは、少なくとも 1 つの失敗ケースと、返されるエラーコード／ステータスコードを示してください。
• 生成されたカタログの再入力。 カタログが生成される場合、手作業で再入力するとジェネレーターと重複し、すぐに乖離します。カタログの生成はジェネレーターに任せ、説明、サンプル、ドリフトチェックに注力してください。
• 契約変更後に古いままのサンプル。 変更時にスキーマが変わったにもかかわらず、実例やコードサンプルを更新しないままにすると、実行可能に見えても実際には動かなくなります。変更の影響を受けるサンプルをすべて再確認してください（ステップ 7.3）。
• 3 種類の変更履歴の混同。 API 変更履歴（API サーフェスの変更内容）、ドキュメント自体の改訂ログ（このドキュメントの変更内容）、スキルのバージョンは、それぞれ別のものです。改訂ログとドキュメントのバージョンはドキュメントに属し、API 変更履歴は API に属します。
• 削除されたエンドポイントを説明なく削除すること。 削除・変更されたオペレーションは、統合する側に何も告げず削除するのではなく、移行手順を伴う非推奨化（Sunset/Deprecation、Sunset 後は 410）としてください。
• リファレンスをワイヤー契約やエンドユーザーガイドと混同すること。 api-spec はエンジニアリング上の契約（上流にある網羅的な仕様）であり、api-reference はその上に構築される、利用者向けに公開するドキュメントです。user-guide/developer-guide は対象読者が異なります。これは開発者向けの統合リファレンスとして作成してください。
• テンプレートの構成をそのまま書き直すこと。 内容の中（またはこのスキル内）でセクション一覧を作り直すと、テンプレートツールと重複し、乖離します。判断を加えながら、用意されたセクションを埋めてください。

完成して見える例と、統合に使える例の対比（自己点検に活用してください）：

項目	完成して見える（不合格）	統合に使える（公開可能）
最初の呼び出し	「認証してから API を呼び出します。」	コピー＆ペーストできる curl のクイックスタート：ダッシュボードでキーを取得し、Authorization ヘッダーを付けて GET /v1/widgets を呼び出し、期待される正確な 200 のレスポンスボディを示します。
認証	「OAuth を使用します。」	「Client-Credentials フロー。リクエストスコープは widgets:read。POST /oauth/token → 有効期間 1 時間の Bearer トークン。401 の場合は更新します。」——フロー、スコープ、ライフサイクル、失敗ケースを示します。
エンドポイントの網羅性	「主要なエンドポイントを説明しています。」	api-spec のすべてのオペレーション（およびイベント）に説明ブロックがあり、インデックスが契約と 1 対 1 で一致します。
パラメーター	「ウィジェットのフィールドを受け取ります。」	「name（string、必須、最大 255 文字）、status（string、省略可能、active／archived のいずれか、デフォルトは active）。」——契約に基づいています。
ページネーション	「リストを返します。」	「カーソルページネーション：limit（最大 100、デフォルト 20）＋ starting_after。has_more ＋ next_cursor。created、次に id の順で並べ替え（同値の場合の判定基準）。」
エラー	「失敗時にエラーを返します。」	Problem-Details 形式＋機械処理用の code＋エンドポイントごとの行（400 invalid_request、404 not_found、409 conflict）＋ステータスコード表——契約にあるコードをすべて示します。
非推奨化	（エンドポイントを説明なく削除）	「GET /v1/charges/legacy — 2026-06-14 に非推奨化、2026-09-12 に廃止。GET /v1/charges に移行してください。」
一貫性	（追跡できない）	すべてのエンドポイント／フィールド／エラー／イベントが api-spec に対応しており、契約で宣言されていない内容は記載されていません。

記述内容が左の列のようになっている場合——どの API にも当てはまる説明、実例なし、エラーケースなし、契約との対応関係なし——まだ完成していません。

アンチパターン

• 「api-spec の内容が薄いので、もっともらしいエンドポイントやパラメーターを補います。」 捏造してはいけません。契約から導き出し、不足は前提条件またはブロッカーとして明示してください。
• 「正常系だけ仕様化します。エラーは明らかです。」 明らかではありません。各エンドポイントのエラー応答とステータスコードをすべて記載してください。
• 「カタログは生成されたので、これで完了です。」 生成で得られるのはカタログであり、オンボーディングの説明、サンプルの品質、差分チェックではありません。そこに人が作成する価値があります。
• 「これもワイヤー契約なので、内部スキーマを徹底的に厳密に記述します。」 契約は上流にあります。リファレンスは、その契約を基にした利用者向けドキュメントです。契約を参照し、再定義しないでください。
• 「これもエンドユーザー／開発者向けの導入ガイドです。」 対象読者が異なります。これは開発者向けのインテグレーションリファレンスです。
• 「ベストプラクティスに従って、GraphQL／webhook のセクションを追加します。」 オーバーレイは必要に応じた補助です。API にその機能がある場合にだけ追加し、REST リファレンスを肥大化させないでください。
• 「エンドポイントが削除されたので、そのブロックを削除します。」 移行手順を示して非推奨にしてください。インテグレーターが利用しているものを突然削除してはいけません。
• 「アウトラインは自分で作成します。」 テンプレートツールと重複します。構成はテンプレートツールから取得してください。
• 「調査は省略します。優れた API ドキュメントの書き方は知っています。」 調査によって、この製品のオンボーディング、エラーの説明、ページネーション、サンプルの規約を確かなものにできます。API ドキュメントの理論を学ぶためではありません。

出力

Step 6 の使いやすさ＋契約との一貫性の基準（最初の呼び出しに到達できること。api-spec のすべての操作／イベントについて、目的＋型付きパラメーター＋具体的なリクエスト例＋具体的なレスポンス例＋エラーを記載すること。エラーを第一級の要素として扱い、Problem Details 形式のエラーを 1 つとステータスコード表を含めること。レート制限を記載すること。契約との一貫性を保つこと — すべてのエンドポイント／フィールド／エラー／イベントの出典をたどれ、差分がなく、捏造がないこと。サンプルを実行でき、スキーマと一致させること。該当する場合はページネーションの規約を記載すること。バージョニングと非推奨化を明記すること。共通型は一度だけ定義すること。適切な範囲に収めること。改訂時は再同期し、ドキュメントのバージョンを付けること）を満たす、包括的で公開済みの API リファレンス（または再同期済みの改訂版）。成果物はテキスト形式です。エンドポイントのセクション、コードフェンスで囲んだリクエスト／レスポンス例、コードフェンスで囲んだコードサンプルで構成します。この手法と基準は媒体に依存しません（現在はローカルのドキュメントバックエンドを使った Markdown で、将来的にレンダリングされたドキュメントサイトになっても変わるのは媒体のみです。検索／試用機能／アクセシビリティ／国際化はそのサイトが担い、このスキルの範囲ではありません）。抽象的な利用者は、リファレンスだけを頼りに API を統合するクライアント開発者であり、同じ基準を適用するランタイムレビュゲートでもあります。api-reference は入力として api-spec に依存し（存在する場合は feature-spec／architecture-doc も参照します）。その構成はテンプレートツールから取得し、このスキルはコンテンツの品質を担います。

関連項目

• api-reference template tool（content-template-gateway）— このスキルが内容を埋めるセクション構成を提供します。組み合わせて使用し、アウトラインを繰り返し記載しないでください。
• deep-research capability（deep-research）— 確立された公開 API ドキュメントの実践を基に、オンボーディングの説明、サンプル、規約を確かなものにします。
• api-spec-authoring skill（authoring-api-spec）— このリファレンスのすべてのエンドポイント、フィールド、イベント、エラーの由来となり、それらとの一貫性を保つ、上流のエンジニアリング向けワイヤー契約を作成します。
• feature-spec と architecture-doc（存在する場合）— 上流のコンテキストです。各操作の利用状況、および認証／バージョニングのコンテキストを提供します。
• review gate（reviewing-api-reference）— 完成したリファレンスに対して、同じ使いやすさ＋契約との一貫性の基準をランタイムで適用します。作成者とゲートは同じ基準を単一の情報源から共有するため、ずれません。
• エンドユーザー向け product-guide／開発者向け導入ガイドのスキル（authoring-user-guide／authoring-developer-guide）— 異なるドキュメント／対象読者向けです（製品のエンドユーザー、またはこのリファレンスを参照する SDK／CLI の導入説明）。

段階的な開示

• references/conventions-and-styles.md — 認証フローの詳細（API キー／OAuth2 フロー／スコープ／トークンのライフサイクル）、RFC 9457 の Problem-Details エラーモデル、レート制限／RateLimit-*／冪等性の仕組み、ページネーションの規約（カーソル／オフセット、標準パラメーター、メタデータ、同順位を解消するソート）、および API スタイルのオーバーレイ（Webhook／イベントのドキュメント作成方法を含む）です。これらのセクションを作成する際に読み込みます。
• references/amend.md — 上流の変更に基づく再同期の修正手順、非推奨からサンセットまでのライフサイクル（RFC 8594/9745）、3 種類の変更履歴の違い、修正例です。修正時に読み込みます。
• references/sources.md — 手法の根拠と品質基準です。ガイダンスの出典を監査する場合にのみ読み込みます。

本文の上限

• description は 1,024 文字以下です（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下です。
• 大量の内容は references/ に置き、必要に応じて読み込みます。

変更履歴

• 1.1.0（2026-06-14） — 本番品質を目指した再構成（追加のみ。reviewing-api-reference の 11 項目の条件基準と単一の情報源を共有）。反復／修正手法（ステップ 7 — 上流の変更に基づく再同期）と references/amend.md を追加し、認証フローの詳細、RFC 9457 の Problem-Details エラーモデル、RateLimit-*/ジッター／冪等性、非推奨／サンセット（RFC 8594/9745）の仕組みを拡充しました。ページネーション／リスト操作の規約と、執筆の補助となる API スタイルのオーバーレイ（Webhook／イベントのドキュメント作成を含む）および references/conventions-and-styles.md を追加しました。ステップ 6 のセルフチェックは 9 項目から 11 項目になりました。入力契約と媒体は変更ありません。
• 1.0.0（2026-06-05） — 初回のレビュー済みリリース。