feat: add auto-loaded skills for routing, knowledge, and readiness

Three skills that load automatically to enhance Claude's behavior:
- postman-routing: intent-to-command routing table
- postman-knowledge: Postman concepts, tool selection, MCP limitations
- agent-ready-apis: agent-readiness concepts, scoring, 8 pillars reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

skills/agent-ready-apis/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: agent-ready-apis
+description: Knowledge about AI agent API compatibility. Use when user asks about API readiness, agent compatibility, or wants to improve their API for AI consumption.
+user-invocable: false
+---
+
+# Agent-Ready APIs
+
+An "agent-ready" API is one that an AI agent can discover, understand, call correctly, and recover from errors without human intervention. Most APIs aren't there yet.
+
+## When to Suggest the Analyzer
+
+If the user mentions any of these, suggest running the readiness-analyzer agent:
+- "Is my API agent-ready?"
+- "Can AI agents use my API?"
+- "Scan my API" / "Analyze my spec"
+- "What's wrong with my API for AI?"
+- "How agent-friendly is my API?"
+- "Improve my API for AI agents"
+
+## What Gets Evaluated
+
+The analyzer checks 48 items across 8 pillars:
+
+| Pillar | What It Measures |
+|--------|-----------------|
+| Metadata | operationIds, summaries, descriptions, tags |
+| Errors | Error schemas, codes, messages, retry guidance |
+| Introspection | Parameter types, required fields, enums, examples |
+| Naming | Consistent casing, RESTful paths, HTTP semantics |
+| Predictability | Response schemas, pagination, date formats |
+| Documentation | Auth docs, rate limits, external links |
+| Performance | Rate limit headers, cache, bulk endpoints, async patterns |
+| Discoverability | OpenAPI version, server URLs, contact info |
+
+## Scoring
+
+- **Critical checks (4x weight):** Blocks agent usage entirely
+- **High checks (2x weight):** Causes frequent agent failures
+- **Medium checks (1x weight):** Degrades agent performance
+- **Low checks (0.5x weight):** Nice-to-have improvements
+
+**Agent Ready = score of 70% or higher with zero critical failures.**
+
+## Interpreting Results
+
+- **90-100%:** Excellent. Agents can use this API reliably.
+- **70-89%:** Agent-ready. Minor improvements possible.
+- **50-69%:** Not agent-ready. Key issues need fixing.
+- **Below 50%:** Significant work needed. Focus on critical failures first.
+
+See `pillars.md` in this skill folder for the full check reference.

skills/agent-ready-apis/pillars.md

