# API Skill

[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)

API Skill は、フロントエンド開発と AI 支援開発のためのローカル OpenAPI/Swagger ワークスペースです。人向けの Web ワークスペースと AI Agent 向けの CLI/MCP インターフェースが、同じキャッシュ済み API ドキュメントを共有します。

- Web アプリ: 人が API ドキュメントをインポート、閲覧、検索、確認、テストし、バージョンと API 操作を管理するための画面。
- CLI: AI Agent や自動化処理がドキュメント状態を確認し、必要な API コンテキストを取得・保守するためのコマンド。
- MCP サーバー: 同じ API の照会・保守機能を Codex や他の AI Agent クライアントへ公開。

## Web アプリの使い方

プロジェクトルートで起動します。

```bash
npm install
npm run dev
```

ターミナルに表示されたローカル Vite URL を開きます。Web アプリは、直接 OpenAPI JSON/YAML URL のインポート、Swagger UI / Knife4j / Redoc ページのクロール、ローカルファイルのアップロード、OpenAPI ドキュメントを返す curl コマンドの実行、空白ドキュメントの新規作成に対応しています。

インポートまたは新規作成後は、バージョンセレクタでキャッシュ済みドキュメントを切り替え、path、summary、tag、method、パラメータテキストでエンドポイントを検索できます。エンドポイントタブでは、リクエストパラメータ、リクエストボディ、レスポンスフィールド、AI 向けコンテキスト、Raw JSON を確認できます。手動 API 操作の追加、編集、削除も可能で、変更はローカルのキャッシュバージョンとして保存されます。

CLI と MCP を使う前に、まず組み込みチェックを実行してください。

```bash
npm run cli -- check
```

CLI でゼロから始める場合は、`npm run cli -- document create --title "My API" --doc-version 1.0.0` で空白ドキュメントを作成し、`api create` でエンドポイントを追加します。MCP クライアントでは、`apiskill_check` でキャッシュを確認し、上流ドキュメントがない場合は `apiskill_create_document` で空白ドキュメントを作成し、`apiskill_help` で利用可能なツールを確認します。

## このツールを開発した理由

大規模 AI モデルが登場してからの数年間で、開発者が AI を使ってコードを書く方法は大きく変化してきました。最初は ChatGPT の Web 画面でコード、エラー、API ドキュメントをコピー&ペーストする使い方が中心でした。その後、Cursor、Codex、Claude Code のようにプロジェクト全体へ統合できるデスクトップまたはローカル開発ツールが登場し、AI 開発は単発の質問からプロジェクト全体のコンテキストを扱う形へ移っていきました。

API ドキュメントの扱い方も変わりました。初期は API ドキュメントをそのまま貼り付けたり、ドキュメント画面のスクリーンショットを渡したりしていました。さらに Context7 のようなツールによって、AI アシスタントが Web 上の API ドキュメントを直接読めるようになりました。これは大きな進歩ですが、実際の開発ではまだいくつかの問題が残ります。

- AI が Web ドキュメントを読み取り解析するには追加 token が必要で、大きな Swagger、Knife4j、製品ドキュメントでは無駄と待ち時間が大きくなります。
- 社内ドキュメントでは、ログイン、cookie、アクセスキー、社内ネットワークなどのアクセス制御を扱う必要があることがよくあります。
- AI がドキュメントを読めたとしても、ドキュメントを新規作成、編集、修正、バージョン管理する能力は通常そのままでは提供されません。

API Skill は、このギャップを埋めるために作られました。API ドキュメントをローカルにインポート、クロール、ゼロから作成、照会、編集、バージョン管理し、同じ構造化された契約を Web アプリ、CLI、MCP サーバーから利用できるようにします。目標は、API ドキュメントを何度も貼り付けるテキストやスクリーンショットではなく、AI アシスタントが安定して利用し継続的に管理できるプロジェクトレベルのツールにすることです。

### Token 効率

実際の削減量は、ドキュメントサイズ、schema の深さ、タスクに必要な周辺コンテキストによって変わりますが、実務上の傾向は一貫しています。

| Workflow | モデルへ送る典型的なコンテキスト | 再利用性 | 期待される token 影響 |
| --- | --- | --- | --- |
| ドキュメントのスクリーンショット | 画像 token と表示ページ全体の視覚的解析 | 低 | 高コストで、正確なフィールド引用が難しい |
| ドキュメント本文の貼り付け | ページ全体の本文、ナビゲーション、例、多くの無関係なエンドポイント | 低-中 | タスクごとに数千から数万 token になりやすい |
| Context7 のような Web ドキュメント読取ツール | AI がリクエスト時に Web ドキュメントを読み取り要約する | 中 | 手動貼り付けより便利だが、ページ取得、解析、広いドキュメントコンテキストのコストは残る |
| CLI/MCP の対象指定クエリ | 1 つのエンドポイントまたは schema を構造化 JSON/Markdown で返す | 高 | API ドキュメント部分を通常約 70-95% 削減 |
| MCP 検索後に詳細取得 | 小さな候補リストの後で正確なエンドポイント詳細を取得 | 高 | 大きな API セットに最適で、数百から数千 token に収まりやすい |

