postman

Postman Agent Skill

バージョン: 1.1.0 (フェーズ 1 - コア API 互換性) API サポート: Postman v10+ (v9 ではグレースフルデグラデーションに対応)

🚀 クイックスタート

このスキルを初めて使用すると、Claude が自動的に以下を実行します:

1. ✅ API キーと接続を検証します
2. 📁 ワークスペースの設定を確認します
3. 📊 コレクションとリソースの数をカウントします
4. 💡 セットアップが不完全な場合は次のステップを提案します

初回セットアップの検証:

# Claude will run this automatically on first use
python scripts/validate_setup.py

すぐに使えるよくある最初の質問:

• 「コレクションはいくつありますか?」 - ワークスペース内のすべてのコレクションを一覧表示します
• 「ワークスペースを表示して」 - 利用可能なワークスペースを表示します
• 「セットアップを検証して」 - 包括的な診断を実行します
• 「『Test API』という名前の新しいコレクションを作成して」 - すぐに構築を開始します

🤖 Claude への注意: 会話でこのスキルを初めて使用する際は、必ず以下を実行してください:

python scripts/validate_setup.py

これにより、ユーザーのリクエストを処理する前に、即座に診断とコンテキストが提供されます。

✅ ネットワーク互換性

このスキルは、適切なプロキシ設定を行うことで、複数の Claude 環境で動作します。

このスキルが動作する環境

環境	ステータス	備考
Claude Web インターフェース	✅ 完全サポート	設定済みのプロキシで動作します
Claude API (コード実行)	✅ 完全サポート	ネットワーク制限はありません
ローカル Python スクリプト	✅ 完全サポート	お使いのマシン上で直接実行できます
Claude Desktop	⚠️ 制限あり	ネットワーク許可リストに api.getpostman.com が必要です

プロキシ設定

このスキルはプロキシ環境で動作するように設計されています:

• プロキシ環境変数をそのまま維持し、適切な DNS 解決を実現します
• プロキシサーバーからのネストされた HTTP レスポンスを処理します
• プロキシ経由の HTTP/2 レスポンスをサポートします
• デバッグモードは POSTMAN_DEBUG=1 環境変数で利用できます

このスキルの使用方法

オプション 1: Claude Web インターフェース (推奨) Claude Web インターフェースでこのスキルを直接使用します。プロキシは事前に設定されており、すべてのネットワークリクエストを自動的に処理します。

オプション 2: コード実行を伴う Claude API コード実行を有効にして Anthropic API 経由でこのスキルを使用します。ネットワーク制限はありません。

オプション 3: ローカル Python スクリプト スクリプトをお使いのマシン上で直接実行します:

python scripts/list_collections.py
python scripts/manage_collections.py --list

概要

このスキルは、Claude が Postman API と連携して API ライフサイクル全体を管理できるようにします。ワークスペースリソースの検出、テストコレクションの実行、モニタリング分析などが可能になります。

v1.1 の新機能 (フェーズ 1)

✨ 強化されたエラー処理: 解決のヒントを備えたカスタム例外クラス 🔀 Git ライクなワークフロー: コレクションのフォーク、プルリクエストの作成、変更のマージ 🔐 自動シークレット検出: 機密性の高い環境変数を自動的に保護します 🔄 スマートな複製: コレクションと環境を完全な忠実度でコピーします 📡 API バージョン検出: 互換性の警告を伴う自動検出 🎯 開発者エクスペリエンスの向上: 簡素化された API とより良いエラーメッセージ

機能

• 検出: ワークスペース内のコレクション、API、仕様、環境、モニターを一覧表示します
• 設計: API 仕様の管理、スキーマの検証、バージョンの比較、API の定義を行います
  • 🆕 Spec Hub: API 仕様 (OpenAPI 3.0、AsyncAPI 2.0) を作成および管理します
  • 🆕 マルチファイル仕様: スキーマファイルを分離したモジュール型仕様をサポートします
  • 🆕 双方向生成: 仕様からコレクションを生成、またはコレクションから仕様を生成します
  • API スキーマの検証とバージョンの比較を行います
• 構築: コレクションと環境の作成、更新、削除を行います
  • 🆕 フォークとマージ: コレクション向けの Git ライクなバージョン管理 (v10 以降)
  • 🆕 プルリクエスト: コレクションを共同編集するワークフロー (v10 以降)
  • 🆕 スマート複製: 完全なメタデータを含めてコレクションと環境をコピーします
