Postman Plugin for Claude Code: A Hands-On Guide

This article was originally published on the Postman blog.

How agent-ready is your API spec? Score it from Claude Code.

If you live in Claude Code and maintain APIs that AI agents will call, you have probably seen two failure modes. The agent guesses wherever your spec is vague. And when a check goes red, it would rather loosen the check than fix the code. This walkthrough covers a repeatable, gated workflow for both: install the Postman plugin, put the contract first, score the spec, fix what the score points at, and move the gate somewhere the agent can't edit.

Why the spec sets the ceiling

Most APIs were written for a human who reads the docs, squints at an error message, and tries again. An agent doesn't do that well. It calls the endpoint your spec describes. If the spec says nothing about what happens when an order is out of stock, the agent guesses. Guessed behavior in an agent loop becomes retries, hallucinated parameters, and a confused on-call engineer.

The Postman plugin for Claude Code closes that gap from the terminal. It gives Claude Code a set of skills that run the real Postman CLI for each step of API work: discover, design, mock, test, document, and gate.

The frame for everything below: a coding agent doesn't need a UI. It needs a command per step, committed skills that say which command to run, and a gate it can't edit.

What you'll need

• Claude Code, signed in
• Node.js 18 or later, which the plugin uses to set up the Postman CLI for you
• A Postman account. The free plan works. Local commands such as linting, mocking and running a collection don't require you to sign in; anything that touches the Postman cloud does.
• A directory with git init run in it

Install the plugin

Install it from Anthropic's official Claude Code plugin marketplace. Register the marketplace once, then install:

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install postman@claude-plugins-official

That's the whole install. You don't need to install the Postman CLI yourself. The plugin's bootstrap skill checks for it the first time Claude needs it and installs it if it's missing.

Start a fresh Claude Code session so the plugin loads, then run /plugin and look for postman. You can also ask Claude:

Which Postman skills do you have available in this session?

Set the ground rules once with CLAUDE.md

Skills tell Claude how to use Postman. CLAUDE.md tells it how your repo works. Run this once in the project:

postman init

It links the repo to a workspace and commits the skills alongside your code, so a teammate's agent or a CI job gets the same guidance. Then add a short section to CLAUDE.md:

## API work
- `openapi.yaml` is the contract. Change it before you change code.
- Make HTTP calls with `postman request`, not curl.
- Before you say a change is done, run `postman spec lint openapi.yaml` and `postman collection run` against the mock.
- Never run `postman workspace push`. CI does that after merge.
- Never edit `.github/workflows/api-gate.yml` or lower a `--min-score` threshold to make a check pass. Ask me.

That last rule matters more than it looks. An agent under pressure to turn a red check green will happily loosen the check. Put the gate somewhere it can't reach, and say so in writing.

Why the OpenAPI spec and v3 collections matter

The OpenAPI spec is the contract and the first thing an agent reads. The v3 collection is the executable proof. In the git-native v3 format, a collection stops being one big collection.json and becomes a directory tree where every request, folder and saved example is its own YAML file:

postman/collections/
  Orders API/
    .resources/
      definition.yaml
    create order.resources/
      examples/
        201 Created.example.yaml
        409 Out of Stock.example.yaml
    create order.request.yaml
    get order.request.yaml
    cancel order.request.yaml

The payoff is cheap context. Claude reads the one request it needs, not an entire collection, so tokens go to the work instead of to loading JSON.

Score the spec for agent readiness

This is the step that makes the workflow AI-native instead of merely automated. The ai-readiness skill scores a spec (or collection) on whether an agent can discover it, understand it, call it correctly, and recover from errors. Missing examples, undocumented errors and ambiguous parameters all cost points.

Point it at an API you already have:

Run the AI-readiness check on openapi.yaml. Report the score, bucket, and confidence exactly as the command printed them, then list the three changes that would raise the score the most. Apply them, and run it again.

The score lands in one of four buckets (Limited, Fair, Good, Excellent), along with a confidence value for how many signals it could measure. Ask Claude to quote what the command printed rather than paraphrase it. A paraphrased 82 has a way of becoming a "roughly 80."

To see the feedback loop, break the spec on purpose: delete a documented error response and rerun the check. The score should drop, and the recommendation should point at the missing error.

CI as the gate the agent can't edit

For the gate itself, skip the model and run the Postman CLI directly in CI. A deterministic check can't be talked out of failing.

name: API gate
on: pull_request
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g postman-cli
      - run: postman spec lint openapi.yaml -f error
      - run: postman collection run "postman/collections/Orders API" --use-mock
      - run: postman spec ai-readiness openapi.yaml --min-score 80

The 80 here is only an example. Pick a threshold your spec clears today, then raise it as you improve. --use-mock needs a recent Postman CLI, so run postman collection run -h on your version before relying on it.

Things to watch for

• Run -h before trusting a flag. Flags change between CLI versions. That includes the ones in this post.
• Check what gets reported. Some Postman CLI commands send run results and analytics to Postman by default. The plugin README lists which ones and how to opt out with --no-report-events.
• Mocks are not the service. A green run against a mock proves your tests match your contract. It says nothing about your implementation until you point the same collection at it.
• Don't let the agent push to your workspace. Push from CI after merge instead.

Where to start

1. Install the plugin with the two commands above.
2. Score the spec of an API you already have.
3. Read the recommendations and fix the top three.
4. Put the gate in CI and the rule in CLAUDE.md.

The full guide also builds an orders API end to end: contract-first design in plan mode, failure-path mocks, tests, lint hooks, a reviewer subagent and bounded /goal loops. Read the full hands-on guide on the Postman blog.

What did your spec score, and which recommendation surprised you? I'm curious which gaps show up most often.