api-designer

api-designerスキルの概要

api-designerスキルでできること

api-designer スキルは、一般的な「API を設計して」という曖昧なプロンプトよりも、構造だった形で REST と GraphQL の API 設計・レビューを進められるスキルです。プロダクト要件を、実際に使える API の形へ落とし込むことを目的としており、リソース設計、エンドポイントやスキーマのパターン、HTTP メソッド、ステータスコード、ページネーション、認証、エラーハンドリング、バージョニングまで整理できます。

api-designerスキルを使うべき人

この api-designer スキルは、API のたたき台設計、レビュー用チェックリスト、再利用しやすい仕様ドラフトを必要とする開発者、テックリード、プラットフォームチーム、アーキテクトに向いています。抽象的な助言だけでなく、短時間で一貫した出発点を作りたい場面で特に有効です。

実際のジョブ・トゥ・ビー・ダン

多くの利用者が必要としているのは API 理論そのものではありません。「ユーザー管理が必要」から、「議論・検証・実装に回せる妥当な API 設計書がある」までを前に進めることです。api-designer スキルは、そのギャップが開発の停滞要因になっているときや、チームごとに API の判断がばらついているときに最も価値を発揮します。

このスキルが他と違う点

最大の違いは、このスキルが単なるプロンプト集ではないことです。REST と GraphQL の設計パターンをまとめた参照ファイルに加え、実用的なスクリプトが 2 つ含まれています。

• scripts/generate_api.py：設計書の初期ドラフトを生成
• scripts/validate_api.py：主要な設計セクションがそろっているか確認

そのため、単に助言だけを返す軽量スキルよりも、具体的な成果物と最低限の検証ステップが欲しいなら、api-designer の導入価値は高めです。

得意なことと手薄な領域

api-designer for API Development は、標準的な API 構成、CRUD ベースのリソース設計、基本的な REST の慣例、GraphQL スキーマ設計のガイドに強みがあります。一方で、高度なドメインモデリング、イベント駆動 API、長時間実行ワークフロー、分散整合性、組織固有のガバナンスにはあまり踏み込みません。万能な API 審査会の代わりではなく、堅実な土台として使うのが適切です。

api-designerスキルの使い方

api-designerスキルのインストール前提

このスキルは zhaono1/agent-playbook リポジトリ内の skills/api-designer にあります。
https://github.com/zhaono1/agent-playbook/tree/main/skills/api-designer

スキル実行環境がリポジトリベースのインストールに対応している場合は、その環境の標準的な手順でこのリポジトリを導入し、api-designer を選択してください。手元のリポジトリ概要には npx skills add ... --skill api-designer のような例が出ている場合がありますが、スキル自身の SKILL.md には専用のインストールコマンドは定義されていません。実際の導入は、使っている環境がサポートする方法に従うのが安全です。

まず読むべきファイル

手早く要点をつかみたい api-designer guide としては、まず次の順番で読むのがおすすめです。

1. skills/api-designer/SKILL.md
2. skills/api-designer/references/rest-patterns.md
3. skills/api-designer/references/graphql-patterns.md
4. skills/api-designer/scripts/generate_api.py
5. skills/api-designer/scripts/validate_api.py

この順番には意味があります。SKILL.md で起動条件と設計原則を把握し、参照ファイルで慣例を具体化し、最後にスクリプトでこのスキルが想定している成果物の形を確認できます。

このスキルに必要な入力

api-designer usage の質は、何を渡すかに大きく左右されます。最低限、次の情報は入れてください。

• API スタイル：REST、GraphQL、または両方
• ドメインと主要リソース
• ユーザーが行う主な操作
• 認証モデル
• 利用者の種類：社内向け、パートナー向け、公開 API
• 非目標と制約
• ページネーション、フィルタリング、エラー処理の期待値
• 後方互換性やバージョニングが重要かどうか

これらがないと、このスキルは汎用的な CRUD パターンに寄りがちです。

曖昧な依頼を強いプロンプトに変える

弱いプロンプト：

• “Design an API for orders.”

より強いプロンプト：

• “Use the api-designer skill to draft a REST API for order management for an internal admin tool. Core resources: orders, customers, refunds. Needed operations: list orders with filtering by status and date, get order details, create refund, update fulfillment status. Auth is service-issued bearer tokens. Must support pagination, standardized error responses, and future versioning. Non-goals: payments processing and bulk export. Produce a design doc with endpoints, request/response examples, status codes, auth, rate limits, and error model.”

この形が有効なのは、対象範囲を絞り、制約を表に出し、このスキルが扱いやすい成果物の形を明示しているからです。

付属ジェネレーターで仕様ドラフトを作る

