mirror of
https://github.com/Postman-Devrel/postman-claude-code-plugin.git
synced 2026-04-16 02:02:42 +00:00
add postman cli workflow skills
This commit is contained in:
nnandan-postman
66
CLAUDE.md
Normal file
66
CLAUDE.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## What This Is
|
||||
|
||||
The Postman Plugin for Claude Code — a pure-markdown, configuration-driven plugin that provides full API lifecycle management via the Postman MCP Server. No compiled code, no runtime dependencies, no build step.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
.claude-plugin/plugin.json # Plugin manifest (name, version, metadata)
|
||||
.mcp.json # MCP server auto-config (Postman MCP at mcp.postman.com)
|
||||
commands/*.md # 11 slash commands (/postman:<name>)
|
||||
skills/*/SKILL.md # 7 skills (routing, knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection)
|
||||
agents/readiness-analyzer.md # Sub-agent for API readiness analysis
|
||||
examples/ # Sample output (readiness report)
|
||||
assets/ # GIFs for README
|
||||
```
|
||||
|
||||
## How the Plugin Works
|
||||
|
||||
- Claude Code discovers components via `.claude-plugin/plugin.json` manifest
|
||||
- `.mcp.json` auto-configures the Postman MCP server, providing `mcp__postman__*` tools (111 tools)
|
||||
- MCP commands use the cloud Postman MCP Server — requires `POSTMAN_API_KEY` environment variable
|
||||
- CLI commands use the locally installed Postman CLI (`npm install -g postman-cli`) — requires `postman login`
|
||||
- Plugin is loaded with `claude --plugin-dir /path/to/postman-claude-code-plugin`
|
||||
|
||||
## Component Conventions
|
||||
|
||||
**Commands** (`commands/*.md`): YAML front matter with `description` and `allowed-tools`. Each defines a structured workflow invoked as `/postman:<name>`.
|
||||
- MCP commands: setup, sync, codegen, search, test, mock, docs, security
|
||||
- CLI commands: request, generate-spec, run-collection
|
||||
|
||||
**Skills** (`skills/*/SKILL.md`): YAML front matter with `name`, `description`, `user-invocable`. Auto-injected context, not directly invoked. `postman-routing` routes requests to commands; `postman-knowledge` provides MCP tool guidance; `agent-ready-apis` provides readiness criteria; `postman-cli` provides CLI and git sync file structure knowledge.
|
||||
|
||||
**Agent** (`agents/readiness-analyzer.md`): YAML front matter with `name`, `description`, `model`, `allowed-tools`. Runs as a sub-agent (sonnet model) for deep API readiness analysis (8 pillars, 48 checks).
|
||||
|
||||
## Key MCP Limitations
|
||||
|
||||
These are documented in `skills/postman-knowledge/mcp-limitations.md` and must be respected in all commands:
|
||||
|
||||
- `searchPostmanElements` searches PUBLIC network only — use `getWorkspaces` + `getCollections` for private content
|
||||
- `generateCollection` and `syncCollectionWithSpec` return HTTP 202 — must poll for completion
|
||||
- `syncCollectionWithSpec` supports OpenAPI 3.0 only — use `updateSpecFile` + `generateCollection` for Swagger 2.0 or OpenAPI 3.1
|
||||
- `createCollection` creates flat collections — nest via `createCollectionFolder` + `createCollectionRequest`
|
||||
- `createSpec` struggles with specs >50KB — decompose into collection items instead
|
||||
|
||||
## Postman CLI Commands
|
||||
|
||||
Three commands use the Postman CLI instead of MCP. They require `postman-cli` installed locally (`npm install -g postman-cli`) and authenticated (`postman login`). If CLI is not found, show install instructions and stop.
|
||||
|
||||
- `/postman:request` — Send HTTP requests via `postman request <METHOD> <URL>`
|
||||
- `/postman:generate-spec` — Scan code for API routes, generate OpenAPI 3.0 YAML, validate with `postman spec lint`
|
||||
- `/postman:run-collection` — Run collection tests via `postman collection run <id>` using cloud IDs from `.postman/resources.yaml`
|
||||
|
||||
CLI commands work with Postman's git sync structure: `postman/collections/` (v3 folder format), `postman/environments/`, `postman/specs/`, and `.postman/resources.yaml` for cloud ID mapping.
|
||||
|
||||
## Development Notes
|
||||
|
||||
- There is no build, lint, or test suite — all "code" is instructional markdown
|
||||
- Changes are purely editing markdown files with YAML front matter
|
||||
- When adding a new command, follow the existing front matter pattern in `commands/`
|
||||
- When adding a new skill, create `skills/<name>/SKILL.md` with proper front matter
|
||||
- The `allowed-tools` field in front matter controls what tools a command/agent can use
|
||||
- CLI commands need `Bash` in `allowed-tools`; MCP commands need `mcp__postman__*`
|
||||
55
commands/generate-spec.md
Normal file
55
commands/generate-spec.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
description: Generate or update an OpenAPI spec from your codebase
|
||||
---
|
||||
|
||||
Generate or update an OpenAPI 3.0 specification by analyzing API routes in your codebase.
|
||||
|
||||
## Step 1: Check for Existing Spec
|
||||
|
||||
```bash
|
||||
ls postman/specs/**/*.yaml postman/specs/**/*.yml postman/specs/**/*.json 2>/dev/null
|
||||
ls openapi.yaml openapi.yml swagger.yaml swagger.yml 2>/dev/null
|
||||
```
|
||||
|
||||
If a spec exists, read it to understand current state. You'll update it rather than replace it.
|
||||
|
||||
## Step 2: Discover API Endpoints
|
||||
|
||||
Scan the project for route definitions based on the framework:
|
||||
|
||||
- **Express/Node**: `app.get()`, `router.post()`, `@Get()` (NestJS)
|
||||
- **Python**: `@app.route()`, `@router.get()` (FastAPI), `path()` (Django)
|
||||
- **Go**: `http.HandleFunc()`, `r.GET()` (Gin/Echo)
|
||||
- **Java**: `@GetMapping`, `@PostMapping`, `@RequestMapping`
|
||||
- **Ruby**: `get`, `post`, `resources` in routes.rb
|
||||
|
||||
Read the route files and extract: methods, paths, parameters, request bodies, response schemas, auth requirements.
|
||||
|
||||
## Step 3: Generate or Update the Spec
|
||||
|
||||
Write a valid OpenAPI 3.0.3 YAML spec including:
|
||||
- `info` with title, version, description
|
||||
- `servers` with local dev URL
|
||||
- `paths` with all discovered endpoints
|
||||
- `components/schemas` with models derived from code (types, models, structs)
|
||||
- `components/securitySchemes` if auth is used
|
||||
|
||||
**When updating**: Add new endpoints, update changed ones, remove endpoints no longer in code. Preserve existing descriptions and examples.
|
||||
|
||||
**When creating**: Write to `postman/specs/openapi.yaml`.
|
||||
|
||||
## Step 4: Validate
|
||||
|
||||
```bash
|
||||
postman spec lint ./postman/specs/openapi.yaml
|
||||
```
|
||||
|
||||
Fix any validation errors and re-run until clean.
|
||||
|
||||
## Step 5: Report
|
||||
|
||||
Show what was created or changed:
|
||||
- Endpoints documented (count and list)
|
||||
- Schemas defined
|
||||
- Changes from previous spec (if updating)
|
||||
- Validation result
|
||||
55
commands/run-collection.md
Normal file
55
commands/run-collection.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
description: Run Postman collection tests using the CLI
|
||||
---
|
||||
|
||||
Run Postman collection tests to verify your API endpoints.
|
||||
|
||||
## Step 1: Find Collections and IDs
|
||||
|
||||
List collection folders and look up their cloud IDs:
|
||||
|
||||
```bash
|
||||
ls postman/collections/
|
||||
cat .postman/resources.yaml
|
||||
```
|
||||
|
||||
The `cloudResources.collections` section maps local collection paths to cloud IDs.
|
||||
|
||||
If no collections found, tell the user and stop.
|
||||
If one collection, use it directly.
|
||||
If multiple, list them and ask which to run.
|
||||
|
||||
## Step 2: Run the Collection
|
||||
|
||||
Run by **collection ID** (from `.postman/resources.yaml`):
|
||||
|
||||
```bash
|
||||
postman collection run <collection-id>
|
||||
```
|
||||
|
||||
Common options:
|
||||
```bash
|
||||
# Stop on first failure
|
||||
postman collection run <collection-id> --bail
|
||||
|
||||
# With request timeout
|
||||
postman collection run <collection-id> --timeout-request 10000
|
||||
|
||||
# With environment
|
||||
postman collection run <collection-id> -e ./postman/environments/<env-file>.json
|
||||
|
||||
# Override environment variable
|
||||
postman collection run <collection-id> --env-var "base_url=http://localhost:3000"
|
||||
```
|
||||
|
||||
## Step 3: Parse and Report Results
|
||||
|
||||
Parse the CLI output for pass/fail counts, failed test names, error messages, and status codes.
|
||||
|
||||
## Step 4: Handle Failures
|
||||
|
||||
If tests fail:
|
||||
1. Analyze error messages
|
||||
2. Read relevant source code
|
||||
3. Suggest fixes
|
||||
4. After fixes, re-run to verify
|
||||
33
commands/send-request.md
Normal file
33
commands/send-request.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
description: Send HTTP requests using Postman CLI
|
||||
---
|
||||
|
||||
Send an HTTP request using the Postman CLI. Ask the user what URL and method they want, or detect it from context.
|
||||
|
||||
## Step 1: Determine Request Details
|
||||
|
||||
Ask the user for:
|
||||
- URL to send the request to
|
||||
- HTTP method (default: GET)
|
||||
- Any headers, body, or auth needed
|
||||
|
||||
If the user wants to send a request from a collection, find collection folders in `postman/collections/` and read the `*.request.yaml` files to extract method and URL. Collections use the v3 folder format.
|
||||
|
||||
## Step 2: Build and Execute
|
||||
|
||||
```bash
|
||||
postman request <METHOD> "<URL>"
|
||||
```
|
||||
|
||||
**With headers:** add `-H "Header: value"`
|
||||
**With body:** add `-d '{"key": "value"}'`
|
||||
**With bearer auth:** add `--auth-bearer-token "<token>"`
|
||||
**With API key:** add `--auth-apikey-key "<name>" --auth-apikey-value "<key>"`
|
||||
**With basic auth:** add `--auth-basic-username "<user>" --auth-basic-password "<pass>"`
|
||||
**With environment:** add `-e ./postman/environments/<file>.json`
|
||||
|
||||
Always show the exact command before running it.
|
||||
|
||||
## Step 3: Report Results
|
||||
|
||||
Parse the response and report status code, response time, and body. Suggest fixes for errors (auth issues, connection problems, invalid URLs).
|
||||
340
skills/generate-spec/SKILL.md
Normal file
340
skills/generate-spec/SKILL.md
Normal file
@@ -0,0 +1,340 @@
|
||||
---
|
||||
name: generate-spec
|
||||
description: Generate or update an OpenAPI specification from code - use when user says "generate spec", "create spec", "create openapi spec", "update spec", "generate API documentation", "create API definition", "write openapi", "document my API", "create swagger", or wants to create/update an API specification from their codebase
|
||||
---
|
||||
|
||||
You are an API specification assistant that generates and updates OpenAPI 3.0 specifications by analyzing the user's codebase.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Trigger this skill when:
|
||||
- User asks to "generate a spec" or "create an OpenAPI spec"
|
||||
- User wants to "document my API" or "create API documentation"
|
||||
- User says "update the spec" or "sync spec with code"
|
||||
- User asks to "create a swagger file" or "write an API definition"
|
||||
- User wants to generate an API spec from their existing routes/endpoints
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Discover API Endpoints in the Codebase
|
||||
|
||||
Scan the project for API route definitions. Check common patterns by framework:
|
||||
|
||||
**Express.js / Node.js:**
|
||||
```bash
|
||||
# Find route files
|
||||
find . -type f \( -name "*.js" -o -name "*.ts" \) -not -path "*/node_modules/*" | head -30
|
||||
```
|
||||
Look for: `app.get()`, `app.post()`, `router.get()`, `router.post()`, `@Get()`, `@Post()` (NestJS)
|
||||
|
||||
**Python (Flask/Django/FastAPI):**
|
||||
```bash
|
||||
find . -type f -name "*.py" -not -path "*/.venv/*" -not -path "*/venv/*" | head -30
|
||||
```
|
||||
Look for: `@app.route()`, `@router.get()`, `path()`, `url()`, `@app.get()` (FastAPI)
|
||||
|
||||
**Go:**
|
||||
```bash
|
||||
find . -type f -name "*.go" -not -path "*/vendor/*" | head -30
|
||||
```
|
||||
Look for: `http.HandleFunc()`, `r.GET()`, `e.GET()` (Echo), `router.Handle()`
|
||||
|
||||
**Java (Spring):**
|
||||
```bash
|
||||
find . -type f -name "*.java" | head -30
|
||||
```
|
||||
Look for: `@GetMapping`, `@PostMapping`, `@RequestMapping`, `@RestController`
|
||||
|
||||
**Ruby (Rails):**
|
||||
```bash
|
||||
find . -type f -name "routes.rb" -o -name "*controller*.rb" | head -20
|
||||
```
|
||||
Look for: `get`, `post`, `resources`, `namespace`
|
||||
|
||||
Read the relevant source files to extract:
|
||||
- HTTP methods (GET, POST, PUT, PATCH, DELETE)
|
||||
- URL paths and path parameters
|
||||
- Query parameters
|
||||
- Request body schemas (from validation, types, or models)
|
||||
- Response schemas (from return types, serializers, or examples)
|
||||
- Authentication requirements
|
||||
- Status codes
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Check for Existing Spec
|
||||
|
||||
Look for an existing OpenAPI spec to update:
|
||||
|
||||
```bash
|
||||
# Check Postman specs directory
|
||||
ls postman/specs/**/*.yaml postman/specs/**/*.yml postman/specs/**/*.json 2>/dev/null
|
||||
|
||||
# Check common root locations
|
||||
ls openapi.yaml openapi.yml openapi.json swagger.yaml swagger.yml swagger.json api-spec.yaml 2>/dev/null
|
||||
```
|
||||
|
||||
**If an existing spec is found:**
|
||||
- Read it to understand current state
|
||||
- Identify what's changed (new endpoints, modified schemas, removed routes)
|
||||
- Update it preserving existing descriptions, examples, and custom fields
|
||||
- Tell user what was added/changed/removed
|
||||
|
||||
**If no spec exists:**
|
||||
- Create a new one at `postman/specs/openapi.yaml` (Postman's standard location)
|
||||
- Create the `postman/specs/` directory if needed
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Generate the OpenAPI 3.0 Spec
|
||||
|
||||
Build a valid OpenAPI 3.0 specification in YAML format. Follow this structure:
|
||||
|
||||
```yaml
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: <API name from package.json, pyproject.toml, or project name>
|
||||
version: <version from package.json or "1.0.0">
|
||||
description: <brief description of the API>
|
||||
servers:
|
||||
- url: http://localhost:<port>
|
||||
description: Local development server
|
||||
paths:
|
||||
/endpoint:
|
||||
get:
|
||||
summary: <short description>
|
||||
description: <detailed description>
|
||||
operationId: <unique camelCase identifier>
|
||||
tags:
|
||||
- <group name>
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: <parameter description>
|
||||
responses:
|
||||
"200":
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ModelName"
|
||||
"400":
|
||||
description: Bad request
|
||||
"401":
|
||||
description: Unauthorized
|
||||
"404":
|
||||
description: Not found
|
||||
"500":
|
||||
description: Internal server error
|
||||
post:
|
||||
summary: <short description>
|
||||
operationId: <unique camelCase identifier>
|
||||
tags:
|
||||
- <group name>
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/CreateModel"
|
||||
responses:
|
||||
"201":
|
||||
description: Created successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ModelName"
|
||||
components:
|
||||
schemas:
|
||||
ModelName:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Unique identifier
|
||||
name:
|
||||
type: string
|
||||
description: Display name
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
apiKey:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: X-API-Key
|
||||
```
|
||||
|
||||
### Key rules for generating the spec:
|
||||
|
||||
1. **Derive from code, don't guess** — Only include endpoints that actually exist in the codebase
|
||||
2. **Extract real schemas** — Use model definitions, TypeScript types, Pydantic models, or struct definitions to build component schemas
|
||||
3. **Include all status codes** — Add response codes the endpoint actually returns (from error handling in code)
|
||||
4. **Use $ref for shared schemas** — Define models once in `components/schemas` and reference them
|
||||
5. **Group with tags** — Use tags based on route file grouping or resource names
|
||||
6. **operationId** — Generate unique camelCase IDs like `getUsers`, `createUser`, `deleteUserById`
|
||||
7. **Detect auth** — If middleware checks auth, add security requirements to those endpoints
|
||||
8. **Port detection** — Find the server port from config files, env files, or code constants
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Write the Spec File
|
||||
|
||||
Write the spec to the appropriate location:
|
||||
|
||||
- **If updating**: Write to the existing spec file path
|
||||
- **If creating new**: Write to `postman/specs/openapi.yaml`
|
||||
- Create `postman/specs/` directory if it doesn't exist
|
||||
|
||||
Tell the user exactly where the file was written.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Validate the Spec with Postman CLI
|
||||
|
||||
**Always validate using the Postman CLI.** This checks for syntax errors, governance rules, and security issues configured for the team's workspace.
|
||||
|
||||
**Basic lint:**
|
||||
```bash
|
||||
postman spec lint ./postman/specs/openapi.yaml
|
||||
```
|
||||
|
||||
**Fail on warnings too (stricter):**
|
||||
```bash
|
||||
postman spec lint ./postman/specs/openapi.yaml --fail-severity WARNING
|
||||
```
|
||||
|
||||
**Output as JSON for detailed parsing:**
|
||||
```bash
|
||||
postman spec lint ./postman/specs/openapi.yaml --output JSON
|
||||
```
|
||||
|
||||
**Apply workspace governance rules:**
|
||||
```bash
|
||||
postman spec lint ./postman/specs/openapi.yaml --workspace-id <workspace-id>
|
||||
```
|
||||
|
||||
If the workspace ID is available in `.postman/resources.yaml`, use it to apply the team's governance rules.
|
||||
|
||||
**Fix-and-relint loop:**
|
||||
1. Run `postman spec lint`
|
||||
2. Parse the error/warning output (line numbers, severity, descriptions)
|
||||
3. Fix every issue in the spec
|
||||
4. Re-run `postman spec lint` until clean — no errors AND no warnings
|
||||
5. Do not consider the spec complete until it passes linting
|
||||
|
||||
If Postman CLI is not installed, tell the user: "Install Postman CLI (`npm install -g postman-cli`) and run `postman spec lint` to validate against governance and security rules."
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Report Results
|
||||
|
||||
**New spec created:**
|
||||
```
|
||||
Created OpenAPI 3.0 spec at postman/specs/openapi.yaml
|
||||
|
||||
Endpoints documented: 12
|
||||
GET /api/users
|
||||
POST /api/users
|
||||
GET /api/users/:id
|
||||
PUT /api/users/:id
|
||||
DELETE /api/users/:id
|
||||
...
|
||||
|
||||
Schemas defined: 5
|
||||
User, CreateUser, UpdateUser, ErrorResponse, PaginatedResponse
|
||||
|
||||
Validation: ✓ No errors
|
||||
```
|
||||
|
||||
**Existing spec updated:**
|
||||
```
|
||||
Updated OpenAPI spec at postman/specs/openapi.yaml
|
||||
|
||||
Changes:
|
||||
Added: POST /api/orders, GET /api/orders/:id
|
||||
Updated: GET /api/users (added query parameters)
|
||||
Removed: DELETE /api/legacy/cleanup (endpoint no longer exists)
|
||||
|
||||
New schemas: Order, CreateOrder
|
||||
Validation: ✓ No errors
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Generate spec from scratch
|
||||
```
|
||||
User: "generate an openapi spec for my API"
|
||||
|
||||
You:
|
||||
1. Scan project for route definitions
|
||||
2. Read route files and extract endpoints
|
||||
3. Read models/types for schemas
|
||||
4. Generate openapi.yaml
|
||||
5. Validate with postman spec lint
|
||||
6. Report: "Created spec with 12 endpoints and 5 schemas"
|
||||
```
|
||||
|
||||
### Update spec after code changes
|
||||
```
|
||||
User: "update the spec, I added new endpoints"
|
||||
|
||||
You:
|
||||
1. Read existing spec
|
||||
2. Scan code for all current endpoints
|
||||
3. Diff against existing spec
|
||||
4. Add new endpoints, update changed ones
|
||||
5. Validate
|
||||
6. Report: "Added 2 new endpoints, updated 1"
|
||||
```
|
||||
|
||||
### Generate spec for specific routes
|
||||
```
|
||||
User: "create a spec for the user routes"
|
||||
|
||||
You:
|
||||
1. Find user-related route files
|
||||
2. Extract only user endpoints
|
||||
3. Generate focused spec
|
||||
4. Validate and report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**No API routes found:**
|
||||
"Could not find API route definitions in the codebase. What framework are you using? Point me to the files containing your route definitions."
|
||||
|
||||
**Unsupported framework:**
|
||||
"I couldn't auto-detect the framework. Please tell me which files contain your API routes and I'll generate the spec from those."
|
||||
|
||||
**Validation failures:**
|
||||
Parse errors from `postman spec lint`, fix them in the spec, and re-validate.
|
||||
|
||||
**CLI not installed (for validation):**
|
||||
"Spec created successfully. Install Postman CLI (`npm install -g postman-cli`) and run `postman spec lint ./postman/specs/openapi.yaml` to validate."
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
- Always generate OpenAPI 3.0.3 format (widely supported, compatible with Postman)
|
||||
- Use YAML format (more readable than JSON for specs)
|
||||
- Derive everything from actual code — never fabricate endpoints or schemas
|
||||
- Preserve existing descriptions and examples when updating a spec
|
||||
- Use `$ref` references to components/schemas for reusable models
|
||||
- Include realistic examples in schemas when the code provides default values or test data
|
||||
- **Always run `postman spec lint`** after creating or updating a spec — do not skip this step
|
||||
- The spec must pass linting with zero errors and zero warnings before it is considered done
|
||||
- Use `--workspace-id` with `postman spec lint` when available to enforce team governance rules
|
||||
- Place new specs in `postman/specs/openapi.yaml` to align with Postman's git sync structure
|
||||
97
skills/postman-cli/SKILL.md
Normal file
97
skills/postman-cli/SKILL.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
name: postman-cli
|
||||
description: Postman CLI reference and git sync file structure knowledge - provides context for CLI-based commands (send-request, generate-spec, run-collection)
|
||||
---
|
||||
|
||||
Reference knowledge for the Postman CLI and git sync file structure. This skill provides context used by the CLI commands.
|
||||
|
||||
## Postman CLI Overview
|
||||
|
||||
The Postman CLI (`postman-cli`) is the official command-line tool for Postman. It runs collections, validates API specs, sends requests, and integrates with CI/CD pipelines.
|
||||
|
||||
### Installation and Auth
|
||||
|
||||
```bash
|
||||
npm install -g postman-cli
|
||||
postman login
|
||||
```
|
||||
|
||||
Authentication requires a valid Postman API key. Run `postman login` and follow the prompts.
|
||||
|
||||
### Core Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `postman collection run <id>` | Run collection tests by cloud ID |
|
||||
| `postman request <METHOD> <URL>` | Send an HTTP request |
|
||||
| `postman spec lint <file>` | Validate an OpenAPI spec |
|
||||
| `postman login` | Authenticate with Postman |
|
||||
|
||||
---
|
||||
|
||||
## Git Sync File Structure
|
||||
|
||||
When a Postman workspace is connected to a git repo, it syncs using this structure:
|
||||
|
||||
```
|
||||
project-root/
|
||||
├── .postman/
|
||||
│ └── resources.yaml # Maps local paths → cloud IDs
|
||||
├── postman/
|
||||
│ ├── collections/
|
||||
│ │ └── My API/ # Collection (v3 folder format)
|
||||
│ │ ├── .resources/
|
||||
│ │ │ └── definition.yaml # schemaVersion: "3.0", name
|
||||
│ │ ├── Get Users.request.yaml
|
||||
│ │ ├── Create User.request.yaml
|
||||
│ │ └── Auth/ # Subfolder
|
||||
│ │ └── Login.request.yaml
|
||||
│ ├── environments/
|
||||
│ │ └── dev.postman_environment.json
|
||||
│ └── specs/
|
||||
│ └── openapi.yaml
|
||||
```
|
||||
|
||||
### resources.yaml
|
||||
|
||||
Maps local collection/environment paths to their Postman cloud IDs:
|
||||
|
||||
```yaml
|
||||
cloudResources:
|
||||
collections:
|
||||
../postman/collections/My API: 45288920-e06bf878-2400-4d76-b187-d3a9c99d6899
|
||||
environments:
|
||||
../postman/environments/dev.postman_environment.json: 45288920-abc12345-...
|
||||
```
|
||||
|
||||
### Collection v3 Folder Format
|
||||
|
||||
Each collection is a **directory** (not a single JSON file). It contains:
|
||||
- `.resources/definition.yaml` — collection metadata
|
||||
- `*.request.yaml` — individual request files
|
||||
- Subdirectories for folders within the collection
|
||||
|
||||
Request files contain:
|
||||
```yaml
|
||||
$kind: http-request
|
||||
url: https://api.example.com/users
|
||||
method: GET
|
||||
order: 1000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Postman CLI vs Newman
|
||||
|
||||
The Postman CLI is the **official replacement** for Newman:
|
||||
|
||||
| Feature | Postman CLI | Newman |
|
||||
|---------|-------------|---------|
|
||||
| Maintenance | Official Postman support | Community-driven |
|
||||
| Security | Digitally signed binary | Open-source |
|
||||
| Governance | Enterprise API governance | Not available |
|
||||
| Auth | Postman API key | No authentication |
|
||||
| Spec linting | Built-in | Not available |
|
||||
| HTTP requests | `postman request` command | Not available |
|
||||
|
||||
Always use `postman-cli`, never Newman.
|
||||
@@ -21,6 +21,9 @@ When the user's request involves Postman or APIs, route to the appropriate comma
|
||||
| Generate docs, improve documentation, publish docs | `/postman:docs` | Analyzes completeness, fills gaps, can publish to Postman |
|
||||
| Security audit, check for vulnerabilities, OWASP | `/postman:security` | 20+ security checks with severity scoring and remediation |
|
||||
| Set up Postman, configure API key, first-time setup | `/postman:setup` | Guided setup with workspace verification |
|
||||
| Send a request, test endpoint, hit the API, call URL | `/postman:send-request` | CLI-based HTTP requests with auth, headers, body support |
|
||||
| Generate spec, create OpenAPI, document my API | `/postman:generate-spec` | Scans code for routes, generates OpenAPI YAML, validates with lint |
|
||||
| Run collection tests, verify changes, check if tests pass | `/postman:run-collection` | Runs collection by cloud ID, parses results, suggests fixes |
|
||||
| Is my API agent-ready?, scan my API, analyze my spec | **readiness-analyzer agent** | 48 checks across 8 pillars, scoring and fix recommendations |
|
||||
|
||||
## Routing Rules
|
||||
|
||||
208
skills/run-collection/SKILL.md
Normal file
208
skills/run-collection/SKILL.md
Normal file
@@ -0,0 +1,208 @@
|
||||
---
|
||||
name: run-collection
|
||||
description: Run Postman collection tests using Postman CLI - use when user says "run tests", "run collection", "run my postman tests", "verify changes", "check if tests pass", or wants to execute API test suites after code changes
|
||||
---
|
||||
|
||||
You are an API testing assistant that runs Postman collection tests using the Postman CLI.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Trigger this skill when:
|
||||
- User asks to "run tests" or "run my collection"
|
||||
- User wants to "verify changes" or "check if tests pass"
|
||||
- User says "run postman tests" or "execute collection"
|
||||
- After code changes that may affect API behavior
|
||||
- User wants to validate their API endpoints work correctly
|
||||
|
||||
---
|
||||
|
||||
## Understanding the Collection Format
|
||||
|
||||
Postman collections synced via git use the **v3 folder format**:
|
||||
|
||||
```
|
||||
postman/collections/
|
||||
├── My API Tests/ # Collection folder (folder name = collection name)
|
||||
│ ├── .resources/
|
||||
│ │ └── definition.yaml # Collection metadata (schemaVersion: "3.0", name)
|
||||
│ ├── Get Users.request.yaml # Individual request files
|
||||
│ ├── Create User.request.yaml
|
||||
│ └── Auth/ # Subfolder for grouped requests
|
||||
│ └── Login.request.yaml
|
||||
```
|
||||
|
||||
The `.postman/resources.yaml` file maps local collection folders to their cloud IDs:
|
||||
|
||||
```yaml
|
||||
cloudResources:
|
||||
collections:
|
||||
../postman/collections/My API Tests: 45288920-e06bf878-2400-4d76-b187-d3a9c99d6899
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Find Collections and Their IDs
|
||||
|
||||
1. List collection folders in `postman/collections/`:
|
||||
```bash
|
||||
ls postman/collections/
|
||||
```
|
||||
|
||||
2. Read `.postman/resources.yaml` to get the cloud ID for each collection:
|
||||
```bash
|
||||
cat .postman/resources.yaml
|
||||
```
|
||||
|
||||
The `cloudResources.collections` section maps local paths to collection IDs. Match the collection folder name to get its ID.
|
||||
|
||||
**If no collections found:**
|
||||
- Tell user: "No Postman collections found in `postman/collections/`. Connect your repo to a Postman workspace to sync collections."
|
||||
- Stop here
|
||||
|
||||
**If no ID found in resources.yaml:**
|
||||
- Tell user the collection exists locally but has no cloud ID mapped — they may need to sync with Postman
|
||||
|
||||
**If one collection found:**
|
||||
- Use it directly, tell user which collection you're running
|
||||
|
||||
**If multiple collections found:**
|
||||
- List them and ask user which one to run
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Run the Collection
|
||||
|
||||
The Postman CLI runs collections by **collection ID**:
|
||||
|
||||
```bash
|
||||
postman collection run <collection-id>
|
||||
```
|
||||
|
||||
For example:
|
||||
```bash
|
||||
postman collection run 45288920-e06bf878-2400-4d76-b187-d3a9c99d6899
|
||||
```
|
||||
|
||||
**With environment:**
|
||||
```bash
|
||||
postman collection run <collection-id> \
|
||||
-e ./postman/environments/<env-file>.json
|
||||
```
|
||||
|
||||
**With options:**
|
||||
```bash
|
||||
# Stop on first failure
|
||||
postman collection run <collection-id> --bail
|
||||
|
||||
# With request timeout
|
||||
postman collection run <collection-id> --timeout-request 10000
|
||||
|
||||
# Override environment variables
|
||||
postman collection run <collection-id> \
|
||||
--env-var "base_url=http://localhost:3000"
|
||||
|
||||
# Run specific folder or request within collection
|
||||
postman collection run <collection-id> -i <folder-or-request-uid>
|
||||
```
|
||||
|
||||
Always show the exact command being executed before running it.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Check for Environment Files
|
||||
|
||||
Look for environment files (do NOT add `-e` flag unless one exists):
|
||||
|
||||
```bash
|
||||
ls postman/environments/ 2>/dev/null
|
||||
```
|
||||
|
||||
- If environment files exist, ask user if they want to use one
|
||||
- If no environment files, proceed without `-e` flag
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Parse and Report Results
|
||||
|
||||
### Successful run (all tests pass)
|
||||
```
|
||||
All tests passed
|
||||
|
||||
Collection: My API Tests
|
||||
Results: 47/47 assertions passed
|
||||
Requests: 10 executed, 0 failed
|
||||
Duration: 2.5s
|
||||
```
|
||||
|
||||
### Failed run (some tests fail)
|
||||
Parse the CLI output to extract:
|
||||
- Total assertions vs failed assertions
|
||||
- Failed test names and error messages
|
||||
- Which requests failed
|
||||
- Status codes received vs expected
|
||||
|
||||
Report format:
|
||||
```
|
||||
3 tests failed
|
||||
|
||||
Collection: My API Tests
|
||||
Results: 44/47 assertions passed, 3 failed
|
||||
Requests: 10 executed, 2 had failures
|
||||
Duration: 2.5s
|
||||
|
||||
Failures:
|
||||
1. "Status code is 200" — POST /api/users
|
||||
Expected 200, got 500
|
||||
|
||||
2. "Response has user ID" — POST /api/users
|
||||
Property 'id' not found in response
|
||||
|
||||
3. "Response time < 1000ms" — GET /api/products
|
||||
Response time was 1245ms
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Analyze Failures and Fix
|
||||
|
||||
When tests fail:
|
||||
|
||||
1. **Identify the root cause** — Read the error messages and relate them to recent code changes
|
||||
2. **Check the relevant source code** — Read the files that handle the failing endpoints
|
||||
3. **Suggest specific fixes** — Propose code changes to fix the failures
|
||||
4. **Apply fixes** (with user approval)
|
||||
5. **Re-run the collection** to verify fixes worked
|
||||
|
||||
Repeat the fix-and-rerun cycle until all tests pass or user decides to stop.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**CLI not installed:**
|
||||
"Postman CLI is not installed. Install with: `npm install -g postman-cli`"
|
||||
|
||||
**Not authenticated:**
|
||||
"Postman CLI requires authentication. Run: `postman login`"
|
||||
|
||||
**Collection not found:**
|
||||
"Collection not found. Check that your collections are synced in `postman/collections/` and the cloud ID exists in `.postman/resources.yaml`."
|
||||
|
||||
**Server not running:**
|
||||
"Requests are failing with connection errors. Make sure your local server is running."
|
||||
|
||||
**Timeout:**
|
||||
"Requests are timing out. Check server performance or increase timeout with `--timeout-request`."
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
- Collections use the **v3 folder format** — each collection is a directory, not a single JSON file
|
||||
- Run collections by **ID** using `postman collection run <collection-id>`
|
||||
- Get the collection ID from `.postman/resources.yaml` under `cloudResources.collections`
|
||||
- Always show the exact command being executed
|
||||
- Parse the CLI output to extract structured results (don't just dump raw output)
|
||||
- After failures, read the relevant source code before suggesting fixes
|
||||
- Do NOT add `-e` or `--environment` flags unless an environment file exists
|
||||
- Don't expose sensitive data from test output (tokens, passwords)
|
||||
175
skills/send-request/SKILL.md
Normal file
175
skills/send-request/SKILL.md
Normal file
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: send-request
|
||||
description: Send HTTP requests using Postman CLI - use when user says "send request", "test endpoint", "call API", "hit the endpoint", "make a request", "try the API", or wants to quickly test an HTTP endpoint
|
||||
---
|
||||
|
||||
You are an API testing assistant that helps send HTTP requests using the Postman CLI.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Trigger this skill when:
|
||||
- User asks to "send a request" or "make a request"
|
||||
- User wants to "test an endpoint" or "hit the API"
|
||||
- User says "call the API" or "try the endpoint"
|
||||
- User wants to verify an endpoint is working
|
||||
- User asks to test a specific URL
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Determine Request Details
|
||||
|
||||
**If user provides a URL directly:**
|
||||
- Extract method (default to GET if not specified)
|
||||
- Extract URL
|
||||
- Note any headers, body, or auth mentioned
|
||||
|
||||
**If user wants to send a request from a collection:**
|
||||
|
||||
Collections use the **v3 folder format** — each collection is a directory containing `*.request.yaml` files:
|
||||
|
||||
```
|
||||
postman/collections/
|
||||
├── My API/
|
||||
│ ├── .resources/
|
||||
│ │ └── definition.yaml # schemaVersion: "3.0", name
|
||||
│ ├── Get Users.request.yaml # method: GET, url: https://...
|
||||
│ ├── Create User.request.yaml
|
||||
│ └── Auth/
|
||||
│ └── Login.request.yaml
|
||||
```
|
||||
|
||||
Each `*.request.yaml` contains:
|
||||
```yaml
|
||||
$kind: http-request
|
||||
url: https://api.example.com/users
|
||||
method: GET
|
||||
order: 1000
|
||||
```
|
||||
|
||||
To find requests from collections:
|
||||
1. List collection folders in `postman/collections/`
|
||||
2. Read the `*.request.yaml` files to find available requests
|
||||
3. Extract `method` and `url` from the matching request file
|
||||
4. Ask user which request to send (if multiple match)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Build the Command
|
||||
|
||||
**Basic request:**
|
||||
```bash
|
||||
postman request <METHOD> "<URL>"
|
||||
```
|
||||
|
||||
**With headers** (repeatable):
|
||||
```bash
|
||||
postman request <METHOD> "<URL>" \
|
||||
-H "Header-Name: value" \
|
||||
-H "Another-Header: value"
|
||||
```
|
||||
|
||||
**With body** (POST/PUT/PATCH):
|
||||
```bash
|
||||
# Inline JSON
|
||||
postman request <METHOD> "<URL>" -d '{"key": "value"}'
|
||||
|
||||
# From file
|
||||
postman request <METHOD> "<URL>" -d @body.json
|
||||
```
|
||||
|
||||
**With form data** (repeatable, supports file upload):
|
||||
```bash
|
||||
postman request <METHOD> "<URL>" \
|
||||
-f "field=value" \
|
||||
-f "file=@path/to/file.png"
|
||||
```
|
||||
|
||||
**With authentication:**
|
||||
```bash
|
||||
# Bearer token
|
||||
postman request <METHOD> "<URL>" --auth-bearer-token "<token>"
|
||||
|
||||
# API Key
|
||||
postman request <METHOD> "<URL>" --auth-apikey-key "X-API-Key" --auth-apikey-value "<key>"
|
||||
|
||||
# Basic auth
|
||||
postman request <METHOD> "<URL>" --auth-basic-username "<user>" --auth-basic-password "<pass>"
|
||||
```
|
||||
|
||||
**With environment:**
|
||||
```bash
|
||||
postman request <METHOD> "<URL>" \
|
||||
-e ./postman/environments/<env>.postman_environment.json
|
||||
```
|
||||
|
||||
**Additional options:**
|
||||
```bash
|
||||
# Retry on failure
|
||||
postman request <METHOD> "<URL>" --retry 3 --retry-delay 1000
|
||||
|
||||
# Custom timeout (default 300000ms)
|
||||
postman request <METHOD> "<URL>" --timeout 10000
|
||||
|
||||
# Save response to file
|
||||
postman request <METHOD> "<URL>" -o response.json
|
||||
|
||||
# Response body only (no metadata)
|
||||
postman request <METHOD> "<URL>" --response-only
|
||||
|
||||
# Verbose output (full request/response details)
|
||||
postman request <METHOD> "<URL>" --verbose
|
||||
|
||||
# Debug mode
|
||||
postman request <METHOD> "<URL>" --debug
|
||||
|
||||
# Redirect control
|
||||
postman request <METHOD> "<URL>" --redirects-max 5
|
||||
postman request <METHOD> "<URL>" --redirects-ignore
|
||||
|
||||
# Pre-request and post-response scripts
|
||||
postman request <METHOD> "<URL>" --script-pre-request @pre.js --script-post-request @post.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Execute the Request
|
||||
|
||||
Run the command and capture output. Always show the exact command being executed.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Parse and Report Results
|
||||
|
||||
Parse the response and report: status code, response time, and response body formatted for readability.
|
||||
|
||||
For errors (4xx/5xx), suggest fixes:
|
||||
- 401/403: Suggest adding auth headers
|
||||
- 404: Check URL path
|
||||
- 500: May be a backend issue
|
||||
- Connection refused: Check if server is running
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**CLI not installed:**
|
||||
"Postman CLI is not installed. Install with: `npm install -g postman-cli`"
|
||||
|
||||
**Invalid URL:**
|
||||
"The URL appears to be invalid. Please provide a valid HTTP/HTTPS URL."
|
||||
|
||||
**Connection refused:**
|
||||
"Could not connect to the server. Check if the server is running and the URL is correct."
|
||||
|
||||
**Timeout:**
|
||||
"Request timed out. The server may be slow or unreachable."
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
- Always show the exact command being executed
|
||||
- Parse and format the response for readability
|
||||
- Suggest fixes for common errors (auth issues, invalid URLs)
|
||||
- Collections use the v3 folder format — read `*.request.yaml` files to extract method and URL
|
||||
- Don't expose or log sensitive data like tokens in output
|
||||
Reference in New Issue
Block a user