reviewing-api-reference

reviewing-api-reference — SKILL.md

バリアント： 標準 · 使用する場面： 完成済み（または修正済み）の公開 API リファレンスを受け入れゲートとして評価する場合。クライアント開発者がこのリファレンスを使って統合できること、また提出された api-spec 契約との一貫性が保たれていることを確認し、実行可能な指摘とともに VERDICT: approve|revise を出力します。

概要

このスキルは、api-reference の作成・評価ペアのうち、レビューを担います。完成済みの公開 API リファレンス、つまり API を呼び出すクライアント開発者が読む、利用開始手順、認証、エンドポイントごとのリファレンス、イベント／Webhook、共有オブジェクト型、ページネーション、エラーとレート制限、コードサンプル、API changelog などの利用者向けドキュメントを受け取ったレビュアーが、このドキュメントを次の問いに照らして評価します。クライアント開発者は、このリファレンスだけで認証し、最初の API 呼び出しを行い、すべての操作を統合できるか。また、記載されたすべてのエンドポイント、構造、エラーは、上流の api-spec 契約にたどれるか。乖離や捏造はないか。 固定の 11 項目からなる使いやすさ＋契約整合性のチェックリストを適用します。これは api-reference の作成者が満たす基準と同じであり、作成基準とレビュー基準のずれを防ぎます。そのうえで、機械で解析可能な判定と、作成者が一度の修正作業で対応できる指摘を出力します。このスキルは受け入れゲートです。リファレンスの作成、修正、書き換えは行いません。評価して指摘を返し、作成者が修正します。

最も重要なチェックは api-spec との整合性（条件 5）です。リファレンスは、エンジニアリング上の api-spec ワイヤー契約を基に作成されます。レビュアーは、記載されたエンドポイント、パラメーター、構造、エラーを、提出された api-spec と照合してスポットチェックします。契約との乖離や、捏造された／契約に存在しないエンドポイントは、最も影響の大きい不具合です。

使用する場面

• 完成済みの公開 API リファレンスを、統合を行う開発者に公開する前に、承認または修正の判断を下す必要がある場合。
• 作成者が作成した API リファレンスの独立したレビュアー／ゲート担当者であり、整合性を確認するための上流 api-spec がある場合。
• 以前の revise 判定後に修正された API リファレンスを再評価する場合。
• 既存のリファレンスへの追補（上流契約の変更後に差分を追加したもの）を評価する場合。差分を対象とする手順です（条件 11）。

次の場合は有効にしないでください：

• API リファレンスを作成または修正する場合 → api-reference-authoring スキルを使用してください（このスキルが定めるのと同じ基準を満たす形で作成します）。このスキルがドキュメントを作成することはありません。
• エンドユーザー向け製品ガイドをレビューする場合 — 製品を使う非技術者向けのヘルプです → user-guide-review スキルを使用してください。対象読者も基準も異なります。
• 開発者向け導入／統合ガイドをレビューする場合 — このリファレンスを参照する、SDK／CLI／プラットフォームの使用方法や概念の説明です → developer-guide-review スキルを使用してください。そのスキルは導入に関する説明を評価します。このスキルは、そのガイドからリンクされているエンドポイント一覧／リファレンスを評価します。
• エンジニアリング上の api-specをレビューする場合 — 操作、網羅的なスキーマ、内部エラーモデルからなるワイヤー契約そのものです → 専用ゲートである reviewing-api-spec を使用してください（汎用の design-review では、api-spec 成果物をそのスキルの対象外としています）。そちらは契約を評価します。このスキルは、その契約から導出された公開利用者向けリファレンスを評価します。
• テンプレートやセクションへの準拠を確認する場合 → それはテンプレートの問題です。このスキルが評価するのは、見出しがすべて存在するかではなく、基準に照らした品質です。
• プロジェクトの稼働中の API 実装を評価する場合 → このゲートが評価するのはリファレンスドキュメントであり、稼働中のサービスではありません。

ワークフロー

ステップ 1：先入観のない新鮮な視点でリファレンス全体を読み、api-spec を確認する