@@ -0,0 +1,116 @@
+# The 8 Pillars of Agent Readiness
+
+## Metadata (META)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| META_001 | Every operation has an `operationId` | Critical |
+| META_002 | Every operation has a `summary` | High |
+| META_003 | Every operation has a `description` | Medium |
+| META_004 | All parameters have descriptions | Medium |
+| META_005 | Operations are grouped with tags | Medium |
+| META_006 | Tags have descriptions | Low |
+
+**Why agents care:** Agents need to discover and select the right endpoint from a list. Without operationIds, agents can't reliably reference endpoints. Without summaries and descriptions, agents can't determine which endpoint matches their goal.
+
+## Errors (ERR)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| ERR_001 | 4xx error responses defined for each endpoint | Critical |
+| ERR_002 | Error schemas include machine-readable identifier and human-readable message | Critical |
+| ERR_003 | 5xx error responses defined | High |
+| ERR_004 | 429 Too Many Requests response defined | High |
+| ERR_005 | Error examples provided | Medium |
+| ERR_006 | Retry-After header documented for 429/503 | Medium |
+
+**Why agents care:** Agents need to self-heal when things go wrong. Without structured error schemas, an agent hitting a 400 has no idea how to parse the error or recover. Without 429 documentation, agents hammer APIs until blocked.
+
+## Introspection (INTRO)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| INTRO_001 | All parameters have `type` defined | Critical |
+| INTRO_002 | Required fields are marked | Critical |
+| INTRO_003 | Enum values used for constrained fields | High |
+| INTRO_004 | String parameters have `format` where applicable | Medium |
+| INTRO_005 | Request body examples provided | High |
+| INTRO_006 | Response body examples provided | Medium |
+
+**Why agents care:** Agents need to construct valid requests without guessing. Missing types force agents to guess formats. Missing required field markers lead to validation errors. Missing examples mean agents build request bodies from scratch with no reference.
+
+## Naming (NAME)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| NAME_001 | Consistent casing in paths (kebab-case preferred) | High |
+| NAME_002 | RESTful path patterns (nouns, not verbs) | High |
+| NAME_003 | Correct HTTP method semantics | Medium |
+| NAME_004 | Consistent pluralization in resource names | Medium |
+| NAME_005 | Consistent property naming convention | Medium |
+| NAME_006 | No abbreviations in public-facing names | Low |
+
+**Why agents care:** Agents need predictable patterns to reason about. Inconsistent naming means agents can't predict URL patterns, leading to wrong endpoint calls. Verb-based paths break REST mental models that agents rely on.
+
+## Predictability (PRED)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| PRED_001 | All responses have schemas defined | Critical |
+| PRED_002 | Consistent response envelope pattern | High |
+| PRED_003 | Pagination documented for list endpoints | High |
+| PRED_004 | Consistent date/time format (ISO 8601) | Medium |
+| PRED_005 | Consistent ID format across resources | Medium |
+| PRED_006 | Nullable fields explicitly marked | Medium |
+
+**Why agents care:** Agents need to parse responses reliably. Missing schemas mean agents can't validate what they receive. No pagination documentation means agents try to load entire datasets in one call. Inconsistent date formats cause parsing failures.
+
+## Documentation (DOC)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| DOC_001 | Authentication documented in security schemes | Critical |
+| DOC_002 | Auth requirements per endpoint | High |
+| DOC_003 | Rate limits documented | High |
+| DOC_004 | API description provides overview | Medium |
+| DOC_005 | External documentation links provided | Low |
+| DOC_006 | Terms of service and contact info | Low |
+
+**Why agents care:** Agents need context that humans get from reading docs. Without auth documentation, agents can't authenticate. Without rate limit documentation, agents have no awareness of usage constraints.
+
+## Performance (PERF)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| PERF_001 | Rate limit headers documented (X-RateLimit-*) | High |
+| PERF_002 | Cache headers documented (ETag, Cache-Control) | Medium |
+| PERF_003 | Compression support noted | Medium |
+| PERF_004 | Bulk/batch endpoints for high-volume operations | Low |
+| PERF_005 | Partial response support (fields parameter) | Low |
+| PERF_006 | Webhook/async patterns for long-running operations | Low |
+
+**Why agents care:** Agents need to operate within constraints. Without rate limit headers in responses, agents can't self-throttle. Without cache headers, agents re-fetch data unnecessarily. Without bulk endpoints, agents make hundreds of individual calls.
+
+## Discoverability (DISC)
+
+| Check | Description | Severity |
+|-------|-------------|----------|
+| DISC_001 | OpenAPI 3.0+ used | High |
+| DISC_002 | Server URLs defined | Critical |
+| DISC_003 | Multiple environments documented (staging, prod) | Medium |
+| DISC_004 | API version in URL or header | Medium |
+| DISC_005 | CORS documented | Low |
+| DISC_006 | Health check endpoint exists | Low |
+
+**Why agents care:** Agents need to find and connect to the API. Missing server URLs mean agents have no idea where to send requests. Older spec formats (Swagger 2.0) have less machine-readable information for agents to work with.
+
+## Scoring Formula
+
+For each check:
+- If N/A (e.g., no list endpoints for pagination check): exclude from scoring
+- If applicable: `weight * (passing_items / total_items)`
+
+Pillar score: `sum(weighted_scores) / sum(applicable_weights) * 100`
+Overall score: `sum(all_weighted_scores) / sum(all_applicable_weights) * 100`
+
+Severity weights: Critical = 4, High = 2, Medium = 1, Low = 0.5