保守的な例として、Knife4j/Swagger のモジュールドキュメントをコピーすると 10,000-30,000 token になる場合でも、単一エンドポイント向けの `apiskill_get_endpoint` または `apiskill_query_api` の応答は多くの場合 500-2,000 token 程度です。ドキュメント部分だけで約 5 倍から 60 倍の削減になります。同じドキュメントをフロントエンド、バックエンド、テスト作業で繰り返し使うほど、ローカルキャッシュにより効果は積み上がります。

Context7 のような Web ドキュメント読取ツールは、ドキュメントが公開されていて最新の上流情報を参照したい場合に便利です。一方で、社内 API ドキュメントや繰り返し行うプロダクト開発では API Skill の方が予測しやすくなります。ドキュメントはすでにローカルに取り込まれ、アクセス処理は一度で済み、AI は広い Web ページを読み直す代わりに狭いローカル契約を照会または編集できるためです。

より大きな価値は、token が安くなることだけではありません。構造化 lookup は無関係なコンテキストを減らし、フィールド名、必須フラグ、型、レスポンス構造を保持しやすくし、本当に必要なときだけ深い schema を追加で取得できます。

### 総合的な費用対効果

API Skill のコストは主に初期設定です。依存関係をインストールし、ドキュメントをインポートまたはクロールし、CLI または MCP アクセスを設定します。その後は同じキャッシュが日常の開発を支えます。エンドポイントが多い、schema が深い、複数人で開発している、AI 支援タスクが繰り返されるプロジェクトでは、早い段階で元が取れます。

主なリターンは次の通りです。

- 大きなドキュメントやスクリーンショットを繰り返しプロンプトへ入れる量を減らします。
- agent に、記憶や視覚抽出ではなく決定的な API 探索ツールを提供します。
- 上流ドキュメントが実装に遅れているときも、ローカル修正を保持できます。
- 元のドキュメントソースを変えずに、ターミナル、エディタ、MCP クライアント、Web アプリで API コンテキストを使えます。

エンドポイントが少なく安定している小規模プロジェクトでは、コピー&ペーストでも十分な場合があります。ただし、ページ、サービス、mock、テストを変化する API 契約に合わせて繰り返し実装するチームでは、CLI/MCP アクセスがコンテキストコストと統合ミスを同時に減らします。

### CLI と MCP の使い分け

CLI は最も移植性が高く、決定的な入口です。任意の shell、CI job、エディタ task、コマンドを実行できる AI ツールから利用できます。スクリプト化された一括更新、import/export 検証、再現可能な自動化では、CLI の方がデバッグしやすく共有もしやすいことが多いです。ユーザーや自動化が正確なコマンドだけを実行し、簡潔な結果だけを会話に戻すなら、CLI も token 効率に優れます。

MCP は agent ワークフローに向いています。MCP 対応の AI クライアントはツールを発見し、`apiskill_search_endpoints`、`apiskill_create_document`、`apiskill_create_api`、`apiskill_get_endpoint` を直接呼び出し、構造化された結果だけを受け取れます。ユーザーがコマンド出力や API ドキュメント全体を貼り付ける必要がないため、prompt token を節約できることが多いです。一方で互換性の条件があります。AI ツールが stdio MCP server と tool schema をサポートする必要があり、クライアントによって timeout 処理、作業ディレクトリ設定、承認 UX、ツール結果の表示が異なる場合があります。

CLI と MCP が同じ shared core に同じ payload を渡す場合、生成される API ドキュメントの内容は同じになるべきです。汎用自動化と CI での再現性を重視するなら CLI、AI agent がコーディング中に API ドキュメントを自律的に検索、作成、編集、照会するなら MCP を選びます。

### プロジェクト統合の効果

フロントエンドチームは、ページ、hooks、リクエスト client、フォーム、テーブル、バリデーションロジックを作るときに正確なエンドポイント契約を参照できます。レスポンスフィールド lookup は、ドキュメントページ全体をプロンプトに貼らずに API データを UI 状態へマッピングする助けになります。

バックエンドチームは、同じキャッシュで既存契約を確認し、手動変更を比較し、上流 OpenAPI ドキュメントが更新される前に一時的または修正済みのローカル操作を公開できます。実装とドキュメントが少しずれている場面で特に有用です。

テスト自動化では、同じエンドポイント詳細から mock、fixture payload、contract assertion、end-to-end の準備データを生成またはレビューできます。CLI と MCP がキャッシュを共有するため、テストはリモートドキュメントサイトの現在状態ではなく既知のバージョンに固定できます。

Agent ワークフローでは MCP が最も効果的です。コーディング agent は `apiskill_search_endpoints` で検索し、`apiskill_get_endpoint` で正確なエンドポイントを確認し、必要なら `apiskill_get_schema` で schema コンテキストを取得してからコードを実装または更新できます。API ドキュメントは巨大なテキストではなく、プロジェクトレベルのツールになります。

## ドキュメント

- Web アプリ: [English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
- CLI 設定と使い方: [English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
- MCP 設定と使い方: [English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

## データモデル

すべての入口は同じキャッシュを読み書きします。

```text
cache/latest-import.json
cache/versions/
```

Web アプリと CLI は、リモートまたはローカルの OpenAPI ドキュメントをインポートできます。MCP サーバーはキャッシュを照会でき、明示的に書き込みツールを呼び出した場合は、ドキュメントのインポートや手動 API 操作の作成、編集、削除も行えます。