• テスト: Newman でコレクションのテストスイートを実行し、結果を分析します
• セキュア: 認証設定とセキュリティ設定を確認します
  • 🆕 シークレット自動検出: 機密性の高い変数を自動的にシークレットとしてマークします
  • 🆕 シークレットの保持: 操作を通じてシークレット型を維持します
• デプロイ: API プロトタイピング用のモックサーバーを作成および管理します
• 監視: 継続的な API モニタリング用のモニターを作成、管理、分析します
• 配布: API ドキュメントの品質を表示および評価します

このスキルを使用する場面

Claude は、次のような場合にこのスキルを使用する必要があります:

• Postman、コレクション、API 仕様、または API テストに言及した場合
• API 仕様 (OpenAPI、AsyncAPI、Swagger) を作成または管理したい場合
• API 仕様を Postman にアップロードまたはインポートする必要がある場合
• API 仕様からコレクションを生成したい場合
• 既存のコレクションから仕様を生成したい場合
• API スキーマを検証したり、バージョンを比較したりしたい場合
• コレクションまたは環境を作成、更新、削除したい場合
• コレクションと環境を複製または整理する必要がある場合
• 認証またはセキュリティ設定の確認を依頼した場合
• プロトタイピング用のモックサーバーの作成を依頼した場合
• テストの実行またはテスト結果の確認を依頼した場合
• 利用可能な API、コレクション、仕様を確認したい場合
• モニターを作成、管理、または分析する必要がある場合
• API の稼働時間、モニタリング、または可観測性について質問した場合
• モニターのステータスまたは実行履歴を確認したい場合
• API ドキュメントの品質またはアクセスについて質問した場合

前提条件

このスキルには、Postman API キーを含む .env ファイルが必要です。.env ファイルはスキルパッケージに含める必要があり、スクリプトの実行時に自動的に読み込まれます。

重要: スキルが API キーを要求している場合、.env ファイルが次のいずれかの状態であることを意味します:

• スキルパッケージに存在しない
• 空であるか、形式が正しくない
• スクリプトから読み取りできない

修正方法: スキルパッケージに次の内容を含む .env ファイルが含まれていることを確認してください:

POSTMAN_API_KEY=PMAK-your-key-here

.env でのオプション設定:

POSTMAN_WORKSPACE_ID=your-workspace-id
POSTMAN_RATE_LIMIT_DELAY=60
POSTMAN_MAX_RETRIES=3
POSTMAN_TIMEOUT=30
# POSTMAN_USE_PROXY=false  # Keep this false to bypass proxies (default)

プロキシ設定 (企業ネットワークで重要)

デフォルトでは、このスキルはすべてのプロキシサーバーをバイパスします。これは、Claude Desktop でよく発生する「403 Forbidden」プロキシエラーを回避するためです。

次のようなエラーが表示される場合:

• ProxyError: Unable to connect to proxy
• Tunnel connection failed: 403 Forbidden

このスキルは自動的に対処します - 操作は不要です。最新バージョンはデフォルトでプロキシをバイパスします。

企業環境にいて、プロキシを使用する必要がある場合:

1. .env ファイルに POSTMAN_USE_PROXY=true を追加します
2. プロキシが api.getpostman.com への接続を許可していることを確認します

Postman API キーの取得

1. https://web.postman.co/settings/me/api-keys にアクセスします
2. 「Generate API Key」をクリックします
3. キー (PMAK- で始まる) をコピーします
4. スキルディレクトリの .env ファイルに追加します

このスキルの使用方法 - 重要

⚠️ 重大: Postman API の呼び出しはすべて Python スクリプトを通じて行う必要があります

このスキルは、Postman API とやり取りするために Python スクリプトを使用します。ブラウザー環境では CORS (Cross-Origin Resource Sharing) の制限により失敗するため、HTTP リクエストを使用して api.postman.com を直接呼び出そうとしないでください。

常に Python スクリプトを使用してください:

# ✅ CORRECT: Use Python scripts
python /path/to/postman-skill/scripts/list_collections.py

# ❌ WRONG: Direct API calls will fail with CORS errors
# fetch('https://api.getpostman.com/collections')  # This will NOT work

これが重要な理由:

• Python の requests ライブラリは CORS の制限を受けません
• ブラウザーから api.postman.com への直接的な API 呼び出しは CORS によってブロックされます
• すべてのスクリプトは .env ファイルから API キーを自動的に読み込みます

利用可能なワークフロー

リソースの検出

ファイル: workflows/test/list_collections.md

ワークスペース内のすべてのコレクション、環境、モニターを一覧表示し、利用可能なリソースを把握します。

API スキーマの検証

ファイル: workflows/design/validate_schema.md

