Postman-Devrel · quintonwall · Jun 9, 2026 · Jun 9, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "postman",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Full API lifecycle management for Claude Code. Sync collections, generate client code, discover APIs, run tests, create mocks, publish docs, and audit security. Powered by the Postman MCP Server.",
   "author": {
     "name": "Postman",

diff --git a/.github/scripts/validate-frontmatter.py b/.github/scripts/validate-frontmatter.py
@@ -9,7 +9,13 @@
 # PyYAML is not guaranteed on all runners, so parse simple YAML manually
 FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
 
-KNOWN_TOOLS = {"Bash", "Read", "Write", "Glob", "Grep", "mcp__postman__*"}
+KNOWN_TOOLS = {"Bash", "Read", "Write", "Edit", "Glob", "Grep"}
+# Specific Postman MCP tools are preferred over the mcp__postman__* wildcard
+MCP_TOOL_RE = re.compile(r"^mcp__postman__[A-Za-z0-9_]+$")
+
+
+def is_known_tool(tool: str) -> bool:
+    return tool in KNOWN_TOOLS or MCP_TOOL_RE.match(tool) is not None
 
 
 def parse_frontmatter(text: str) -> Optional[dict]:
@@ -46,7 +52,7 @@ def validate_commands(root: Path) -> list[str]:
         if "allowed-tools" in fm and fm["allowed-tools"]:
             tools = [t.strip() for t in fm["allowed-tools"].split(",")]
             for tool in tools:
-                if tool not in KNOWN_TOOLS:
+                if not is_known_tool(tool):
                     errors.append(f"{f.name}: Unknown tool '{tool}' in allowed-tools")
 
     return errors
@@ -98,7 +104,7 @@ def validate_agents(root: Path) -> list[str]:
         if "allowed-tools" in fm and fm["allowed-tools"]:
             tools = [t.strip() for t in fm["allowed-tools"].split(",")]
             for tool in tools:
-                if tool not in KNOWN_TOOLS:
+                if not is_known_tool(tool):
                     errors.append(f"agents/{f.name}: Unknown tool '{tool}' in allowed-tools")
 
     return errors

diff --git a/.github/scripts/validate-structure.py b/.github/scripts/validate-structure.py
@@ -73,7 +73,7 @@ def main():
         errors.append("agents/: Directory not found")
 
     # 6. Check for stray markdown files in root (not README, CLAUDE, LICENSE, or examples)
-    expected_root_md = {"README.md", "CLAUDE.md", "LICENSE"}
+    expected_root_md = {"README.md", "CLAUDE.md", "LICENSE", "token-optimization-findings.md"}
     for f in sorted(root.glob("*.md")):
         if f.name not in expected_root_md:
             errors.append(f"{f.name}: Unexpected markdown file in repo root")

diff --git a/.mcp.json b/.mcp.json
@@ -2,11 +2,11 @@
   "mcpServers": {
     "postman": {
       "type": "http",
-      "url": "https://mcp.postman.com/mcp",
+      "url": "https://mcp.postman.com/${POSTMAN_MCP_MODE:-mcp}",
       "headers": {
         "X-Source": "claude-code-plugin",
-        "X-Plugin-Version": "1.1.0",
-        "User-Agent": "postman-claude-code-plugin/1.1.0"
+        "X-Plugin-Version": "1.2.0",
+        "User-Agent": "postman-claude-code-plugin/1.2.0"
       }
     }
   }

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -11,18 +11,19 @@ The Postman Plugin for Claude Code — a pure-markdown, configuration-driven plu
 ```
 .claude-plugin/plugin.json   # Plugin manifest (name, version, metadata)
 .mcp.json                    # MCP server auto-config (Postman MCP at mcp.postman.com)
-commands/*.md                # 11 slash commands (/postman:<name>)
-skills/*/SKILL.md            # 8 skills (routing, knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context)
+commands/*.md                # 10 slash commands (/postman:<name>)
+skills/*/SKILL.md            # 7 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context)
+skills/*/references/*.md     # On-demand reference files loaded by skills only when needed
 agents/readiness-analyzer.md # Sub-agent for API readiness analysis
 examples/                    # Sample output (readiness report)
-assets/                      # GIFs for README
 ```
 
 ## How the Plugin Works
 
 - Claude Code discovers components via `.claude-plugin/plugin.json` manifest
-- `.mcp.json` auto-configures the Postman MCP server, providing `mcp__postman__*` tools (111 tools)
-- MCP commands use the cloud Postman MCP Server — requires `POSTMAN_API_KEY` environment variable
+- `.mcp.json` auto-configures the Postman MCP server, providing `mcp__postman__*` tools. The server mode is switchable via `POSTMAN_MCP_MODE` (`mcp` full/default, `minimal`, or `code` — the latter two expose fewer tools; `minimal` lacks the `*Context` code-gen tools)
+- MCP commands use the cloud Postman MCP Server — authenticate via OAuth in `/postman:setup` or a `POSTMAN_API_KEY` environment variable
+- Routing is native: there is no routing skill. Claude matches user intent to commands/skills from their front-matter `description` fields, so descriptions must state when to use the component
 - CLI commands use the locally installed Postman CLI (`npm install -g postman-cli`) — requires `postman login`
 - Plugin is loaded with `claude --plugin-dir /path/to/postman-claude-code-plugin`
 
@@ -32,7 +33,9 @@ assets/                      # GIFs for README
 - MCP commands: setup, sync, search, test, mock, docs, security
 - CLI commands: request, generate-spec, run-collection
 
-**Skills** (`skills/*/SKILL.md`): YAML front matter with `name`, `description`, `user-invocable`. Auto-injected context, not directly invoked. `postman-routing` routes requests to commands; `postman-knowledge` provides MCP tool guidance; `agent-ready-apis` provides readiness criteria; `postman-cli` provides CLI and git sync file structure knowledge; `postman-context` provides API discovery, exploration, and code generation from real API definitions via `postman context` CLI commands.
+**Skills** (`skills/*/SKILL.md`): YAML front matter with `name`, `description`, `user-invocable`. Auto-injected context, not directly invoked. `postman-knowledge` provides MCP tool guidance; `agent-ready-apis` provides readiness criteria; `postman-cli` provides CLI and git sync file structure knowledge; `postman-context` provides API discovery, exploration, and code generation from real API definitions.
+
+Large skills use progressive disclosure: a lean SKILL.md holds the workflow, and detailed rules live in `references/*.md` files inside the skill directory that the skill instructs Claude to Read only at the step that needs them (see `postman-context` and `generate-spec`). Keep new skills under ~6KB and put bulky templates/rules in references.
 
 **Agent** (`agents/readiness-analyzer.md`): YAML front matter with `name`, `description`, `model`, `allowed-tools`. Runs as a sub-agent (sonnet model) for deep API readiness analysis (8 pillars, 48 checks).
 
@@ -64,4 +67,5 @@ CLI commands work with Postman's git sync structure: `postman/collections/` (v3
 - When adding a new command, follow the existing front matter pattern in `commands/`
 - When adding a new skill, create `skills/<name>/SKILL.md` with proper front matter
 - The `allowed-tools` field in front matter controls what tools a command/agent can use
-- CLI commands need `Bash` in `allowed-tools`; MCP commands need `mcp__postman__*`
+- CLI commands need `Bash` in `allowed-tools`; MCP commands list the specific `mcp__postman__<toolName>` tools they call — never the `mcp__postman__*` wildcard. When a command's workflow gains a new MCP call, add that tool to its `allowed-tools`
+- Front-matter `description` fields are injected into every user session — keep them to one or two sentences (what it does + when to use it)
diff --git a/README.md b/README.md
@@ -6,13 +6,9 @@
 
 The Postman Plugin provides a single, simple install for Claude Code. It provides full API lifecycle management, and best practices when working with Postman APIs. 
 
-<p align="center">
-  <img src="assets/postman-plugin-sync.gif" alt="Postman plugin syncing code -> collection" width="800">
-</p>
-
 ## What's included:
 - Commands for setting up the Postman MCP Server (no more manual installs!), working with Collections, Tests, Mock Servers, and generating code and documentation from Collections
-- Skills for Postman Routing, API best practices, and API OWASP security reviews
+- Skills for API discovery and client code generation, OpenAPI spec generation, Postman CLI workflows, and API best practices
 - Agent for reviewing API production readiness and providing recommendations based on the <a href="https://www.postman.com/ai/90-day-ai-readiness-playbook/">Postman API Readiness Guide</a>.
 
 ## Installation
@@ -32,32 +28,26 @@ claude --plugin-dir /path/to/postman-claude-code-plugin
 
 ## Quick Start
 
-1. Set your API key:
-```bash
-export POSTMAN_API_KEY=PMAK-your-key-here
-```
-Add it to your shell profile (`~/.zshrc` or `~/.bashrc`) to persist across sessions.
-
-2. Start Claude Code with the plugin:
+1. Start Claude Code with the plugin:
 ```bash
 claude --plugin-dir /path/to/postman-claude-code-plugin
 ```
 
-3. Run setup:
+2. Run setup:
 ```
 /postman:setup
 ```
 
-That's it. The plugin auto-configures the Postman MCP Server, verifies your connection, and lists your workspaces. You're ready to go.
+3. Authenticate when prompted — **OAuth (recommended)**, which opens a browser sign-in with no key copying, or an API key:
+```bash
+export POSTMAN_API_KEY=PMAK-your-key-here
+```
+If you use an API key, add it to your shell profile (`~/.zshrc` or `~/.bashrc`) to persist across sessions. Get one at [go.postman.co/settings/me/api-keys](https://go.postman.co/settings/me/api-keys).
 
-Get your API key at [go.postman.co/settings/me/api-keys](https://go.postman.co/settings/me/api-keys).
+That's it. The plugin auto-configures the Postman MCP Server, verifies your connection, and lists your workspaces. You're ready to go.
 
 ## Commands
 
-<p align="center">
-  <img src="assets/postman-plugin-codegen.gif" alt="Postman Plugin generating code from a collection" width="800">
-</p>
-
 | Command | What It Does |
 |---------|-------------|
 | `/postman:setup` | Configure API key, verify connection, select workspace |
@@ -71,10 +61,6 @@ Get your API key at [go.postman.co/settings/me/api-keys](https://go.postman.co/s
 
 ## What You Can Do
 
-<p align="center">
-  <img src="assets/postman-plugin-mock-server.gif" alt="Postman Plugin creating a mock server to be used in code to mock an API" width="800">
-</p>
-
 ### Sync your API to Postman
 ```
 "Sync my OpenAPI spec with Postman"
@@ -117,20 +103,16 @@ Get your API key at [go.postman.co/settings/me/api-keys](https://go.postman.co/s
 → 48 checks across 8 pillars, scored 0-100, prioritized fix recommendations
 ```
 
-## Auto-Routing
+## Natural Language Routing
 
-You don't need to remember command names. The plugin's routing skill detects your intent and runs the right command:
+You don't need to remember command names. Claude matches your intent to the right command or skill natively:
 
-- "Sync my collection" routes to `/postman:sync`
-- "Check for vulnerabilities" routes to `/postman:security`
+- "Sync my collection" runs `/postman:sync`
+- "Check for vulnerabilities" runs `/postman:security`
 - "Is my API agent-ready?" triggers the readiness analyzer
 
 ## API Readiness Analyzer
 
-<p align="center">
-  <img src="assets/postman-plugin-api-ai-check.gif" alt="Postman Plugin analyzing your API for AI Readiness" width="800">
-</p>
-
 The built-in readiness analyzer evaluates APIs for AI agent compatibility across 8 pillars:
 
 | Pillar | What It Checks |
@@ -149,12 +131,19 @@ The built-in readiness analyzer evaluates APIs for AI agent compatibility across
 ## Requirements
 
 - Claude Code v1.0.33+
-- Postman API key (`POSTMAN_API_KEY` environment variable)
+- A Postman account — authenticate via OAuth during `/postman:setup`, or set a `POSTMAN_API_KEY` environment variable
 - No Python, Node, or other runtime dependencies
 
 ## How It Works
 
-The plugin bundles a `.mcp.json` file that auto-configures the [Postman MCP Server](https://github.com/postmanlabs/postman-mcp-server) when installed. All commands communicate with Postman through 111 MCP tools. No scripts, no dependencies, pure MCP.
+The plugin bundles a `.mcp.json` file that auto-configures the [Postman MCP Server](https://github.com/postmanlabs/postman-mcp-server) when installed. All commands communicate with Postman through MCP tools. No scripts, no dependencies, pure MCP.
+
+By default the plugin connects to the full Postman MCP Server (100+ tools). Recent Claude Code versions load MCP tool schemas on demand, so the full server adds little context overhead. If you're on an older client or want a lighter session, set `POSTMAN_MCP_MODE` before starting Claude Code to pick a smaller server mode:
+
+```bash
+export POSTMAN_MCP_MODE=minimal   # ~42 CRUD tools; code-generation (context) tools unavailable
+export POSTMAN_MCP_MODE=code      # ~24 read-only tools for API discovery and client code generation
+```
 
 ## License
 

diff --git a/agents/readiness-analyzer.md b/agents/readiness-analyzer.md
@@ -1,8 +1,8 @@
 ---
 name: API Readiness Analyzer
-description: "Analyze any API for AI agent compatibility. Scans OpenAPI specs across 8 pillars (48 checks), scores agent-readiness, and provides fix recommendations. Triggers on: 'Is my API agent-ready?', 'Scan my API', 'Analyze my OpenAPI spec', 'What\\'s wrong with my API for AI agents?', 'How agent-friendly is my API?'."
+description: Analyze any API or OpenAPI spec for AI agent compatibility — 48 checks across 8 pillars, with scoring and fix recommendations. Use when the user asks whether an API is agent-ready or wants it scanned, scored, or improved for AI agents.
 model: sonnet
-allowed-tools: Read, Glob, Grep, Bash, mcp__postman__*
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__createSpec, mcp__postman__generateCollection, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__createEnvironment, mcp__postman__createMock, mcp__postman__runCollection, mcp__postman__publishDocumentation
 ---
 
 # API Readiness Analyzer

diff --git a/assets/postman-plugin-api-ai-check.gif b/assets/postman-plugin-api-ai-check.gif
diff --git a/assets/postman-plugin-codegen.gif b/assets/postman-plugin-codegen.gif
diff --git a/assets/postman-plugin-mock-server.gif b/assets/postman-plugin-mock-server.gif
diff --git a/assets/postman-plugin-sync.gif b/assets/postman-plugin-sync.gif
diff --git a/commands/docs.md b/commands/docs.md
@@ -1,6 +1,6 @@
 ---
 description: Generate, improve, and publish API documentation from Postman collections.
-allowed-tools: Read, Glob, Grep, mcp__postman__*
+allowed-tools: Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__updateCollectionRequest, mcp__postman__publishDocumentation, mcp__postman__unpublishDocumentation, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks
 ---
 
 # API Documentation
@@ -76,7 +76,7 @@ Ask the user which output they want:
 ### Step 5: Sync Spec and Collection
 
 If both a spec and collection exist, keep them in sync:
-- Call `syncCollectionWithSpec` to update collection from spec. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion. Only supports OpenAPI 3.0.
+- Call `syncCollectionWithSpec` to update collection from spec. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion with increasing waits between polls. Only supports OpenAPI 3.0.
 - Or call `syncSpecWithCollection` to update spec from collection changes.
 
 ## Error Handling

diff --git a/commands/mock.md b/commands/mock.md
@@ -1,6 +1,6 @@
 ---
 description: Create Postman mock servers for frontend development. Generates missing examples, provides integration config.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__*
+allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__createCollectionResponse, mcp__postman__createSpec, mcp__postman__generateCollection, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__getSpecCollections, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getMocks, mcp__postman__getMock, mcp__postman__createMock, mcp__postman__publishMock, mcp__postman__unpublishMock
 ---
 
 # Create Mock Servers
@@ -25,7 +25,7 @@ Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exis
 - Find OpenAPI spec in the project
 - Import it first:
   1. Call `createSpec` with `workspaceId`, `name`, `type`, and `files`
-  2. Call `generateCollection`. **Async (HTTP 202).** Poll `getGeneratedCollectionSpecs` or `getSpecCollections` for completion. Note: `getAsyncSpecTaskStatus` may return 403 on some plans.
+  2. Call `generateCollection`. **Async (HTTP 202).** Poll `getGeneratedCollectionSpecs` or `getSpecCollections` for completion, with increasing waits between polls (2s, 4s, 8s). Note: `getAsyncSpecTaskStatus` may return 403 on some plans.
 
 ### Step 2: Check for Examples
 

diff --git a/commands/search.md b/commands/search.md
@@ -1,6 +1,6 @@
 ---
 description: Discover APIs across your Postman workspaces. Ask natural language questions about available endpoints and capabilities.
-allowed-tools: Read, Glob, Grep, mcp__postman__*
+allowed-tools: Read, Glob, Grep, mcp__postman__searchPostmanElementsInPrivateNetwork, mcp__postman__searchPostmanElementsInPublicNetwork, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getTaggedEntities, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__getSpecDefinition
 ---
 
 # Discover APIs

diff --git a/commands/security.md b/commands/security.md
@@ -1,6 +1,6 @@
 ---
 description: Security audit your APIs against OWASP API Top 10. Finds vulnerabilities and provides remediation guidance.
-allowed-tools: Read, Glob, Grep, mcp__postman__*
+allowed-tools: Read, Edit, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getEnvironment, mcp__postman__putEnvironment, mcp__postman__updateCollectionRequest, mcp__postman__updateCollectionResponse
 ---
 
 # API Security Audit

diff --git a/commands/setup.md b/commands/setup.md
@@ -1,6 +1,6 @@
 ---
 description: Set up Postman MCP Server. Authenticate via OAuth or API key, verify connection, select workspace.
-allowed-tools: mcp__postman__*
+allowed-tools: mcp__postman__authenticate, mcp__postman__complete_authentication, mcp__postman__getAuthenticatedUser, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getAllSpecs
 ---
 
 # First-Run Configuration

diff --git a/commands/sync.md b/commands/sync.md
@@ -1,6 +1,6 @@
 ---
 description: Sync Postman collections with your API code. Create collections from specs, push updates, keep everything in sync.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__*
+allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__createSpec, mcp__postman__updateSpecFile, mcp__postman__generateCollection, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks, mcp__postman__createEnvironment, mcp__postman__createCollectionRequest, mcp__postman__updateCollectionRequest, mcp__postman__createCollectionFolder, mcp__postman__createCollectionResponse
 ---
 
 # Sync Collections
@@ -38,7 +38,7 @@ Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exis
    - `name`: from the spec's `info.title`
    - `type`: one of `OPENAPI:2.0`, `OPENAPI:3.0`, `OPENAPI:3.1`, `ASYNCAPI:2.0`
    - `files`: array of `{path, content}` objects
-3. Call `generateCollection` from the spec. **This is async (HTTP 202).** Poll `getAsyncSpecTaskStatus` or `getGeneratedCollectionSpecs` until complete.
+3. Call `generateCollection` from the spec. **This is async (HTTP 202).** Poll `getAsyncSpecTaskStatus` or `getGeneratedCollectionSpecs` until complete, with increasing waits between polls (2s, 4s, 8s). Don't narrate intermediate poll results — report only the final outcome.
 4. Call `createEnvironment` with variables extracted from the spec:
    - `base_url` from `servers[0].url`
    - Auth variables from `securitySchemes` (mark as `secret`)
@@ -48,7 +48,7 @@ Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exis
 
 **Spec to Collection (most common):**
 1. Call `createSpec` or `updateSpecFile` with local spec content
-2. Call `syncCollectionWithSpec` to update the collection. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion.
+2. Call `syncCollectionWithSpec` to update the collection. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion with increasing waits between polls.
 3. **Note:** `syncCollectionWithSpec` only supports OpenAPI 3.0. For Swagger 2.0 or OpenAPI 3.1, use `updateSpecFile` and regenerate the collection.
 4. Report what changed