@postman/postman-plugin 0.1.0 → 0.1.2-rc.0

package/README.md

@@ -24,7 +24,7 @@ Install Postman in every compatible coding agent detected on your machine:
 npx @postman/postman-plugin
 ```
 
-One command configures **Claude Code, Codex, Cursor, Kimi Code and OpenCode**.
+One command configures **Claude Code, Codex, Cursor, Kimi Code, OpenCode and Pi**.
 Run it again to update, `status` to see what's installed, and `remove` to
 uninstall; `--agent <id>` limits any of them to one agent.
 
@@ -54,6 +54,18 @@ claude plugin install postman@postman
 codex plugin add postman@postman
 ```
 
+### Pi
+
+[View Postman in Pi's package gallery](https://pi.dev/packages/@postman/postman-plugin)
+
+```bash
+pi install npm:@postman/postman-plugin
+```
+
+`pi update npm:@postman/postman-plugin` updates it. Sign in to Postman's MCP
+server with `/mcp login postman` inside a Pi session. The shell's `pi mcp login`
+doesn't load extensions, so it reports no server named `postman`.
+
 ## Highlights
 
 ### Filesystem-first API development

package/dist/hosts/index.js

@@ -3,4 +3,5 @@ import { codex } from './codex.js';
 import { cursor } from './cursor.js';
 import { kimi } from './kimi.js';
 import { opencode } from './opencode.js';
-export const HOSTS = [claudeCode, codex, cursor, kimi, opencode];
+import { pi } from './pi.js';
+export const HOSTS = [claudeCode, codex, cursor, kimi, opencode, pi];

package/dist/hosts/pi.js

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { PI_SOURCE, REPO, isSameRepo, redact } from '../source.js';
+import { failed, guard, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+const NEXT = 'Restart Pi, or run `/reload` in an open session, for the change to take effect.', GIT_PREFIX = /^git:/, 
+// Pi's ref is everything after the first `@` in the repo path, slashes included. The path starts
+// after the scp-style `host:` or after the host, so an `@` in URL user-info is never a ref.
+SCP_WITH_REF = /^(git@[^:]+:[^@]*)@/, URL_WITH_REF = /^((?:[a-z][a-z0-9+.-]*:\/\/)?[^/]*\/[^@]*)@/i;
+function agentDir(system) {
+    const dir = system.env.PI_CODING_AGENT_DIR;
+    if (!dir) {
+        return path.join(system.home, '.pi', 'agent');
+    }
+    return dir === '~' || dir.startsWith('~/') ? path.join(system.home, dir.slice(1)) : dir;
+}
+function withoutRef(source) {
+    const url = source.replace(GIT_PREFIX, '');
+    return (url.match(SCP_WITH_REF) ?? url.match(URL_WITH_REF))?.[1] ?? url;
+}
+// Pi keys an npm package by its name, so a pinned `npm:@postman/postman-plugin@x` is this
+// package too. A git install of this repo is another package loading the same skills.
+const settingsFile = (system) => path.join(agentDir(system), 'settings.json'), isOurPackage = (source) => source === PI_SOURCE || source.startsWith(`${PI_SOURCE}@`), isRepoClone = (source) => !source.startsWith('npm:') && isSameRepo(withoutRef(source), REPO);
+/** Every package source in Pi's user settings, or `null` when the file can't be parsed. */
+async function packageSources(system) {
+    const text = await system.readFile(settingsFile(system));
+    if (text === null) {
+        return [];
+    }
+    // Pi parses the file the same way, so a file that fails here fails in `pi` too.
+    const settings = parseJson(text.replace(/^\uFEFF/, ''));
+    if (!settings || (settings.packages !== undefined && !Array.isArray(settings.packages))) {
+        return null;
+    }
+    return (settings.packages ?? [])
+        .map((entry) => (typeof entry === 'string' ? entry : entry?.source))
+        .filter((source) => typeof source === 'string');
+}
+async function readableSources(system) {
+    return (await packageSources(system)) ?? failed(`${settingsFile(system)} is not valid JSON; fix it and re-run`);
+}
+export const pi = {
+    id: 'pi',
+    name: 'Pi',
+    route: 'installer/package.json',
+    async detect(system) {
+        return (await system.which('pi')) !== null;
+    },
+    async status(system) {
+        const sources = await packageSources(system);
+        if (sources === null) {
+            return { installed: null, detail: `could not read ${settingsFile(system)}`, notes: [] };
+        }
+        const ours = sources.find(isOurPackage), notes = [
+            ...(ours && ours !== PI_SOURCE ? [`${ours} is pinned, so an update leaves it at that version`] : []),
+            ...sources.filter(isRepoClone).map((source) => `${redact(source)} loads the same skills and will be removed`)
+        ];
+        return ours ?
+            { installed: true, detail: `${ours} in ${settingsFile(system)}`, notes } :
+            { installed: false, detail: 'not installed', notes };
+    },
+    install(system) {
+        return guard(async () => {
+            const sources = await readableSources(system), installed = sources.some(isOurPackage);
+            // Replacement first: if it fails, a git copy of this repo is still a working one.
+            await mustRun(system, 'pi', [installed ? 'update' : 'install', PI_SOURCE]);
+            for (const source of sources.filter(isRepoClone)) {
+                await mustRun(system, 'pi', ['remove', source]);
+            }
+            return result('done', `${installed ? 'updated' : 'installed'} ${PI_SOURCE} in ${settingsFile(system)}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const sources = await readableSources(system), targets = [...(sources.some(isOurPackage) ? [PI_SOURCE] : []), ...sources.filter(isRepoClone)];
+            if (!targets.length) {
+                return result('skipped', 'not installed');
+            }
+            for (const source of targets) {
+                await mustRun(system, 'pi', ['remove', source]);
+            }
+            return result('done', `removed ${targets.map(redact).join(', ')}`, NEXT);
+        });
+    }
+};

package/dist/pi-extension.js

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** In the tarball, where `prepack` staged the repo's shared files beside `dist/`. */
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), ENTRY_SKILL = 'api-engineer', SECTION = 'postman';
+/** Pi's skill names are un-namespaced; the shared mandate names them `postman:<skill>` for the other routes. */
+export function toPiSessionContext(source) {
+    return source.replace(/`postman:([a-z0-9-]+)`/g, '`$1`');
+}
+/** Reads the mandate and the MCP config from `root`, which is laid out like the repository root. */
+export function postmanExtension(root) {
+    return (pi) => {
+        const mandate = toPiSessionContext(fs.readFileSync(path.join(root, 'hooks', 'session-start-context.md'), 'utf8')), { mcpServers } = JSON.parse(fs.readFileSync(path.join(root, 'mcp.pi.json'), 'utf8'));
+        // A `postman` server in the user's own mcp.json takes precedence over this registration.
+        for (const [name, server] of Object.entries(mcpServers)) {
+            pi.registerMcpServer(name, server);
+        }
+        // Pi's stand-in for the SessionStart hook. The mandate routes to a skill, so it goes only
+        // where that skill loaded; `pi config` can disable it.
+        pi.on('before_agent_start', ({ systemPromptOptions }) => {
+            if (systemPromptOptions.skills.some((skill) => skill.name === ENTRY_SKILL)) {
+                systemPromptOptions.sections[SECTION] = mandate;
+            }
+        });
+    };
+}
+export default postmanExtension(packageRoot);

package/dist/source.js

@@ -1,8 +1,10 @@
-/** Where every host's copy of the plugin comes from. The npm package carries no skills. */
+/** Where every host's copy of the plugin comes from. Pi alone installs the npm package instead. */
 export const REPO = 'postmanlabs/postman-plugin';
 export const GIT_URL = `https://github.com/${REPO}.git`;
 /** The branch every clone this installer makes tracks. */
 export const BRANCH = 'main';
+/** Unpinned, so `pi update` moves it with each `latest` release; test/pi-package.test.js checks the name. */
+export const PI_SOURCE = 'npm:@postman/postman-plugin';
 /** Must stay byte-identical to the shim in opencode/README.md; test/routes.test.js enforces it. */
 export const OPENCODE_SHIM = "export { default } from '../postman-plugin/opencode/src/index.ts';\n";
 /** Pinned: this third-party CLI writes Kimi's plugin store for us, and an unpinned npx would run whatever is latest. */

package/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 — load the `postman:api-engineer` skill 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 (project instruction files such as AGENTS.md or CLAUDE.md, and direct requests) take precedence over this mandate.
+</EXTREMELY_IMPORTANT>

package/mcp.pi.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "postman": {
+      "type": "http",
+      "url": "https://mcp.postman.com/mcp",
+      "description": "Postman workspaces, collections, specs, environments, mocks and monitors",
+      "headers": {
+        "X-Source": "postman-pi-plugin",
+        "X-Plugin-Version": "0.1.2-rc.0",
+        "User-Agent": "postman-pi-plugin/0.1.2-rc.0"
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.1.0",
-  "description": "Installs the Postman plugin into every supported coding agent on this machine.",
+  "version": "0.1.2-rc.0",
+  "description": "Postman's API engineering skills for coding agents: a Pi package, and an npx installer that sets up Claude Code, Codex, Cursor, Kimi Code, OpenCode and Pi.",
   "type": "module",
   "license": "Apache-2.0",
   "author": {
@@ -17,6 +17,8 @@
   },
   "bugs": "https://github.com/postmanlabs/postman-plugin/issues",
   "keywords": [
+    "pi-package",
+    "pi",
     "postman",
     "claude-code",
     "codex",
@@ -29,13 +31,26 @@
     "postman-plugin": "dist/cli.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "skills/",
+    "hooks/session-start-context.md",
+    "mcp.pi.json"
   ],
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://assets.getpostman.com/common-share/postman-logo-horizontal-320x132.png"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build && node scripts/pack-docs.js stage",
-    "postpack": "node scripts/pack-docs.js clean",
-    "test": "npm run build && node --test test/*.test.js"
+    "prepack": "npm run build && node scripts/pack-repo-files.js stage",
+    "postpack": "node scripts/pack-repo-files.js clean",
+    "test": "npm run build && node --test test/*.test.js",
+    "test:pi-harness": "node scripts/pi-harness.js"
   },
   "devDependencies": {
     "@types/node": "24.5.2",

package/skills/ai-readiness/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ai-readiness
+description: Scores a Postman collection or an OpenAPI spec for how well an AI agent can discover, understand, call, and recover from errors with it — missing examples, undocumented errors, and ambiguous parameters all cost points. Use when the user asks "is my API agent-ready," "can AI agents use my API," "how agent-friendly is my API," or wants to scan, score, or improve a collection or spec for AI/agent consumption. Covers `postman collection ai-readiness` and `postman spec ai-readiness`.
+---
+
+# AI Readiness
+
+## Overview
+
+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.
+
+Two ways to run this check, same rubric family, different target — pick by what exists:
+
+- `collection ai-readiness <collectionId/path>` scores a Postman collection
+  — by cloud ID, local file path, or a `postman/collections/<name>`
+  local-mode directory.
+- `spec ai-readiness <spec>` 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
+gives you, don't recompute them:
+
+- **`readiness`** (score 0-100 + bucket) is the headline number. Buckets,
+  low to high: **Limited → Fair → Good → Excellent**.
+- **`confidence`** (`high`/`medium`/`low`) says how many signals it
+  could actually measure vs. had to mark `unknown` — a data-quality
+  caveat, not part of the score.
+
+## Interpreting Results
+
+Report the bucket, score, and confidence the command actually printed
+— don't infer a percentage band. Doc coverage is a modifier via its
+adjustment, not a separate gate; call it out by name when it's `low`,
+since recommendations flag that first. Also state which verb ran
+(`collection` vs. `spec` `ai-readiness`), which target was scored
+(local path vs. cloud ID), the output mode, and — if `--min-score` was
+set — the resulting exit code, not just "it passed."
+
+You can ask user if they would like to set this check with a min score guarantee to run on their CI.
+
+## Reference
+
+- `collection-schema-v3` skill — what saved examples and descriptions look
+  like in the git-synced format this command reads.
+- `ci-integration` skill — where `--min-score` fits as a pipeline gate
+  alongside `spec lint`/`collection lint`/`workspace lint`.

package/skills/api-discovery/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: api-discovery
+description: Discover and use APIs from the web or Postman. Find and integrate public third-party APIs with Orbit, locate Postman entities with search, and use the Context Graph to investigate dependencies, ownership, runtime behavior, and change impact across an API ecosystem.
+---
+
+# API Discovery
+
+## Overview
+
+Use this guide for any task that involves discovering an API — whether it
+lives on the public web or inside Postman as a workspace, collection, request,
+spec, mock, document, or flow. You can find entities across every surface: your
+own private work, anything your team or organization shares, and resources
+owned by external organizations. Beyond finding entities, this guide also
+covers understanding how they relate to one another — for example, "which
+services consume this API?"
+
+Each discovery option serves a distinct purpose:
+
+- **Orbit** → discovers and integrates **public third-party APIs**. No signup
+  or API key, and it uses ~27× less context than loading a vendor OpenAPI spec.
+  Search returns matching endpoints — including what each one
+  *cannot* do — and integrate returns a task brief specific enough to write
+  code against. It accepts both keyword and natural-language queries. Reach for
+  it instead of writing a third-party integration from memory.
+- **`search`** → **finds any Postman entity**, for tasks like "update the tests
+  in my collection and run them" or "where is the documentation for our
+  access-control API?"
+- **`context-graph ask`** → answers organization-wide relationship and impact
+  questions such as "what depends on billing-api?" or "what could this schema
+  change break?"
+
+These three draw on different data sources, so a miss in one is not proof of a
+miss in the others. `search` locates a known Postman resource; the Context
+Graph discovers relationships around a known starting point. Use both when a
+task needs the resource itself and its wider impact.
+
+## Orbit — Public API Discovery
+
+Orbit finds public third-party APIs. It's free, needs no signup or API key, and
+works entirely against publicly available APIs. REST base:
+`https://api.buildwithorbit.ai`. Docs: `https://www.buildwithorbit.ai`.
+
+Reach for Orbit whenever a task needs an external capability — weather,
+payments, invoicing, messaging, geocoding, calendar, and so on — even when the
+user already named a provider. Rather than writing integration code from
+memory, let Orbit hand you the details that matter: paths, auth header names,
+required fields, and the rest. It works in two steps, search then integrate,
+and a typical round trip runs ~2,500 tokens and ~15–20s end to end — against
+~69,000 tokens for a full vendor OpenAPI spec.
+
+Two REST calls, both `POST`:
+
+1. **Search** (`POST /v1/search`) — describe the task, e.g.
+   `{ "q": "send email via SMTP" }`. Returns candidate endpoints, each with an
+   `id` and `resourceType` (pass both back verbatim) and an `evaluateGuide`
+   grading its fit.
+2. **Integrate** (`POST /v1/integrate`) — send the task plus the chosen
+   resources (up to 10). Returns a `taskBrief` with `FIT`, `AUTH`, `BASE URL`,
+   `STEPS`, and `GOTCHAS` — read the GOTCHAS before writing the client.
+
+Full endpoint schemas, request/response shapes, `taskBrief` fields, and error
+handling: [reference/orbit.md](reference/orbit.md).
+
+## `search`
+
+`postman search <type> <query>` finds any Postman entity, searching across
+`requests`, `collections`, `workspaces`, `flows`, `specs`, `mocks`,
+`environments`, or `documents`. The query can be a keyword or natural language,
+and is optional (omit it to list or filter a type outright). Narrow with
+`--ownership` and `--filter`, and add `-o json` for the enriched payload. An
+empty default-scope result is not proof nothing exists — retry with
+`--ownership all` before reporting that.
+
+```bash
+postman search requests "where do we validate a user's email?"
+postman search collections "payments" --ownership external --filter "visibility=public"
+```
+
+Use `postman search <type> -h` for more details — ownership modes, the
+`--filter` / `--filter-json` syntax, filter fields per type, and the exact
+installed-version flags.
+
+## `context-graph`
+
+The Context Graph is a private, authenticated map of an API ecosystem. It
+reconciles Postman specifications, collections, monitors, and mocks; GitHub
+repositories, definitions, and call sites; and New Relic deployments, traffic,
+and telemetry. These become typed entities joined by sourced relationships such
+as `calls`, `depends_on`, `owned_by`, and `monitored_by`.
+
+Use it before a cross-service or potentially breaking change. Name the endpoint,
+schema, service, database, deployment, or shared module being changed; the graph
+discovers the surrounding scope, including runtime callers and repositories not
+checked out locally:
+
+```bash
+postman context-graph ask "What depends on billing-api?" --wait
+postman context-graph ask "What is the likely blast radius of changing this schema?" --wait
+```
+
+Treat the result as a lead, not proof. For consequential work, verify candidates
+against source, API definitions, deployment configuration, or telemetry and
+cite that evidence. Sources are connected through Postman's Agent Context UI
+and refresh nightly; an unconnected or not-yet-ingested source makes absence
+inconclusive.
+
+`--wait` polls the asynchronous API and prints the answer. Without it, `ask`
+returns an ID for `postman context-graph status <askId>`. Use `--json` for the
+structured record; `--timeout`, `--interval`, and `--max-steps` control waiting
+and reasoning.
+
+The query runs against the team derived from the API key; there is no workspace
+or team selector. Authentication uses `--api-key`, `POSTMAN_API_KEY`, or the
+current `postman login` session, in that order.
+
+## After discovery: reusing what was found
+
+`dependency add <type> <nameOrId>` formally adds a collection, environment,
+or mock found in another workspace as a dependency of the current one —
+the step after `search` finds something worth reusing (e.g., feeding
+`application test`'s contract matching), rather than copying it in by hand. It
+takes a Postman entity ID. If the Context Graph identifies a service or API to
+reuse, locate its collection with `search` first, then pass that entity ID to
+`dependency add`.
+
+## Reference
+
+- [Orbit](reference/orbit.md) — public API discovery: the search/integrate
+  REST endpoints, request/response shape, `taskBrief` fields, and error
+  handling. (Docs at `https://www.buildwithorbit.ai`, REST at
+  `https://api.buildwithorbit.ai`.)
+
+For `postman search`, run `postman search <type> -h` — the CLI's own help is
+per-type, complete, and always matches your installed version.

package/skills/api-discovery/reference/orbit.md

@@ -0,0 +1,101 @@
+# Orbit — public API discovery reference
+
+Orbit finds and integrates **public third-party APIs** — weather, payments,
+invoicing, messaging, geocoding, calendar, and the like. It is free, needs no
+signup and no API key, and works entirely against publicly available APIs.
+
+- REST base: `https://api.buildwithorbit.ai`
+- Docs: `https://www.buildwithorbit.ai`
+
+## Implementation
+
+Two REST calls, both `POST`, both read-only (safe to retry). No auth header —
+send `Content-Type: application/json` and a JSON body. Run search first,
+surface candidates, then integrate the chosen ids.
+
+```bash
+# Step 1 — search
+curl -sS https://api.buildwithorbit.ai/v1/search \
+  -H 'Content-Type: application/json' \
+  -d '{ "q": "send email via SMTP", "limit": 10 }'
+
+# Step 2 — integrate (ids come from the search response, verbatim)
+curl -sS https://api.buildwithorbit.ai/v1/integrate \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Send a welcome email when a user signs up",
+    "resources": [{ "id": "urn:orbit:endpoint:v1:...", "type": "endpoint" }]
+  }'
+```
+
+Implementation notes:
+
+- A typical search+integrate is ~2,500 tokens and ~15–20s end to end, vs
+  ~69,000 tokens for loading a vendor OpenAPI spec.
+- One integrate call can span up to 10 resources across different providers;
+  batch every endpoint the task needs into a single `resources` array rather
+  than making one call per endpoint.
+- Auth, request bodies, `Threading`, and `GOTCHAS` come from live public API
+  schemas, so take them from the brief rather than from memory.
+
+## Step 1 — Search (`POST /v1/search`)
+
+Describe the task, not a provider name. Good: `"send an invoice to a customer"`.
+Worse: `"PayPal"`. Provider name is fine to include when it is fixed.
+
+```json
+{ "q": "send email via SMTP" }
+```
+
+Query params:
+
+- `limit` — default 10, max 25.
+- `cursor` — from `meta.nextCursor`; pagination stops at 40 results.
+- `q` — max 512 characters.
+
+Returns `data[]`. Each item has:
+
+- `id` — opaque URN. Pass it back verbatim; never construct, shorten, or edit
+  it.
+- `resourceType` — `endpoint` or `mcp`.
+- `name`, `method`, `url`, `description`.
+- `evaluateGuide` — how well the endpoint fits the task, including what it
+  cannot do.
+
+Hold onto both `id` and `resourceType` — both are required for integrate. Do not
+read `meta.total` as a match count; it reports the page size.
+
+## Step 2 — Integrate (`POST /v1/integrate`)
+
+Pass the same task plus every endpoint the job needs (up to 10). Use
+`resourceType` from the search result as the `type` field.
+
+```json
+{
+  "task": "Send a welcome email when a user signs up",
+  "resources": [{ "id": "urn:orbit:endpoint:v1:...", "type": "endpoint" }]
+}
+```
+
+Returns a `taskBrief` covering:
+
+- `FIT` — Fully or Partially (and names the gap if Partial).
+- `AUTH` — use the exact header name given; it is frequently not
+  `Authorization`.
+- `BASE URL`.
+- numbered `STEPS` — method, path, every parameter with an example, expected
+  responses, `Threading`.
+- `GOTCHAS` — read these before writing the client.
+
+## Error handling
+
+Both endpoints are read-only, so retries are safe. Free and unauthenticated is
+not unlimited — back off on `429`.
+
+- `400` — invalid input.
+- `404` on integrate — no IDs resolved.
+- `500` — server error.
+
+If `FIT` is not Fully, say what's missing before writing code. If the brief
+names a credential the user doesn't have yet, stop and tell them which one to
+get.

package/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.

package/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.

package/skills/api-engineer/SKILL.md

@@ -0,0 +1,29 @@
+---
+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.
+9. Prefer filesystem-first Postman workflows. For an existing cloud workspace,
+   `postman workspace pull <id>` connects it and materializes its collections,
+   environments, and specs locally. When no cloud workspace exists, `postman
+   init --no-cloud` initializes the local structure. Work against those files,
+   validate them, and push only with user consent; sharing an already-bound
+   workspace means `workspace push`, not creating a duplicate. See
+   **bootstrap** for the lifecycle decision table.
+10. When actual use exposes a concrete Postman CLI gap or a misleading skill, handle the user's task first — then use `postman feedback` to report the gaps/bugs. Exclude secrets, user data, and proprietary content
+
+## 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**.