skills/postman-knowledge/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: postman-knowledge
+description: Postman concepts and MCP tool guidance. Loaded when working with Postman MCP tools to make better decisions about tool selection and workarounds.
+user-invocable: false
+---
+
+# Postman Knowledge
+
+Reference for Postman concepts and MCP tool selection. Use this context when working with Postman MCP tools to make better decisions.
+
+## Core Concepts
+
+- **Collection:** A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples, tests, and documentation.
+- **Environment:** Key-value pairs (variables) scoped to a context (dev, staging, prod). Used to swap base URLs, auth tokens, and config without changing requests.
+- **Workspace:** Container for collections, environments, and specs. Can be personal, team, or public.
+- **Spec (Spec Hub):** An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections and stay synced.
+- **Request:** A single API call definition (method, URL, headers, body, tests).
+- **Response:** A saved example response for a request. Used by mock servers and documentation.
+- **Folder:** A grouping within a collection, typically by resource (e.g., "Users", "Orders").
+- **Tags:** Labels on collections for categorization and search.
+- **Monitor:** A scheduled collection runner that checks API health.
+- **Mock Server:** A fake API that serves example responses from a collection.
+
+## Decision Guide
+
+| Goal | Approach |
+|------|----------|
+| Push code changes to Postman | Create/update spec in Spec Hub, then sync to collection |
+| Consume a Postman API | Read collection + generate client code |
+| Find an API | Search workspace collections, then drill into details |
+| Test an API | Run collection with `runCollection` |
+| Create a fake API for frontend | Create mock server from collection with examples |
+| Document an API | Analyze collection completeness, fill gaps, optionally publish |
+| Audit API security | Run security checks against spec or collection |
+
+## MCP Tool Selection
+
+**Workspace operations:** `getWorkspaces`, `getWorkspace`, `createWorkspace`
+**Collection CRUD:** `getCollections`, `getCollection`, `createCollection`, `putCollection`, `patchCollection`, `deleteCollection`
+**Request/Response:** `getCollectionRequest`, `createCollectionRequest`, `updateCollectionRequest`, `getCollectionResponse`, `createCollectionResponse`, `updateCollectionResponse`
+**Folder management:** `getCollectionFolder`, `createCollectionFolder`, `updateCollectionFolder`
+**Spec Hub:** `getAllSpecs`, `getSpec`, `createSpec`, `getSpecDefinition`, `updateSpecFile`, `getSpecFiles`
+**Sync:** `generateCollection`, `syncCollectionWithSpec`, `syncSpecWithCollection`
+**Environments:** `getEnvironments`, `getEnvironment`, `createEnvironment`, `putEnvironment`
+**Mocks:** `getMocks`, `getMock`, `createMock`, `publishMock`, `unpublishMock`
+**Tests:** `runCollection`
+**Docs:** `publishDocumentation`, `unpublishDocumentation`
+**Search:** `searchPostmanElements` (public network only), `getTaggedEntities`
+**User:** `getAuthenticatedUser`
+
+See `mcp-limitations.md` in this skill folder for known limitations and workarounds.

skills/postman-knowledge/mcp-limitations.md

