Sync skills and hooks from postmanlabs/postman-plugin main

CHANGELOG.md

@@ -10,6 +10,20 @@ is cut by tagging the matching `vX.Y.Z` (see [Releasing](#releasing)).
 
 ## [Unreleased]
 
+### Added
+
+- `api-documentation` and `api-engineer` skills, ported from postmanlabs/postman-plugin.
+  `api-engineer` is a default entry point for API engineering work that routes to the
+  other skills; `api-documentation` generates filesystem-first, agent-friendly API docs.
+- `hooks/hooks.json` with a `SessionStart` hook that injects `hooks/session-start-context.md`,
+  directing Claude to invoke `postman:api-engineer` for non-trivial API engineering tasks.
+
+### Changed
+
+- Synced `ai-readiness`, `api-discovery` (search filters reference), and `bootstrap`
+  skills to match their postmanlabs/postman-plugin source (whitespace/heading-level only,
+  no behavior change).
+
 ## [1.3.1] - 2026-08-02
 
 ### Changed

hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start-context.md\"",
+            "shell": "bash",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

hooks/session-start-context.md

@@ -0,0 +1,11 @@
+<EXTREMELY_IMPORTANT>
+You have the Postman plugin.
+
+Before responding to any non-trivial API engineering task — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API or Postman Flow — invoke the `postman:api-engineer` skill with the Skill tool and follow it. It is the default entry point and routes to the specific postman skills from there. Pure questions and trivial one-line edits don't need it.
+
+When the intent is already specific, you may enter directly into the relevant skill instead: `postman:bootstrap` (link this repo to a Postman workspace), `postman:api-mocking`, `postman:api-testing`, `postman:api-monitoring`, `postman:flows`, `postman:ci-integration`, `postman:api-discovery`, `postman:ai-readiness`, `postman:performance-testing`, `postman:api-documentation`.
+
+If you were dispatched as a subagent to execute a specific task, ignore this block — `postman:api-engineer` governs the orchestrating session, and it already shaped your dispatch.
+
+User instructions (CLAUDE.md, AGENTS.md, direct requests) take precedence over this mandate.
+</EXTREMELY_IMPORTANT>

skills/api-documentation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: api-documentation
+description: Generate filesystem-first agent friendly api documentation that you can share with your teammates without hassle. Use when the user asks to "publish API docs," "generate documentation for this API," "put this on the API Network," "share a docs link for this collection or spec," or "why do my docs look empty." 
+---
+The bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.
+
+# API Documentation
+When working on any API task, the first step is to establish and capture the contract.
+API documentation can be done in two predominant ways:
+1. through a Postman collection,
+2. with an OpenAPI spec
+
+It is recommended to create both. They serve different, complementary use cases, and it takes only one command to convert from one to another. Start with creating a Postman collection in v3 format, **collection-schema-v3**.
+Postman collections are very human-friendly and offer other capabilities like creating an API mock, monitor, SDK, or spec.
+
+Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.
+
+## Good practices for API design
+
+See [reference/rest-api-best-practices.md](reference/rest-api-best-practices.md)
+for the practices well-documented APIs tend to already follow: resource
+naming, HTTP method/status-code usage, error response shape, versioning,
+pagination, filtering, auth, idempotency, and backward compatibility. A
+spec or collection that already follows these renders documentation with
+nothing left to fix.
+
+### Examples
+Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
+1. anyone can look at them to see how your API behaves,
+2. they can be used to generate a mock from your collection in a single command.
+
+## Workflow
+1. Establish the contract - refer to best practices. Don't just accept the user's ask - fight for the right API design.
+2. Choose the instrument - Postman collection / OpenAPI spec - or both. Recommend using both to the user. Start with the Postman collection.

skills/api-documentation/reference/rest-api-best-practices.md

@@ -0,0 +1,47 @@
+# REST API Design Practices 
+
+- **Resource naming.** Nouns, not verbs, in the path (`POST /orders`, not
+  `POST /createOrder`). Plural collections, consistent casing, nesting
+  reflects real relationships and rarely goes past two levels deep.
+- **HTTP methods.** GET is read-only and safe to repeat. POST creates.
+  PUT replaces a whole resource and is idempotent. PATCH updates part of
+  one. DELETE removes and is idempotent. Never use GET to change state.
+- **Status codes.** 2xx for success (201 + `Location` on create, 204 for
+  no body), 4xx for client mistakes (401 vs. 403 vs. 404 vs. 409 vs. 422
+  each mean something distinct), 5xx for server failure. Inconsistent
+  codes are one of the most common sources of client bugs.
+- **Error responses.** One consistent shape across every endpoint, with a
+  stable machine-readable `code` plus a human-readable `message`, and all
+  validation failures returned together rather than one at a time.
+- **Versioning.** Decide the strategy (URI path like `/v2/users`, or a
+  version header) before the first breaking change forces the question.
+  A breaking change is a removed/renamed field, a changed type, or a
+  changed auth requirement — additive changes don't need a new version.
+- **Pagination.** Page/offset pagination is simple but can skip or repeat
+  items when the underlying data changes mid-list; cursor-based
+  pagination avoids that and holds up better for feeds and high-write
+  data. Either way, return the metadata a client needs to fetch the next
+  page without guessing.
+- **Filtering, sorting, searching.** Query parameters with names that say
+  what they filter/sort on, not internal field names.
+- **Auth.** API keys for server-to-server; OAuth bearer tokens when a
+  request needs to represent a specific user, scoped rather than
+  all-or-nothing. HTTPS always. Rate limits communicated through response
+  headers, not discovered by hitting them.
+- **Idempotency.** GET/PUT/DELETE are naturally or by-design idempotent;
+  POST isn't, so a client that might retry a POST (payments, especially)
+  needs an idempotency key the server can recognize on retry.
+- **Content type and shape.** JSON by default; keep response bodies flat
+  rather than deeply nested, and let a client ask for only the fields it
+  needs on large resources.
+- **Observability.** Log method, endpoint, status, and latency per
+  request; return a request ID in the response so a client's bug report
+  can be traced to server-side logs.
+- **Backward compatibility.** Add fields instead of changing or removing
+  them where possible. When something really must go, announce it, give
+  a migration path, and run the old and new versions side by side for a
+  window — a deprecation header on responses beats a changelog entry
+  nobody reads.
+- **Testing.** Beyond the happy path: auth failures, validation errors,
+  rate limiting, and retries — the same edge cases a thin API-readiness
+  score (see `ai-readiness`) tends to catch missing coverage for.

skills/api-engineer/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: api-engineer
+description: Default entry point for API engineering work — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
+---
+
+# API Engineer
+
+## Foundations
+1. Contract comes first. Establish and document the contract before starting implementation.
+2. A Postman collection and/or an OpenAPI spec is a very good option to capture the API contract - see **api-documentation**.
+3. Always validate the change against the contract you started with. Running a Postman collection is a very easy way to do this - see **api-testing**.
+4. Always propose next steps. Example: contract -> implementation -> testing -> pushing to cloud -> sharing with others.
+5. Don't jump straight into implementation. Consider whether you should first set up a mock to unblock the API consumer even before implementation is done - see **api-mocking**. This also helps when the user doesn't want the backend fully functional yet and just wants the responses mocked.
+6. Don't push to the cloud workspace (`postman workspace push`) without user consent. The recommended way to push to the cloud is a CI step on PR merge - see **ci-integration**.
+7. For high-quality API search results, use **api-discovery**.
+8. No is an acceptable answer. Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment.
+
+## Dos
+1. Prove it works - validate the task against the contract. See **api-testing**.
+2. Just do it - never block on the human. When tempted to ask "should I do X?" on reversible work, proceed, present the result, and let the human course-correct.
+3. Fight for good API design. See **api-documentation**.