API リファレンスを、API に初めて触れるインテグレーション開発者になったつもりで、著者の枠組みにとらわれず最初から最後まで読んでください。あなたはインテグレーション開発者のゲートキーパーです。指摘に意味があるのは、開発者が認証できない、最初の呼び出しを行えない、または記載どおりに操作を統合できないことを示す場合、またはリファレンスが契約と食い違っている場合に限られます。リファレンスが想定するAPI の類型（少数のエンドポイントからなるシンプルな API キーユーティリティか、複数のリソースを扱う幅広いプラットフォームか、イベント駆動型／Webhook API か）を特定してください。ステップ 2 の比例性の調整は、この類型に基づいて行います。重要なのは、提供された api-spec を読み込むことです。これは、エンドポイント網羅性のチェックリストであり、一貫性を検証するための基準です。api-spec が提供されていない場合は、そのことをここで記録してください。ステップ 4 で前提として明記し、契約との一貫性を完全には検証できないことを踏まえて、手元にある情報でユーザビリティを判断します。修正の場合は、変更リクエスト／変更された契約との差分も確認してください。これにより、差分に限定した評価経路（条件 11）が有効になります。

ステップ 2：ユーザビリティと契約との一貫性に関するチェックリストを実施し、各条件を判定する

以下の各条件について、合格か不足かを判定してください。条件が不合格となるのは、実際に特定できる不足がある場合に限ります。「エンドポイントの整理方法を変えたほうがよい」は不足ではありません。不足がある場合は、該当箇所と欠けている内容を正確に記録してください（ステップ 4 で、実行可能な指摘にします）。これらの条件が唯一の評価基準です（API リファレンスの著者が従うのと同じ条件です）。独自の条件を追加しないでください。