リポジトリには、出発点として便利なジェネレーターが入っています。

python skills/api-designer/scripts/generate_api.py --name orders --owner platform-team --output api-design.md

これは、パターンを手で写すより api-designer install を使う価値が高い理由のひとつです。以下のようなセクションを含むドラフトをすぐに作れます。

• ## Overview
• ## Ownership
• ## Goals
• ## Non-Goals
• ## Resources
• ## Endpoints

まずこれを生成してから、モデルに設計を磨かせるのがおすすめです。白紙から始めるより、構造化されたドラフトを編集したほうが結果は安定します。

レビュー前に設計を検証する

仕様を生成または修正したら、バリデーターを実行します。

python skills/api-designer/scripts/validate_api.py --input api-design.md

このバリデーターは、少なくとも次の必須セクションがあるかを確認します。

• ## Overview
• ## Ownership
• ## Resources
• ## Endpoints
• ## Authentication
• ## Error Model
• ## Pagination
• ## Rate Limits

独自の必須セクションを追加することもできます。

python skills/api-designer/scripts/validate_api.py --input api-design.md --require "## Versioning"

これは意味内容まで精査するレビューではなく、あくまで基本的な検証です。ただし、不完全なドラフトを早い段階で見つけるには十分役立ちます。

このスキルに合う REST ワークフロー

REST では、次の順序で進めるとこのスキルの強みが出やすくなります。

1. 操作ではなく名詞としてリソースを定義する
2. 操作を GET、POST、PUT、PATCH、DELETE に割り当てる
3. パス設計と collection/item パターンを決める
4. ステータスコードとエラーモデルを定義する
5. ページネーション、フィルタリング、認証、レート制限を加える
6. 命名とバージョニングを見直す

リポジトリの例も、/getUsers のような動詞中心パスより、/users や /users/{id} のようなリソース指向設計を明確に推しています。

このスキルに合う GraphQL ワークフロー

GraphQL では、参照ファイルを使ってモデルを次の方向へ誘導すると効果的です。

• わかりやすい型名
• 汎用的すぎるフィールドを減らす
• cursor ベースのページネーション
• 複雑な mutation では input object を使う
• mutation のレスポンスで更新後エンティティとエラーを返す

このスキルはスキーマ構造の設計には役立ちますが、ドメイン固有の問い合わせパターンまで具体的に与えないと、見た目は整っていても実際のフロントエンドや連携要件に合わない浅いスキーマになりがちです。

api-designer usageの実践的なプロンプトパターン

安定して使いやすいテンプレートは次のとおりです。

Use the api-designer skill.

Design a [REST/GraphQL] API for [product or workflow].
Users: [who consumes it]
Core resources/types: [list]
Main operations: [list]
Auth: [model]
Constraints: [compliance, performance, backward compatibility, public/internal]
Non-goals: [list]
Need included: endpoints or schema, examples, pagination, error model, versioning, rate limits.
Output format: a markdown design doc ready for team review.

このプロンプト構造は、ジェネレーターやバリデーターが想定する形と噛み合っているため、無理に逆らうより出力品質が上がりやすくなります。

導入判断のためのおすすめリポジトリ確認順

api-designer skill を採用するか見極めたいなら、次を確認してください。

• SKILL.md：対象範囲と設計慣例
• references/rest-patterns.md：REST ガイダンスの意見の強さ
• references/graphql-patterns.md：GraphQL との相性
• scripts/generate_api.py：テンプレートの実用性
• scripts/validate_api.py：ワークフローの成熟度

これらが自チームの設計書の書き方に近いなら、導入する価値はあります。逆に、OpenAPI 生成、ポリシー lint、厳密なプロトコルガバナンスまで必要なら、このスキル単体ではやや軽めです。

api-designerスキル FAQ

api-designerは初心者にも向いているか

はい。ただし、基本的な API の概念をすでに理解している初心者向けです。api-designer スキルは構造と慣例を与えてくれますが、なぜあるリソース設計が別案より良いのかまで学習の代わりをしてくれるわけではありません。あくまでガイド付きの足場であり、完全なチュートリアルではありません。

普通のプロンプトより良いのか

多くの場合、再現性の面で優れています。素のプロンプトでも一度きりなら許容できるエンドポイント案は出せますが、api-designer skill には参照資料とスクリプトを含む再利用可能なワークフローがあります。複数サービスや複数レビュアーで一貫性を保ちたいなら、この差は大きいです。

api-designerはRESTとGraphQLの両方に対応しているか

対応しています。リポジトリには SKILL.md の REST 原則に加え、REST と GraphQL の両方について別々の参照ファイルがあります。実運用の感覚としては、一般的な REST 設計のほうがより具体的で、GraphQL ガイドは有用ではあるものの少し軽めです。

