postman-collection-skill

Generate Postman v2.1 collections from Laravel routes, OpenAPI specs, or manual endpoint lists. Usable three ways:

1. AI skill — drop into Claude Code, Codex, OpenCode, or any LLM coding agent. The agent uses templates + scripts instead of writing JSON by hand → 10× cheaper in tokens.
2. Standalone CLI — npx postman-gen .... No AI required.
3. Library — call scripts directly from CI / scripts.

Templates do the skeleton work. Scripts do the bulk work. The LLM only fills slots.

Install

As CLI

npm install -g postman-collection-skill
postman-gen --help

Or one-shot:

npx postman-collection-skill --help

As AI skill (Claude Code)

git clone https://github.com/adnnco/postman-collection-skill.git
cd postman-collection-skill
./install.sh

The script symlinks agents/SKILL.md + assets into ~/.claude/skills/postman-collection/. Triggers on "postman", "/postman", "convert routes to postman", etc.

As AI skill (Codex / OpenCode / Cursor)

Copy the agent file your tool reads, then point it at this repo:

| Tool | File | Action | |------|------|--------| | Claude Code | agents/SKILL.md | ./install.sh symlinks it | | Codex / OpenAI CLI | agents/AGENTS.md | Copy into your repo root as AGENTS.md | | OpenCode | agents/AGENTS.md + agents/opencode.json | Copy both into repo | | Cursor / generic | agents/CONVENTIONS.md | Copy into repo root |

Each agent file is short — instructs the LLM to invoke postman-gen (or the underlying scripts) instead of hand-writing JSON.

CLI Usage

Laravel routes

php artisan route:list --json > /tmp/routes.json
postman-gen laravel /tmp/routes.json \
  --name="My API" \
  --base-url="https://api.example.com" \
  --only-prefix=api \
  --except-vendor \
  --tests \
  --out=./postman/api.json

Optional --bodies reads FormRequest rules() and builds JSON body placeholders matching rule types.

OpenAPI

postman-gen openapi ./openapi.yaml \
  --name="My API" \
  --base-url="https://api.example.com" \
  --tests \
  --out=./postman/api.json

Supports JSON or YAML (minimal subset). Resolves $ref, infers body from requestBody.schema, detects bearer security.

Manual

# requests.json: array of { name, method, path, body?, folder?, auth? }
postman-gen merge ./postman/api.json ./requests.json \
  --name="My API" \
  --base-url="https://api.example.com" \
  --tests

What gets generated

Postman v2.1 collection with:

• {{base_url}} and {{token}} collection variables
• Path params converted to Postman :id syntax + variable array
• Folders grouped by controller (Laravel) or tag (OpenAPI)
• Accept: application/json on all requests
• Content-Type: application/json on POST/PUT/PATCH
• Bearer auth block injected when auth:sanctum / auth:api / auth:passport middleware detected
• Optional pm.response.code within 200-299 test per request

See examples/minimal.json for reference output.

Why this exists

Hand-writing Postman JSON in a chat is wasteful — the schema is verbose, the LLM regenerates the same info / _postman_id / schema boilerplate every time. This skill enforces:

• Skeleton lives in templates/ (LLM never re-writes it)
• Bulk work lives in scripts/ (LLM never re-implements it)
• Manual mode: LLM writes only {name, method, url, body} per endpoint — ~30 tokens each

Result: a 50-endpoint collection costs near-zero LLM tokens when the source is route:list or OpenAPI.

Requirements

• Node.js ≥ 18 (for openapi, merge subcommands and CLI)
• PHP ≥ 8.1 (only for laravel subcommand)

License

MIT