1. 最初の呼び出しに到達できること。 はじめに読むガイドと認証の説明を合わせて、開発者が高度な機能に進む前に、認証を行い、最初の呼び出しをエンドツーエンドで成功させられるようにします。コピー＆ペーストで実行できる内容にしてください。認証セクションには方式／フロー（API キー／どの OAuth2 フローか）、認証情報の取得方法と送信方法を明記し、成功例だけでなく認証失敗（401／403）のケースも示します。不足とみなす場合 は、はじめに読むガイドまたは認証の説明がない、方式／フローが明記されていない、失敗ケースがない、または推測せずに動作する呼び出しを1つ実行できるオンボーディング経路がない場合です。
2. すべての操作が文書化されていること。 提出された api-spec に含まれるすべての操作（契約で宣言されたイベント／Webhookを含む。この条件ではイベントも「操作」とみなします）について、次のすべてを記載します。目的、型付きパラメーター（必須／任意と制約）、実際に動作するリクエスト例、実際に動作するレスポンス例、およびエラーレスポンス。不足とみなす場合 は、契約に含まれる操作／イベントが欠落している場合、または文書化された操作に 200 のボディしかなく、パラメーター／実例／エラーがない場合です。
3. エラーを第一級の要素として扱うこと。 一貫したエラーレスポンスの形式を1か所に記載します（Problem Details形式のボディ — RFC 9457 application/problem+json、またはAPI独自の一貫した形式）。HTTPステータスとは別の、機械可読な code を含めます。原因と対処法を記載したステータスコード表では、意味的に正しいステータス（レート制限は429、競合は409、提供終了は410など。汎用的な400ではない）を使います。エンドポイントごとのエラー行も記載します。不足とみなす場合 は、リファレンスが2xxの成功ケースだけを扱っている場合、エラーがエンドポイントごとの行なしに一般論としてしか記載されていない場合、または誤ったステータスクラスを使用している場合です。
4. レート制限を文書化すること。 制限値、429 の通知、Retry-After、存在する場合の RateLimit-*／X-RateLimit-* ヘッダー（429では Retry-After に置き換わることを明記）、バックオフとジッター、安全に再試行できる書き込み操作の冪等性キーを記載します。不足とみなす場合 は、レート制限を行う／書き込みを受け付けるAPIでこれらが文書化されていない場合です（レート制限を行わないシンプルなAPIでは、正当な理由があれば省略できます。「比例性」を参照）。
5. 提出された api-spec と一貫しており、乖離や捏造がないこと。 リファレンスに記載されたすべてのエンドポイント、フィールド型、必須／任意の指定、エラーコード、イベント、認証方式は、上流の api-spec に根拠がある必要があります。リファレンスでは説明、オンボーディング、実例を追加しますが、契約を再定義したり、矛盾したり、契約にない内容を作り出したりしてはいけません。不足とみなす場合 は、文書化されたエンドポイント／イベントが契約で宣言されていない場合（捏造または孤立した項目）、フィールド／型／必須指定／エラー／認証が契約と矛盾する場合、契約で宣言された操作が欠落している場合、またはリファレンスが生成済みカタログを手作業で再入力した重複版である場合（乖離のリスク）です。文書化されたエンドポイント、パラメーター、データ構造、エラーを提出された api-spec と照合して抜き取り確認してください。これは最も重要な評価軸です。最も影響の大きい欠陥は、リファレンスが契約から乖離することです。
6. サンプルが実行可能であること。 curl に加えて、少なくとも1つの言語のサンプルを用意します。現実的な値を使い、スキーマに厳密に一致させてください。スキーマと矛盾する例（契約で宣言されていないフィールド、誤った型やステータスなど）は欠陥です。言語を追加するのは、公式SDKがある場合のみです。不足とみなす場合 は、実行可能なサンプルがない場合、またはサンプルのデータ構造が契約と矛盾する場合です。
7. バージョン管理と非推奨化を明記すること。 バージョンの表現方法、開発者がバージョンを固定／アップグレードする方法、破壊的変更に該当するもの、日付入りの変更履歴を記載します。さらに、非推奨となったインターフェースがある場合は、非推奨化／提供終了の仕組み（Deprecation／Sunset、提供終了後の 410 Gone）と移行手順／ガイドを記載します。不足とみなす場合 は、バージョン管理を行うAPIでバージョン管理について説明がない場合、または非推奨のエンドポイントに移行手順がない場合です（非推奨の項目がないv1のみのAPIでは、該当セクションが簡潔でも問題ありません）。
8. データ構造は一度だけ定義すること。 共通オブジェクト／データ型は、中核オブジェクトのセクション1か所にまとめ、エンドポイント／イベントごとのブロックから参照します。不足とみなす場合 は、再利用可能なリソースを参照せず、すべてのエンドポイント内で定義し直している場合（乖離のリスク）です。
9. 根拠に基づき、不足を明示すること。 エンドポイント／イベントは api-spec を反映し、規約は確立された慣行に沿う必要があります。使用状況の不足や未文書化の制限など、実際に存在する不足は、完成しているように見せるために作り出すのではなく、明示的な前提／未解決の質問として提示します。不足とみなす場合 は、完成しているように見せるために内容を捏造し、問題として明示していない場合です。
10. ページネーション／一覧操作の規約（APIに応じた対応）。一覧操作があるAPIでは、リファレンス全体で一度、ページネーション方式（カーソル／オフセット）、標準的なパラメーター名、レスポンスメタデータ（has_more／next_cursor）、デフォルトのページサイズと文書化された最大ページサイズ、最終ページを示す方法、安定した同順位解消ソート（ページをまたいでも順序が確定的になるよう一意な第2キーを使うこと）を記載します。不足とみなす場合 は、一覧エンドポイントで方式／最大ページサイズ／同順位解消ソートが文書化されていない場合です。一覧操作がないAPIでは該当なしです。存在しない不足を作り出さないでください。
11. 改訂 — 変更された契約に合わせて差分を再同期すること（改訂時のみ）。変更リクエスト／変更後の契約差分を受け取った場合、変更されたブロックが基準を満たすこと、差分が（変更後の）api-spec と再同期されていること（差分に対する条件5）、サンプルが再同期されていること（条件6。スキーマ変更後に古いサンプルを残さない）、エンドポイントが変更／削除された場合に非推奨化／移行が文書化されていること（条件7）、ドキュメント自体のバージョンと改訂ログ（APIの変更履歴とは別）が更新されていることを確認します。これは差分の範囲に限定したレビューであり、変更のないカタログ全体を再レビューするものではありません。新規作成には該当しません（変更リクエストが提出されていない場合。入力シグナルから判定します）。 比例性。 「開発者がそれを使って統合できるか」は、API の規模に応じて判断します。薄い API のリファレンスでは、不要なセクションを正当に省略できます。一覧表示するものがなければページネーションは不要です（cond. 10 は該当なし）。SDK が存在するまでは SDK／言語の表は不要です。変更履歴は 1 行から始まります。API にレート制限がなければ、レート制限の記載は不要です。適用されるまでは、Webhook／非推奨化の記載は不要です。初回ビルドでは cond. 11 は該当しません。これは適切な規模への調整であり、欠落ではありません。文字数やセクション数ではなく、開発者が統合できるかを評価してください。適用されるすべての条件を満たす、小規模でも完全なリファレンスは合格です。（条件 2 と 5 は規模を問わず適用されます。すべての契約上の操作／イベントが記載され、すべてが契約に照らして検証可能である必要があります。）