API スキーマを OpenAPI/Swagger 標準に照らして検証します。スキーマ構造を確認し、API バージョンを取得し、デプロイ前に API 定義が正しい形式であることを確認します。

API バージョンの比較

ファイル: workflows/design/version_comparison.md

API の異なるバージョンを比較し、変更点、破壊的な更新、移行要件を特定します。API ガバナンスとバージョン管理に不可欠です。

API 仕様の管理 (Spec Hub)

ファイル: workflows/design/manage_specs.md

Postman の Spec Hub を使用して API 仕様を作成および管理します。これは API 定義を管理するための現代的で推奨されるアプローチです。

🆕 新機能:

• 仕様を直接作成 (OpenAPI 3.0、AsyncAPI 2.0)
• 単一ファイルおよびマルチファイルの仕様をサポート
• 仕様からコレクションを自動生成
• 既存のコレクションから仕様を生成
• YAML および JSON 形式をサポート
• 非推奨の create_api() ワークフローを置き換えます

コレクションの管理

ファイル: workflows/build/manage_collections.md

Postman コレクションの作成、更新、削除、複製を行います。新しいテストコレクションを構築し、既存のコレクションを整理し、コレクションのライフサイクルをプログラムで管理します。

🆕 v1.1 拡張機能:

• 独立した開発のためにコレクションをフォーク
• プルリクエストの作成と管理
• フォークからの変更のマージ
• 完全なメタデータを保持したコレクションの複製

環境の管理

ファイル: workflows/build/manage_environments.md

Postman 環境の作成、更新、削除、複製を行います。さまざまなステージ (dev、staging、production) 用の環境変数を設定し、環境構成を管理します。

🆕 v1.1 拡張機能:

• 機密変数 (api_key、token、password など) の自動シークレット検出
• 既存のシークレットを保持する部分更新
• シークレットを保持した環境の複製
• 環境をすばやく作成するための簡素化された dict ベースの API

コレクションテストの実行

ファイル: workflows/test/run_collection.md

Newman を使用してコレクションのテストスイートを実行し、成功、失敗、詳細な診断を示す形式化された結果を取得します。Newman CLI がインストールされている必要があります。

認証の確認

ファイル: workflows/secure/check_auth.md

コレクション内の認証構成を確認します。認証タイプを特定し、セキュリティ設定を確認し、API セキュリティを改善するための推奨事項を取得します。

モックサーバーの管理

ファイル: workflows/deploy/manage_mocks.md

API プロトタイピングおよびフロントエンド開発用のモックサーバーを作成、更新、管理します。バックエンドを実装せずにテストを可能にします。

モニターの管理

ファイル: workflows/observe/manage_monitors.md

継続的な API 監視のために Postman モニターを作成、更新、削除、分析します。モニターの実行履歴、成功率、パフォーマンス指標を表示し、API の信頼性を確保します。

ドキュメントの表示

ファイル: workflows/distribute/view_documentation.md

API ドキュメントにアクセスし、その品質を評価します。ドキュメントの完全性を確認し、エンドポイントの説明をレビューし、ドキュメントを改善するための推奨事項を取得します。

アーキテクチャ

このスキルは段階的な開示を使用します:

1. メタデータ (常に読み込まれます): YAML フロントマターのスキル名と説明
2. SKILL.md (トリガーされたときに読み込まれます): この概要ドキュメント
3. ワークフローファイル (必要に応じて読み込まれます): 具体的な手順ごとの指示
4. Python スクリプト (実行され、読み込まれません): 実際の API 操作コード

ファイル構造

