SKILL.md
Postman
Full API lifecycle management through the Postman MCP Server (111+ tools for workspaces, collections, specs, environments, mocks, and monitors). Sync specs, generate code, run tests, create mocks, publish docs, and audit security.
Prerequisites
Setup check: Call getAuthenticatedUser via MCP. If it succeeds, you're connected. If it fails, walk through Setup below.
Setup
If MCP tools are not available or getAuthenticatedUser fails:
- Get a Postman API key at https://postman.postman.co/settings/me/api-keys — "Generate API Key", name it "Claude Code", copy the key (starts with
PMAK-). - Set the environment variable —
export POSTMANAPIKEY=PMAK-your-key-here(add to~/.zshrcor~/.bashrcto persist). - Verify: call
getAuthenticatedUser, then list workspaces and collection counts so the user sees they're connected.
Routing
Match the user's intent to a workflow, then read that workflow's reference file and follow it. Each file is loaded on demand — read one only when the task needs that depth (progressive disclosure).
| User intent | Workflow reference |
|---|---|
| Import a spec, push spec to Postman, create collection from spec, sync changes | references/sync-collections.md |
| Generate client code, SDK, wrapper, typed client, consume an API | references/generate-client-code.md |
| Find API, search endpoints, what's available, discover APIs | references/discover-apis.md |
| Run tests, check if tests pass, validate API, test collection | references/run-collection-tests.md |
| Create mock server, fake API, mock for frontend, mock URL | references/create-mock-servers.md |
| Generate docs, improve documentation, publish docs, API docs | references/api-documentation.md |
| Security audit, vulnerabilities, OWASP, security check | references/security-audit.md |
Routing rules:
- Specific workflows take priority. If intent clearly maps to one, use it.
- Ambiguous requests: ask the user what they need.
- Multi-step requests chain workflows. "Import my spec and run tests" = Sync then Test.
- Only use
mcppostman*tools directly for single targeted updates or when the user explicitly asks.
References
references/mcp-limitations.md— known MCP behaviors and workarounds (300KB+ payloads fromgetWorkspaces/getCollection model=full, async HTTP 202 polling, plan-gated tag tools, aggregate-onlyrunCollection, public-onlysearchPostmanElements) · read before composing any tool calls a workflow doesn't already cover.references/mcp-tools.md— the complete tool catalog by category · read when picking the right tool outside a workflow.
Error Handling
These patterns apply across all workflows:
| Error | Response |
|---|---|
| MCP tools not available | "The Postman MCP Server isn't configured. Set your POSTMANAPIKEY environment variable and restart your editor." |
| 401 Unauthorized | "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys"; |
| Network timeout | Retry once. Check https://status.postman.com for outages. |
| Async operation stuck | If polling shows no progress after 30 seconds, inform user and suggest checking Postman app directly. |
| Collection not found | "No collection matching that name. Try discovering APIs across your workspace." |
| Empty collection | "This collection has no requests. Add endpoints in Postman or sync from a local spec." |
| Invalid spec | Report specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues. |
| Plan limitations | "Some features may require a paid Postman plan. Core operations work on all plans." |