ステップ 3：判定を決める

• approve — 適用されるすべての条件を満たしています。クライアント開発者は、このリファレンスの記述どおりに認証して最初の呼び出しを行い、すべての操作を統合でき、記載内容はすべて api-spec に準拠しています。スタイル上の改善案が思いついても承認してください。基準となるのは使いやすさと契約との一貫性であり、完璧さでも最大限の網羅性でもありません。
• revise — 統合を妨げる、具体的に指摘できる不備が 1 つ以上あります（操作やイベントの欠落／未記載、契約との乖離や契約にないエンドポイント、getting-started／認証または認証失敗時のケースの欠落、正常系だけのエンドポイント、スキーマと矛盾するサンプル、一覧表示 API でのページネーションの未記載、移行手順のない非推奨エンドポイント、修正後も古いサンプルが残る状態、内容の捏造など）。

努力を示したり、あると望ましいだけの項目を求めたりするために revise としてはいけません。条件は満たされているか、いないかのどちらかです。

ステップ 4：判定と実行可能な指摘を出力する

判定は 1 行だけで出力します。VERDICT: approve または VERDICT: revise という文字列を、単独の行に記載し、前後にコードフェンス、引用符、余計な語句を付けないでください（ここにあるフェンスは説明用です）。

VERDICT: approve

続く行に指摘を列挙します。revise の場合、各指摘は実行可能でなければなりません。不合格となった条件、正確な箇所、および修正方法を示し、作成者が一度の対応で解決できるようにしてください。approve の場合、指摘は任意の非ブロッキングなメモです。修正が必要だと受け取られるような内容にしてはいけません。

api-spec が提出されていない場合は、その点を前提として指摘に明記してください（例：「api-spec が未提出のため、一貫性（cond. 5）はリファレンス内部の整合性のみで評価しました。完全な照合には契約を提出してください」）。ほかの条件は提示された内容に基づいて判定してください。実行できない一貫性チェックを黙って見送ってはいけません。

適切な指摘は、不備と修正方法を明確に示します。

revise — api-spec との一貫性（cond. 5）、「POST /v1/refunds」：リファレンスにはこのエンドポイントが記載されていますが、提出された api-spec には refunds 操作が宣言されていません。修正方法：契約にないエンドポイントを削除するか、契約に含める意図がある場合は api-spec の作成者に確認してください。リファレンスに契約で宣言されていないエンドポイントを記載してはいけません。

revise — ページネーションの規約（cond. 10）、「GET /v1/widgets」：一覧エンドポイントには limit が記載されていますが、最大ページサイズと安定した並べ替えのタイブレーカーが記載されていないため、ページをまたいだ順序が不定になります。修正方法：最大ページサイズと第 2 ソートキーを記載してください（例：created、次に id の順に並べ替える）。