postman-skill/
├── SKILL.md                      # This file - skill overview
├── workflows/
│   ├── test/
│   │   ├── list_collections.md   # Discovery workflow
│   │   └── run_collection.md     # Test execution workflow
│   ├── design/
│   │   ├── manage_specs.md       # 🆕 Spec Hub management workflow (NEW!)
│   │   ├── validate_schema.md    # Schema validation workflow
│   │   └── version_comparison.md # API version comparison workflow
│   ├── build/
│   │   ├── manage_collections.md # Collection management workflow
│   │   └── manage_environments.md # Environment management workflow
│   ├── secure/
│   │   └── check_auth.md         # Authentication check workflow
│   ├── deploy/
│   │   └── manage_mocks.md       # Mock server management workflow
│   ├── observe/
│   │   └── manage_monitors.md    # Monitor management workflow
│   └── distribute/
│       └── view_documentation.md # Documentation access workflow
├── scripts/
│   ├── config.py                 # Configuration management
│   ├── postman_client.py         # API client with CRUD + Spec Hub operations (now uses curl)
│   ├── validate_setup.py         # 🆕 Comprehensive setup validation & diagnostics
│   ├── list_collections.py       # Collection discovery script (enhanced with context)
│   ├── list_workspaces.py        # 🆕 Workspace discovery and navigation
│   ├── manage_collections.py     # Collection management CLI
│   ├── manage_environments.py    # Environment management CLI
│   ├── manage_pet_store_spec.py  # 🆕 Spec Hub example script (NEW!)
│   ├── manage_pet_store_api.py   # Legacy API example (deprecated)
│   ├── run_collection.py         # Newman test execution wrapper
│   └── manage_monitors.py        # Monitor management CLI
├── utils/
│   ├── retry_handler.py          # Retry logic with backoff
│   ├── formatters.py             # Output formatting (collections, monitors, runs)
│   └── exceptions.py             # 🆕 Custom exception classes with helpful messages
├── tests/
│   ├── test_phase1_manual.py     # 🆕 Phase 1 test suite
│   └── README.md                 # 🆕 Testing guide
└── docs/
    ├── assessment-report.md      # 🆕 Current state analysis
    ├── api-compatibility-matrix.md # 🆕 API endpoint coverage
    ├── gap-analysis.md           # 🆕 Implementation roadmap
    └── compatibility-strategy.md # 🆕 v10+ compatibility approach

使用例

基本操作

すべてのコレクションを一覧表示:

python /skills/postman-skill/scripts/list_collections.py

新しいコレクションを作成:

python /skills/postman-skill/scripts/manage_collections.py --create --name "My API Tests"

自動シークレット検出を使用して環境を作成 (v1.1):

from scripts.postman_client import PostmanClient

client = PostmanClient()
env = client.create_environment(
    name="Production",
    values={
        "base_url": "https://api.example.com",
        "api_key": "secret-key-123",      # Auto-detected as secret! 🔐
        "bearer_token": "bearer-xyz-456"  # Auto-detected as secret! 🔐
    }
)

Spec Hub ワークフロー (新機能!)

API 仕様を作成:

import json
from scripts.postman_client import PostmanClient

client = PostmanClient()

# Create OpenAPI 3.0 spec
openapi_spec = {
    "openapi": "3.0.0",
    "info": {"title": "My API", "version": "1.0.0"},
    "paths": {"/users": {"get": {"responses": {"200": {"description": "Success"}}}}}
}

spec = client.create_spec({
    "name": "My API",
    "description": "A sample API",
    "files": [{
        "path": "openapi.json",
        "content": json.dumps(openapi_spec),
        "root": True
    }]
})
print(f"Created spec: {spec['id']}")

仕様からコレクションを生成:

# Automatically create a collection from your spec
result = client.generate_collection_from_spec(
    spec_id,
    collection_name="My API Collection"
)

コレクションから仕様を生成:

# Create a spec from an existing collection
result = client.generate_spec_from_collection(
    collection_id="collection-12345",
    spec_name="Generated API Spec"
)

完全なサンプルを実行:

python scripts/manage_pet_store_spec.py

バージョン管理ワークフロー (v1.1 - v10 以降が必要)

コレクションをフォーク:

# Create a fork for independent development
fork = client.fork_collection(
    collection_uid="12345-abcde",
    label="feature-new-tests"
)
print(f"Forked collection: {fork['uid']}")

プルリクエストを作成:

# Propose merging your changes
pr = client.create_pull_request(
    collection_uid="12345-abcde",      # Parent collection
    source_collection_uid=fork['uid'], # Your fork
    title="Add authentication tests",
    description="This PR adds comprehensive auth test coverage"
)

プルリクエストをマージ:

# Merge approved changes
client.merge_pull_request("12345-abcde", pr['id'])

コレクションを複製:

# Create a standalone copy (not a fork)
backup = client.duplicate_collection(
    collection_uid="12345-abcde",
    name="My Collection Backup"
)

API スキーマを検証:

# See: workflows/design/validate_schema.md
from scripts.postman_client import PostmanClient
client = PostmanClient()
schemas = client.get_api_schema(api_id="<api-id>", version_id="<version-id>")

認証設定を確認:

# See: workflows/secure/check_auth.md
collection = client.get_collection(collection_uid="<collection-id>")
auth_type = collection.get('auth', {}).get('type', 'No auth')

モックサーバーを作成:

# See: workflows/deploy/manage_mocks.md
mock_data = {"name": "API Mock", "collection": "<collection-uid>"}
mock = client.create_mock(mock_data)
print(f"Mock URL: {mock['mockUrl']}")

特定のコレクションを実行:

python /skills/postman-skill/scripts/run_collection.py --collection="My API Tests"

すべてのモニターを一覧表示:

python /skills/postman-skill/scripts/manage_monitors.py --list

モニターの実行履歴を分析:

python /skills/postman-skill/scripts/manage_monitors.py --analyze <monitor-id> --limit 20

エラー処理 (v1.1 で強化)

すべてのスクリプトに含まれるもの:

• カスタム例外クラス: エラータイプごとの具体的な例外
  • AuthenticationError (401) - 無効な API キーとセットアップ手順
  • PermissionError (403) - 権限不足と解決手順
  • ResourceNotFoundError (404) - 存在しないリソースと考えられる原因
  • ValidationError (400) - リクエスト検証の失敗と詳細
  • RateLimitError (429) - レート制限の超過と再試行までの情報
  • ServerError (5xx) - サーバーエラーとステータスページへのリンク
  • NetworkError - 接続の問題とトラブルシューティング手順
  • TimeoutError - リクエストのタイムアウトと設定のガイダンス
• 自動再試行 (指数バックオフ付き、3 回試行)
• 役立つエラーメッセージ (解決のガイダンス付き)
• API バージョンの検出 (互換性の警告付き)
• レート制限の処理 (自動バックオフ付き)

エラーメッセージの例

変更前 (v1.0):

Exception: API request failed with status 404: Resource not found

変更後 (v1.1):

ResourceNotFoundError: Collection with ID '12345' was not found.

Possible reasons:
- The resource was deleted
- The ID is incorrect
- You don't have permission to access it
- The resource is in a different workspace

セキュリティ (v1.1 で強化)

• API キーは環境変数からのみ読み取られます
• すべての操作は設定されたワークスペースに限定されます
• レート制限と自動バックオフ
• 機密データはログに記録されず、キャッシュされません
• 🆕 環境変数の自動シークレット検出
• 🆕 更新および複製を通じたシークレットタイプの保持
• 🆕 11 個の機密キーワードを監視 (api_key、token、password、bearer、auth など)
• 🆕 デフォルトタイプの変数における認証情報の偶発的な露出を防止

制限事項

• コード実行コンテナ内で実行されます (API 呼び出しにネットワークアクセスの制限は適用されません)
• スキルサイズは最大 8MB
• プリインストールされた Python パッケージのみを使用します
• コレクションのフォークとプルリクエストには Postman v10 以降の API が必要です
• 一部のエンタープライズ機能には有料の Postman プランが必要な場合があります

API バージョン互換性

このスキルは Postman v10 以降の API に最適化されていますが、グレースフルデグラデーションを維持します:

機能	v9 API	v10 以降の API
コレクションの CRUD	✅ ベストエフォート	✅ 完全サポート
コレクションのフォーク	❌ 利用不可	✅ 完全サポート
プルリクエスト	❌ 利用不可	✅ 完全サポート
環境の CRUD	✅ ベストエフォート	✅ 完全サポート
シークレット変数	⚠️ 制限あり	✅ 完全サポート
カスタム例外	✅ 完全サポート	✅ 完全サポート
バージョン検出	✅ 完全サポート	✅ 完全サポート

クライアントは API バージョンを自動的に検出し、v10 以降の機能が利用できない場合は警告を表示します。

次のステップ

このスキルを読み込んだ後（Claude への指示）:

1. 必ず最初にセットアップ検証を実行してください: python scripts/validate_setup.py
   • これにより、即座に診断情報とワークスペースのコンテキストが提供されます
   • 設定の問題を事前に特定できます
   • コレクションの件数と役立つ次のステップが表示されます
2. 検証が失敗した場合:
   • .env ファイルに POSTMAN_API_KEY が設定されているかを確認してください
   • https://web.postman.co/settings/me/api-keys からキーを取得するようユーザーに案内してください
3. 「コレクションはいくつありますか？」という問い合わせの場合:
   • python scripts/list_collections.py を実行してください
   • コレクションが 0 件の場合、以下を提案してください:
     • ワークスペースの一覧表示: python scripts/list_workspaces.py
     • 新しいコレクションの作成
     • .env ファイルでワークスペースを切り替える
4. ユーザーのリクエストに応じて特定のワークフローを実行してください

役立つ診断コマンド:

• セットアップ検証: python scripts/validate_setup.py
• コレクションの一覧表示: python scripts/list_collections.py
• ワークスペースの一覧表示: python scripts/list_workspaces.py
• すべてのリソースの一覧表示: python scripts/list_collections.py --all

関連リソース

• Postman API ドキュメント
• ワークフローファイル
• レスポンスの例