api-designerを使わないほうがよいのはどんなときか

主な課題が次のいずれかなら、api-designer for API Development は見送ったほうがよいです。

• イベント駆動やストリーミングのインターフェース設計
• 非同期ワークフローのオーケストレーション
• REST/GraphQL を超えるプロトコル固有設計
• OpenAPI-first パイプライン、正式なレビューゲート、互換性試験を伴う厳格なエンタープライズガバナンス

こうしたケースでは、このスキルは粗い初期案づくりに留めるのが現実的です。

本番投入できる仕様を生成できるか

それだけで本番品質にはなりません。もっともらしい設計ドラフトを作り、主要セクションの存在を確認することはできますが、ドメインレビュー、セキュリティレビュー、命名の整理、実装レベルの判断は別途必要です。バリデーターが確認するのは完全性であって、正しさではありません。

api-designer installには自動的な強制チェックが含まれるか

ごく軽量です。付属のバリデーターは必須見出しを確認するだけで、HTTP セマンティクス、スキーマの正確性、互換性保証までは見ません。より強い強制力が必要なら、OpenAPI の linter、contract test、GraphQL スキーマ用ツールと組み合わせるべきです。

api-designerスキルを改善する方法

プロダクト制約をより明確に渡す

api-designer の出力品質を最も大きく改善するのは、制約条件を具体化することです。たとえば次を含めてください。

• 利用者は誰か
• どの操作が最も頻繁に使われるか
• 何を安定維持する必要があるか
• 意図的に対象外とするものは何か
• 想定される一覧件数とページネーション要件
• エラーはクライアント向けにわかりやすさ重視か、連携向けに機械処理重視か

これにより、実際の利用パターンを無視した汎用 CRUD 設計を避けやすくなります。

単なる文書化ではなく設計判断を求める

「API 仕様を書いて」ではなく、判断を伴う依頼にすると効果が上がります。

• REST と GraphQL のどちらを採るべきか、その理由も含めて選ばせる
• PATCH と PUT のどちらが適切かを説明させる
• cursor と offset のページネーションを比較して推奨させる
• バージョニング戦略を提案させる
• エラー envelope を定義させる

こうすることで、api-designer guide は単なる markdown 整形役ではなく、設計アシスタントとして機能します。

よくある失敗パターンに注意する

弱い出力には、次のような傾向があります。

• /createUser のような動詞ベースのエンドポイント
• 認証前提が抜けている
• ステータスコードはあるのにエラーボディ構造がない
• GraphQL スキーマのフィールドが曖昧
• 一覧系エンドポイントにページネーション方針がない
• 非目標がなく、スコープが膨らむ

これらは偶発的なミスではなく、たいてい初期プロンプトの具体性不足が原因です。

リポジトリ付属スクリプトで初稿を改善する

実務的には、次の改善ループが有効です。

1. generate_api.py で初期ドキュメントを生成する
2. api-designer スキルでその内容をエージェントに修正させる
3. validate_api.py を実行する
4. 足りないセクションや独自要件を追加する
5. 命名、一貫性、エッジケースを深掘りするために再度スキルを使う

一回の生成で完璧な設計を狙うより、この流れのほうが安定します。

実際の利用者行動の例を渡す

api-designer usage を改善する強い方法のひとつは、現実のリクエスト例をいくつか添えることです。

• “Admin lists failed orders from the last 7 days”
• “Support agent retrieves a customer’s active subscriptions”
• “Partner app creates a refund with a reason code”

こうした例があると、このスキルはリソース設計、フィルタ、mutation の形、レスポンス項目をより現実に沿って選びやすくなります。

チーム基準に合わせて必須セクションを追加する

組み込みのバリデーターは、意図的にシンプルに作られています。必要に応じて、チームで重視するセクションを必須化してください。たとえば次のような項目です。

• ## Versioning
• ## Idempotency
• ## Observability
• ## Deprecation Policy
• ## Webhooks

こうすることで、コアのプロンプト内容を変えなくても、api-designer skill を実際の開発フローにより近づけられます。

api-designerを生成専用ではなくレビュー用途でも使う

価値の高い使い方のひとつは、既存の API 設計を貼り付けて、このスキルに次の観点でレビューさせることです。

• リソース命名の一貫性
• メソッドの誤用
• 不足しているステータスコード
• ページネーションの抜け
• GraphQL mutation 設計の問題
• 認証やエラー関連セクションの不足

このリポジトリの原則はコンパクトでチェックリスト化しやすいため、新規生成よりレビュー用途のほうがハマる場面も少なくありません。