revise — 変更対応（cond. 11）、「Charge オブジェクト」：api-spec に currency が追加され、フィールドの説明もありますが、応答例と Python のサンプルにはまだ記載されていません。修正方法：Charge の例とサンプルを同期し、currency を含めてください（cond. 6）。

不適切な指摘は曖昧で、具体的な対応につながりません。

エラーの説明をもっと充実させるとよいでしょう。(どのエンドポイントですか？どのエラーですか？どう修正すればよいですか？)

ルール

必ず守るルール（決して違反しないこと）：

• 判定行を正確に1行だけ出力してください。VERDICT: approve または VERDICT: revise のいずれかを、他の文字を加えず単独の行に記述します。 後続のツールが解析します。別の判定語は使わないでください。
• 評価に徹し、執筆はしないでください。 指摘事項を返してください。参照資料の書き換え、修正、補完はしないでください。修正するのは作成者です。
• 単一の評価基準に従ってください。 ステップ2にある11項目、つまり作成者が準拠するものと同じ基準で評価してください。独自の条件を追加したり、独自の厳しい基準を適用したりしないでください。
• 最も重要な評価項目は api-spec-consistency です。 文書に記載されたエンドポイント、パラメーター、データ構造、イベント、エラーを、提出された api-spec と照合してスポットチェックしてください。捏造された、または対応する仕様のないエンドポイント、契約に反するフィールド／型／必須フラグ／エラー／認証、参照資料にない契約上の操作／イベント、または生成されたカタログを手作業で重複して記述したものは、最も影響の大きい欠陥です（条件5）。
• 誤った revise 判定をしないでください。 適用されるすべての条件を満たす参照資料は、規模の小さな API 向けの簡潔なものであっても承認してください。契約を網羅している限り、規模に応じた分量は欠陥ではありません。実際の、具体的な不足がある場合に限り revise としてください。API スタイルのオーバーレイと Webhook のドキュメント作成手法は、成果に基づいて評価する補助要素です（Webhook の参照資料は条件2／3／5で評価し、「Webhook／GraphQL セクションを追加すること」を求めてはいけません）。レンダリングされたドキュメントサイトの機能（検索、インタラクティブな試用機能／Postman、アクセシビリティ／国際化）は対象外です。Markdown 形式の参照資料に対する revise 判定の理由にしてはいけません。
• 誤った approve 判定をしないでください。 賛成するために実際の不足を見過ごしてはいけません。承認を妨げる不足があれば revise としてください。
• 成功例だけでは不足です。 エンドポイントの説明が 2xx レスポンス本文のみで、パラメーター、具体的な使用例、エラーレスポンスがない場合、条件2を満たしません。
• スキーマと矛盾するサンプルは不足です。 契約にないフィールドを使ったり、型／ステータスが誤っていたりする具体例やコードサンプルは、条件6を満たしません。修正後も古いまま残ったサンプルも該当します。
• 捏造は根拠ではなく不足です。 事実として提示された、実在しないエンドポイント、パラメーター、ステータスコード、イベント、制限値は条件9を満たしません。実際の不足は、前提または未解決の質問として指摘してください。
• api-spec がない場合は、そのことを指摘してください。 契約が提出されていない場合は、明示的な前提として示し、整合性（条件5）を完全には確認できなかったと記してください。その他の項目は、手元の情報に基づいて評価してください。
• 改訂時（条件11）は差分に限定して評価してください。 改訂では、変更された契約との再同期、サンプルの再同期、非推奨化／移行の文書化、文書バージョンと改訂ログの更新を確認してください。変更のないカタログ全体を再評価してはいけません。新規作成の場合は該当しません。
• 提示された上流資料を基準に評価してください。 depends_on セット（主に api-spec）に照らして参照資料を評価してください。未作成の上流資料は、決して revise 判定の理由にしてはいけません。一方、作成済みの上流資料（たとえば、提出された api-spec の操作内容を反映していない参照資料）を無視している場合は、正当な指摘事項です。
• revise の指摘はすべて対応可能な内容にしてください。 満たしていない条件、該当箇所、具体的な修正内容を示してください。曖昧な指摘はしないでください。

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

