From 5a80d10dc72599d183ba41fc1e588a226279e287 Mon Sep 17 00:00:00 2001 From: Diego Garcia Date: Mon, 21 Sep 2026 18:13:44 +0200 Subject: [PATCH 1/2] Sync skills and hooks from postmanlabs/postman-plugin main Ports the two skills devrel-plugin was missing (api-engineer as the default API-engineering entry point, api-documentation for filesystem-first agent-friendly docs), adds the hooks/ directory with the SessionStart hook that routes non-trivial API work to postman:api-engineer, and re-syncs three skills that had drifted (ai-readiness, api-discovery's search_filters reference, bootstrap) to match the source repo's current whitespace/heading style. --- CHANGELOG.md | 14 ++++++ hooks/hooks.json | 17 +++++++ hooks/session-start-context.md | 11 +++++ skills/ai-readiness/SKILL.md | 2 + .../api-discovery/reference/search_filters.md | 2 - skills/api-documentation/SKILL.md | 34 ++++++++++++++ .../reference/rest-api-best-practices.md | 47 +++++++++++++++++++ skills/api-engineer/SKILL.md | 21 +++++++++ skills/bootstrap/SKILL.md | 4 +- 9 files changed, 148 insertions(+), 4 deletions(-) create mode 100644 hooks/hooks.json create mode 100644 hooks/session-start-context.md create mode 100644 skills/api-documentation/SKILL.md create mode 100644 skills/api-documentation/reference/rest-api-best-practices.md create mode 100644 skills/api-engineer/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a314332..dfc5b89 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..9fece4f --- /dev/null +++ b/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 + } + ] + } + ] + } +} diff --git a/hooks/session-start-context.md b/hooks/session-start-context.md new file mode 100644 index 0000000..87dfe39 --- /dev/null +++ b/hooks/session-start-context.md @@ -0,0 +1,11 @@ + +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. + diff --git a/skills/ai-readiness/SKILL.md b/skills/ai-readiness/SKILL.md index 5859e6f..f74e5e8 100644 --- a/skills/ai-readiness/SKILL.md +++ b/skills/ai-readiness/SKILL.md @@ -17,6 +17,8 @@ Two ways to run this check, same rubric family, different target — pick by wha - `spec ai-readiness ` scores an OpenAPI specification directly — by cloud ID or local file path — with no collection involved at all. + + ## Scoring The command computes and prints the score itself — read the fields it diff --git a/skills/api-discovery/reference/search_filters.md b/skills/api-discovery/reference/search_filters.md index c3443cf..af258fa 100644 --- a/skills/api-discovery/reference/search_filters.md +++ b/skills/api-discovery/reference/search_filters.md @@ -53,7 +53,6 @@ first to find them. ## Element-specific fields **`requests`** - | Field | Operators | Value | | --- | --- | --- | | `collectionId` | `$eq`, `$ne`, `$in`, `$nin` | id | @@ -62,7 +61,6 @@ first to find them. | `type` | `$eq`, `$ne`, `$in`, `$nin` | `http-request`, `graphql-request`, `grpc-request`, `ws-raw-request`, `ws-socketio-request`, `mqtt-request`, `llm-request` | **`specs`** - | Field | Operators | Value | | --- | --- | --- | | `specificationId` | `$eq`, `$ne`, `$in`, `$nin` | id | diff --git a/skills/api-documentation/SKILL.md b/skills/api-documentation/SKILL.md new file mode 100644 index 0000000..44d4b0f --- /dev/null +++ b/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. diff --git a/skills/api-documentation/reference/rest-api-best-practices.md b/skills/api-documentation/reference/rest-api-best-practices.md new file mode 100644 index 0000000..41dfec0 --- /dev/null +++ b/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. diff --git a/skills/api-engineer/SKILL.md b/skills/api-engineer/SKILL.md new file mode 100644 index 0000000..6d1400f --- /dev/null +++ b/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**. diff --git a/skills/bootstrap/SKILL.md b/skills/bootstrap/SKILL.md index e22bb4f..800792b 100644 --- a/skills/bootstrap/SKILL.md +++ b/skills/bootstrap/SKILL.md @@ -52,7 +52,7 @@ pick from what it prints. --- -## Process +# Process Four steps, in order. Stop at the first that fails and report which one. @@ -172,7 +172,7 @@ written but the requested workspace was not created — it does *not* mean re-ru --- -## Reference Files +# Reference Files - `collection-schema-v3` skill — read when inspecting or writing the collection files this skill resolves. From b7faad972f2216e28c5ba4221d908383403c42d2 Mon Sep 17 00:00:00 2001 From: Diego Garcia Date: Mon, 21 Sep 2026 20:02:43 +0200 Subject: [PATCH 2/2] Fix markdownlint violations in synced skills Multiple-blank-lines, missing blank lines around tables, and duplicate top-level headings, all introduced by copying source files verbatim from postman-plugin, which doesn't run the same markdownlint config. --- skills/ai-readiness/SKILL.md | 2 -- skills/api-discovery/reference/search_filters.md | 2 ++ skills/bootstrap/SKILL.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/ai-readiness/SKILL.md b/skills/ai-readiness/SKILL.md index f74e5e8..5859e6f 100644 --- a/skills/ai-readiness/SKILL.md +++ b/skills/ai-readiness/SKILL.md @@ -17,8 +17,6 @@ Two ways to run this check, same rubric family, different target — pick by wha - `spec ai-readiness ` scores an OpenAPI specification directly — by cloud ID or local file path — with no collection involved at all. - - ## Scoring The command computes and prints the score itself — read the fields it diff --git a/skills/api-discovery/reference/search_filters.md b/skills/api-discovery/reference/search_filters.md index af258fa..c3443cf 100644 --- a/skills/api-discovery/reference/search_filters.md +++ b/skills/api-discovery/reference/search_filters.md @@ -53,6 +53,7 @@ first to find them. ## Element-specific fields **`requests`** + | Field | Operators | Value | | --- | --- | --- | | `collectionId` | `$eq`, `$ne`, `$in`, `$nin` | id | @@ -61,6 +62,7 @@ first to find them. | `type` | `$eq`, `$ne`, `$in`, `$nin` | `http-request`, `graphql-request`, `grpc-request`, `ws-raw-request`, `ws-socketio-request`, `mqtt-request`, `llm-request` | **`specs`** + | Field | Operators | Value | | --- | --- | --- | | `specificationId` | `$eq`, `$ne`, `$in`, `$nin` | id | diff --git a/skills/bootstrap/SKILL.md b/skills/bootstrap/SKILL.md index 800792b..e22bb4f 100644 --- a/skills/bootstrap/SKILL.md +++ b/skills/bootstrap/SKILL.md @@ -52,7 +52,7 @@ pick from what it prints. --- -# Process +## Process Four steps, in order. Stop at the first that fails and report which one. @@ -172,7 +172,7 @@ written but the requested workspace was not created — it does *not* mean re-ru --- -# Reference Files +## Reference Files - `collection-schema-v3` skill — read when inspecting or writing the collection files this skill resolves.