Update to Postman

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,71 +1,65 @@
 ---
 name: postman-mcp-server
-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
+description: Use when working through Postman MCP tools to inspect or change workspace resources, choose a targeted operation, or handle MCP limitations. Supports hosted workflows when the CLI is unavailable and distinguishes tool completion from a usable result. Use for requests such as "use Postman MCP to inspect this collection".
 ---
 
-# Postman Knowledge
+# Postman MCP Server
 
-Reference for Postman concepts and MCP tool selection. Use this context when working with Postman MCP tools to make better decisions.
-
-See `references/setup.md` for how to to setup postman mcp server and auth.
-
-## 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 | Use `searchPostmanElements`, 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 |
-| Learn how to use a Postman feature | Search Postman docs with `searchLearningCenter` (Full mode) |
-
-## 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` , `getTaggedEntities`
-**Learning Center:** `searchLearningCenter` (Full mode only — searches Postman product docs for how-to guidance)
-**User:** `getAuthenticatedUser`
-
-See `references/mcp-limitations.md` for known limitations and workarounds.
-
-## Workflows
-
-Each reference below is a full MCP-tool workflow for one goal — the tool
-call sequence, what to present at each step, and error handling. Reach for
-one once the Decision Guide above has picked a goal; they assume MCP tools
-only, no `postman` CLI.
-
-- `references/setup.md` — first-run auth (OAuth or API key) and workspace verification.
-- `references/search.md` — discover APIs across workspaces with `searchPostmanElements`.
-- `references/sync.md` — create/update collections from specs, or sync a spec from collection changes.
-- `references/mock.md` — create a mock server from a collection or spec.
-- `references/test.md` — run collection tests and diagnose failures.
-- `references/docs.md` — generate, improve, and publish API documentation.
-- `references/security.md` — audit a spec or collection against the OWASP API Top 10.
-- `references/learn.md` — search the Postman Learning Center for how-to guidance.
+MCP exposes workspace resources directly to an agent. Existing collections,
+specs, examples, and environments provide maintained API knowledge; fetching
+the relevant entity preserves that context when a local CLI workflow is not
+available. For repository edits and Git review, prefer the local workflows in
+**api-engineer** and **bootstrap** when available.
+
+Each tool definition exposed to the model consumes context whenever it is
+included in a request. Prefer the smallest available toolset that covers the
+task; expanding to every tool can crowd out the API evidence needed to reason.
+When exposed, call `getEnabledTools` to inspect the active toolset before
+diagnosing a missing operation. Otherwise use the host's discovered tools and
+report that limitation. Do not infer availability from reference tool names or
+assume a client can switch a route pinned to a specific MCP endpoint.
+
+1. Select tools from the connected server's actual surface. Tool availability
+   varies by mode; a name listed in a reference is not proof it is exposed.
+   Use [setup](references/setup.md) for connection/auth failures and
+   [limitations](references/mcp-limitations.md) when an operation is missing
+   or behaves differently from the CLI.
+2. Search to locate an entity, then fetch enough detail to work on it.
+   `searchPostmanElements` finds candidates; collection, spec, and workspace
+   detail tools establish IDs, ownership, and content. A search preview is
+   insufficient evidence for replacing a collection or declaring an API absent.
+3. Match the mutation to the intended scope. Request-level updates preserve
+   unrelated collection content; whole-collection replacement requires the
+   current complete object. A workspace is a container and access boundary,
+   not a reason to create duplicate resources whenever a new task begins.
+4. Preserve the source of truth when synchronizing. Spec-to-collection
+   generation reuses the interface, while collection-to-spec sync carries
+   changes in the other direction. Choose from the intended contract rather
+   than overwriting whichever artifact is easiest to reach. An asynchronous
+   acceptance response needs a completed task result before claiming sync.
+5. Treat publication separately from editing. A collection example can feed
+   docs and a classic mock, but neither becomes publicly accessible merely
+   because it exists. Apply the user's intended audience and authorization
+   before publishing docs or mocks, or changing shared resources.
+
+Read the reference for the branch being used:
+
+| Task | Reference and decision it supports |
+| --- | --- |
+| Locate an API | [Search](references/search.md): narrow candidates to the intended resource |
+| Generate or synchronize artifacts | [Sync](references/sync.md): choose source and track completion |
+| Serve saved examples | [Mock](references/mock.md): classic collection mocks; for CLI Code Mocks use **api-mocking** |
+| Execute saved assertions | [Test](references/test.md): distinguish run completion from failures |
+| Improve or publish docs | [Docs](references/docs.md): fill contract gaps and verify reader access |
+| Requested security review | [Security](references/security.md): assess concrete API risks |
+| Product how-to questions | [Learning Center](references/learn.md): product documentation search when exposed |
+
+## Verification
+
+State the active toolset as observed through `getEnabledTools`, or identify the
+host discovery evidence used when that tool is unavailable. Report any operation
+the connected surface could not perform instead of claiming it succeeded.
+
+Report the resource and observed result: assertions for a run, completed sync
+for a generated artifact, or the reachable URL and visibility for publication.
+Tool success alone does not establish any of those outcomes.