• 指摘は重大度の高い順に並べてください。まず承認を妨げる不足を示し、特に api-spec との不整合や捏造を最優先にします。その後、軽微な指摘を示してください。
• 各指摘には条件番号／名称を記載し、作成者が評価基準と照合できるようにしてください。
• approve に添えるコメントは少数にし、承認を妨げるものではないことが明確にわかるようにしてください。

注意点

• 統合性ではなく、網羅性を基準に承認すること。 すべてのセクションがそろっていても、API を統合できるとは限りません（最初の呼び出しに到達できない、エンドポイントに 200 の本文しか示されていない、サンプルがスキーマと矛盾しているなど）。テンプレートが埋まっているかではなく、開発者がそれを基に統合できるかを判断してください。
• 一見、整合しているように見える食い違い。 リファレンスと api-spec は個別に見るとどちらも正しく見えても、互いに食い違っていることがあります。たとえば、リファレンスに記載されているのにコントラクトには宣言されていないフィールド、コントラクトから抜け落ちたエンドポイント、リファレンスに記載されていないエラーなどです。これを見つける唯一の方法は、ドキュメントに記載されたエンドポイント／データ構造／エラーを、提出された api-spec と照合することです（条件 5）。これは最も重大で、最も見落とされやすい欠陥です。
• 捏造された／孤立したエンドポイント。 リファレンスに、もっともらしく見えるもののコントラクトには宣言されていないエンドポイントが記載されていることがあります。エンドポイント一覧を api-spec と一対一で抜き取り確認してください。コントラクトの裏付けがないエンドポイントは、カバレッジではなく欠陥です。
• 成功時の処理しか記載されていないエンドポイント。 200 の本文だけを示して終わるエンドポイントのブロックは、一見完成しているように見えても、開発者は試行錯誤しながら失敗時の挙動を把握することになります。各操作にはパラメーター、少なくとも 1 つの実例、エラーレスポンスが必要です（条件 2／3）。
• スキーマから逸脱したサンプル（修正後も含む）。 コントラクトにないフィールドを使ったり、型／ステータスが誤っていたりする curl またはコードのサンプルは、気付かれないまま動作を妨げます。特に修正後、スキーマが変わったのにサンプルが更新されていないと、実行可能に見えて実際には動きません（条件 6／11）。
• 生成されたカタログの手入力による再作成。 エンドポイントカタログが OpenAPI から生成されている場合、手入力で再作成した複製はすぐに食い違います。生成されたカタログの手動管理コピーは、指摘すべきドリフトリスクです（条件 5）。一方、生成されたカタログ自体が最新に保たれているのは問題ありません。
• ページネーションを主観で評価すること。 条件 10 は構造に関するものです。つまり、一覧 API について、モデル／最大値／同順位を解消するソートが文書化されているかを確認します。「ページネーションが洗練されているか」ではありません。また、一覧 API ではない場合は該当なしです。無理に指摘を作らないでください。
• コントラクト欠如による見落とし。 api-spec が提出されていない場合、整合性の評価は完全には実施できません。その欠如を承認の既定値にしてはいけません。これを指摘し（条件 5 は一部実施不可）、残りの項目を評価してください。
• 体系的な過剰指摘（誤った修正判定）。 問題を見つけるよう依頼されたレビュアーは、適切なリファレンスを欠陥と判断し、過剰に修正しがちです。基準に合わせてください。条件の不足といえるのは、具体的で実在する欠陥が明示できる場合だけです。構成や、自分なら異なる書き方をしたという理由では不足になりません。もっともらしいだけの細かな指摘は、レビュアーが陥る主な誤りです。
• 規模に見合ったリファレンスに対する誤った修正判定。 規模の小さい API のリファレンスが簡潔なのは適切です。エンドポイントが少数で、ページネーションがなく（条件 10 は該当なし）、変更履歴が 1 行で、SDK 表も、Webhook も、非推奨事項もない、という場合です。これはドキュメント不足ではなく、適切な規模です。簡潔さを理由に不足を作り出すと、避けられる修正の反復につながります。API の類型に合わせて判断してください（条件 2 と 5 は引き続き適用されます）。
• API に存在しない機能のセクションを要求すること。 REST のみの API に Webhook／GraphQL のセクションは不要です。一覧 API でなければ、ページネーションも不要です。各オーバーレイは執筆支援のためのものです。セクションを要求するのではなく、既存の条件で成果物を評価してください（これは条件を捏造する落とし穴です）。
• これをユーザーガイド、開発者ガイド、またはデザインレビューのゲートと混同すること。 ここで評価するのは、公開済みの開発者リファレンス／エンドポイントカタログです。user-guide-review はエンドユーザー向けの製品ヘルプを評価し、developer-guide-review は SDK／CLI の導入に関する説明を評価し、reviewing-api-spec はエンジニアリング用の api-spec コントラクトを審査します。ここでは、エンドユーザー向け、導入説明、またはワイヤーコントラクトの基準を適用しないでください。
• 判定トークンのずれ。 「Approved」「LGTM」「needs work」や、段落の途中に埋め込まれた判定は解析できません。独立した行に、文字どおり VERDICT: approve|revise と出力してください。