@@ -0,0 +1,44 @@
+# Known MCP Limitations
+
+These limitations are documented so they are handled correctly in all commands and workflows.
+
+## searchPostmanElements is Public-Only
+
+`searchPostmanElements` searches the PUBLIC Postman network only, not the user's private workspaces.
+
+**Workaround:** For private content, use `getWorkspaces` + `getCollections` + `getCollection`. Use `searchPostmanElements` only as a fallback when searching for public APIs.
+
+## generateCollection is Async
+
+`generateCollection` returns HTTP 202 (accepted), not the collection directly.
+
+**Workaround:** Poll `getGeneratedCollectionSpecs` or `getSpecCollections` for completion. Note: `getAsyncSpecTaskStatus` may return 403 on some plans; use the alternatives.
+
+## syncCollectionWithSpec is Async and OpenAPI 3.0 Only
+
+`syncCollectionWithSpec` returns HTTP 202 and only supports OpenAPI 3.0 specifications.
+
+**Workaround for async:** Poll `getCollectionUpdatesTasks` for completion.
+
+**Workaround for non-3.0 specs:** For Swagger 2.0 or OpenAPI 3.1 specs, use `updateSpecFile` to update the spec and regenerate the collection with `generateCollection`.
+
+## createCollection Cannot Nest Folders
+
+`createCollection` creates a flat collection. You cannot nest folders in a single call.
+
+**Workaround:** Decompose the operation:
+1. `createCollection` to create the collection
+2. `createCollectionFolder` to add folders
+3. `createCollectionRequest` to add requests to folders
+
+## putCollection Auth Enum Lacks "noauth"
+
+The `putCollection` auth type enum does not include "noauth" as a valid value.
+
+**Workaround:** Endpoints that need no auth should inherit from collection-level settings or use a different auth type as a placeholder.
+
+## createSpec Impractical for Large Specs
+
+`createSpec` struggles with specs larger than ~50KB due to request size limits.
+
+**Workaround:** For large APIs, parse the spec locally and create collection items directly using `createCollection` + `createCollectionFolder` + `createCollectionRequest` + `createCollectionResponse`.

skills/postman-routing/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: postman-routing
+description: Automatically routes Postman and API-related requests to the correct command. Use when user mentions APIs, collections, specs, testing, mocks, docs, security, or Postman.
+user-invocable: false
+---
+
+# Postman Command Routing
+
+When the user's request involves Postman or APIs, route to the appropriate command. Always prefer commands over raw MCP tool calls. Commands provide structured workflows, async handling, error diagnosis, and formatted output.
+
+## Routing Table
+
+| User Intent | Command | Why |
+|-------------|---------|-----|
+| Import a spec, push spec to Postman, create collection from spec | `/postman:sync` | Creates spec + collection + environment, handles async polling |
+| Sync collection, update collection, keep in sync, push changes | `/postman:sync` | Full sync workflow with change reporting |
+| Generate client code, SDK, wrapper, consume an API | `/postman:codegen` | Reads collection shape, detects language, writes typed code |
+| Find API, search endpoints, what's available, is there an API for | `/postman:search` | Searches private workspace first, drills into details |
+| Run tests, check if tests pass, validate API | `/postman:test` | Runs collection, parses results, diagnoses failures, suggests fixes |
+| Create mock server, fake API, mock for frontend | `/postman:mock` | Checks for examples, generates missing ones, provides integration config |
+| Generate docs, improve documentation, publish docs | `/postman:docs` | Analyzes completeness, fills gaps, can publish to Postman |
+| Security audit, check for vulnerabilities, OWASP | `/postman:security` | 20+ security checks with severity scoring and remediation |
+| Set up Postman, configure API key, first-time setup | `/postman:setup` | Guided setup with workspace verification |
+| Is my API agent-ready?, scan my API, analyze my spec | **readiness-analyzer agent** | 48 checks across 8 pillars, scoring and fix recommendations |
+
+## Routing Rules
+
+1. **Specific commands take priority.** If the intent clearly maps to one command, use it.
+2. **Agent-readiness questions go to the agent.** Phrases like "agent-ready", "scan my API", "analyze my spec for AI" trigger the readiness-analyzer agent.
+3. **Ambiguous requests get clarified.** If you can't determine intent, ask: "I can sync collections, generate client code, search for APIs, run tests, create mocks, generate docs, or audit security. What do you need?"
+4. **Multi-step requests chain commands.** "Import my spec and run tests" = `/postman:sync` then `/postman:test`.
+
+## When to Use Raw MCP Tools
+
+Only use `mcp__postman__*` tools directly when:
+- Making a single, targeted update (e.g., updating one request's body)
+- The user explicitly asks to call a specific MCP tool
+- The task doesn't match any command workflow