アンチパターン

• 形式的な承認。 修正のやり取りを避けるためにざっと目を通して承認すると、捏造されたエンドポイント、契約からの逸脱、またはハッピーパスのみのブロックを見過ごすことになり、統合の不具合や実装途中のサポートチケットにつながります。
• api-spec との照合を省略。 「リファレンスは内部的に一貫しているようなので、承認します」——提出された契約と照らし合わせて抜き取り確認をしなければ、最も影響の大きい欠陥の種類（条件 5）を見逃します。このゲートが禁じるために存在する、唯一の近道です。
• 細部にこだわった修正要求。 エンドポイントの順序の好み、言い回しの好み、または不足として装った「あれば便利なもの」を理由にブロックします。修正要求は、実際の使いやすさや一貫性を損なう問題に限ります。
• 黙って書き換える。 「例を自分で直したほうが簡単だった」——レビュー中に執筆すると、作成と評価の分離が崩れ、作成者が不足点から学ぶ機会がなくなります。
• 条件をでっち上げる。 基準に含まれない独自の要件（「Postman コレクション／GraphQL 版／対話型の試用機能も必要」など）を追加すると、レビュー基準が作成基準から逸脱し、不当な修正要求が発生します。11 の条件のみを評価してください。オーバーレイや DX 機能は条件ではありません。
• 過剰主義。 不要な薄い API に対して、ページネーション、多言語 SDK の一覧、Webhook、長大な変更履歴を要求します。基準となるのは開発者が統合できることです。考えられる限り最大のリファレンスではありません。
• 修正内容の全件再レビュー。 条件 11 に沿った差分スコープの手順を使わず、変更されていないカタログ全体を差分に対して再評価します。非効率であり、プロトコルにも反します。
• 曖昧な判定。 「おおむね承認ですが……」や判定行を 2 つ書くことです。決定は 1 つ、トークンも 1 つだけです。

出力

公開済み（または修正済み）の API リファレンス 1 件に対する、単一のレビュー結果です。

• 判定行は 1 行 — VERDICT: approve または VERDICT: revise を、独立した 1 行にそのまま記載します。
• 指摘事項 — revise の場合は、ブロック要因となる問題ごとに実行可能な指摘を 1 件記載します（不合格となった条件 + 該当箇所 + 具体的な修正方法）。approve の場合は、ブロック対象ではない注記を任意で記載できます。

現在、レビュー対象のリファレンスはテキスト形式です（エンドポイントのセクション + フェンス付きリクエスト／レスポンス例 + フェンス付きコードサンプル。ローカルのドキュメントバックエンドを通じた Markdown）。レビューの方法と基準は、媒体に依存しません（将来、レンダリングされたドキュメントサイトになった場合も、変わるのは媒体だけです。検索／試用機能／アクセシビリティ／国際化はそのサイト側が担い、評価対象は変わりません）。抽象的な利用者は、作成->レビューのループを調整するものです。approve は統合を行う開発者が API リファレンスを使用できる状態にし、revise は範囲を限定した修正作業のために指摘事項を作成者へ返します。

関連項目

• api-reference-authoring スキル（authoring-api-reference）——このペアの作成側です。このスキルが評価するのと同じ、使いやすさと契約との一貫性に関する 11 条件の基準に従ってリファレンスを作成します。両者を組み合わせることで基準が一元化され、作成とレビューの間で基準がずれるのを防ぎます。
• 上流の api-spec（authoring-api-spec）——リファレンスに含まれるすべてのエンドポイント、フィールド、イベント、エラーの基となる、エンジニアリング上のワイヤー契約です。このゲートでは、提出された api-spec に対するリファレンスの一貫性を確認します（条件 5）。api-spec 自体は、ここではなく reviewing-api-spec によってエンジニアリング段階でゲートされます。
• user-guide-review スキル——エンドユーザー向け製品ガイド（製品を使用する技術者以外の人向け）のゲートです。対象となるドキュメントと読者が異なります。
• developer-guide-review スキル——SDK／CLI／プラットフォームの導入と統合について説明し、このリファレンスを参照する内容のゲートです。対象となるドキュメントと基準が異なります。このスキルが評価するのは、リンク先のエンドポイントカタログです。
• design-review スキル——汎用的なエンジニアリング設計ドキュメント（仕様書／計画／RFC／ADR）のゲートです。上流のエンジニアリング api-spec ワイヤー契約には専用のゲート reviewing-api-spec があり、design-review の対象外です。ゲートと成果物が異なるため、公開済みの利用者向けリファレンスには使用しません。
• api-reference テンプレート／content-template ツール——セクションの構成を担います。このスキルが評価するのは基準に照らした品質であり、構成への準拠ではありません。

段階的な情報開示

• references/usability-consistency-bar.md — 条件ごとの合格／不足のシグナルと、詳しく説明した条件および新規条件に関する調査結果の例（認証フローの詳細度、Problem Details エラー、RateLimit／冪等性、非推奨化／廃止、ページネーションの条件 10、差分スコープの修正に関する条件 11）。条件ごとの詳細なシグナルが必要な場合に読み込んでください。
• references/sources.md — レビューメソッドと単一ソース化された基準の調査来歴。ガイダンスの出典を監査する場合にのみ読み込んでください。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）です。Claude は一覧表示で description と when_to_use の合計が 1,536 文字を超えると切り詰めます。
• 本文は約 500 行／5,000 トークン以下にしてください。毎ターン、コンテキストに保持されます。
• 参照ファイルごとに、10k トークン超で警告、25k トークン超でエラーとします。参照ファイル全体では、25k トークン超で警告、50k トークン超でエラーとします。

変更履歴

• 1.1.0（2026-06-14）— 本番向けの構成に再編（追加のみ。authoring-api-reference の Step-6 セルフチェックと単一ソース化）。基準を 9 条件から 11 条件に拡張：cond-10 ページネーション／リスト操作の慣例（比例的）と cond-11 差分スコープの修正（入力シグナルで判定、新規開発では該当なし）を追加。cond-1（認証フローの詳細度）、cond-3（RFC 9457 Problem Details と機械可読コード）、cond-4（RateLimit-*/ジッター／冪等性）、cond-7（Sunset／Deprecation の仕組みと移行）を拡充。cond-5 の条件文は負荷を担う要素として逐語的に維持し、確認方法を拡充（SSoT／コントラクトテストを使用し、カタログを手作業で再入力しない）。cond-2 にコントラクトで宣言されたイベント／Webhook を追加。API スタイルのオーバーレイと Webhook ドキュメントの手法は、成果に基づいて評価する補助として維持。レンダリング媒体の DX（検索／お試し実行／a11y／i18n）は対象外として設定。references/usability-consistency-bar.md を追加し、sources.md を可搬化。VERDICT: approve|revise と入力コントラクトは変更なし。
• 1.0.0（2026-06-05）— 初回レビュー済みリリース。