From 1e634e4cb69c5e3af1522709c778baabf40f3b65 Mon Sep 17 00:00:00 2001 From: Romulo Nascimento Date: Wed, 22 Jul 2026 15:06:13 -0300 Subject: [PATCH 1/3] Add Postman Flows CLI skills and slash commands --- commands/deploy-flow.md | 22 ++++++ commands/get-flow-run.md | 22 ++++++ commands/list-flows.md | 21 ++++++ commands/trigger-flow.md | 24 +++++++ skills/deploy-flow/SKILL.md | 83 +++++++++++++++++++++++ skills/get-flow-run/SKILL.md | 80 ++++++++++++++++++++++ skills/list-flows/SKILL.md | 77 +++++++++++++++++++++ skills/trigger-flow/SKILL.md | 125 +++++++++++++++++++++++++++++++++++ 8 files changed, 454 insertions(+) create mode 100644 commands/deploy-flow.md create mode 100644 commands/get-flow-run.md create mode 100644 commands/list-flows.md create mode 100644 commands/trigger-flow.md create mode 100644 skills/deploy-flow/SKILL.md create mode 100644 skills/get-flow-run/SKILL.md create mode 100644 skills/list-flows/SKILL.md create mode 100644 skills/trigger-flow/SKILL.md diff --git a/commands/deploy-flow.md b/commands/deploy-flow.md new file mode 100644 index 0000000..99df80d --- /dev/null +++ b/commands/deploy-flow.md @@ -0,0 +1,22 @@ +--- +description: Deploy a Postman Flow so it becomes triggerable, proposing and confirming a trigger path +allowed-tools: Bash, Read +--- + +Deploy a Postman Flow using the Postman CLI. Follow the `deploy-flow` skill. + +## Inputs (from the user's message) +- The flow (a 24-char ID, or a name to resolve via `list-flows`) +- Optionally a desired trigger path and whether auth is required + +## Steps +1. Resolve the flow ID (use `list-flows` if given a name; ask for the workspace if unknown). +2. Propose a trigger path derived from the flow name (e.g. "Checkout" → `/checkout`) and **confirm the path + the deploy action** with the user — deploy is mutating and MUST NOT run without explicit confirmation. +3. Show the command, then run it after confirmation: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy --path /checkout + ``` +4. Report the **Trigger URL** and whether the **trigger is enabled**. If it's off, offer `postman flows update --trigger on` (confirm first). +5. If this was part of a deploy-then-trigger request, hand back to `trigger-flow` to run it. + +Always prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials — never authenticate twice. diff --git a/commands/get-flow-run.md b/commands/get-flow-run.md new file mode 100644 index 0000000..2a36b05 --- /dev/null +++ b/commands/get-flow-run.md @@ -0,0 +1,22 @@ +--- +description: Inspect a Postman Flow run by its Run ID — per-block logs, failing block, status, and credits consumed +allowed-tools: Bash, Read +--- + +Inspect a specific Postman Flow run using the Postman CLI. Follow the `get-flow-run` skill. + +## Inputs (from the user's message) +- The Run ID (the `x-run-id` that `trigger-flow` reported; ask if unknown) +- Optionally a block ID to focus on + +## Steps +1. Take the Run ID. +2. Run a summary, then add `--logs` for detail: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id --logs + ``` + Narrow to a block with `--filter `. +3. Report **which block failed and why**, the **run status**, and **credits consumed** when the run history exposes it (say so if it doesn't, rather than inventing a number). + +Read-only: no confirmation needed. Prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials. diff --git a/commands/list-flows.md b/commands/list-flows.md new file mode 100644 index 0000000..febdaf4 --- /dev/null +++ b/commands/list-flows.md @@ -0,0 +1,21 @@ +--- +description: List Postman Flows in a workspace and resolve a flow name to its 24-character ID +allowed-tools: Bash, Read +--- + +List Postman Flows in a workspace using the Postman CLI. Follow the `list-flows` skill. + +## Inputs (from the user's message) +- The workspace ID (ask if unknown) +- Optionally a name/pattern to filter by + +## Steps +1. Ensure you have a workspace ID; ask which workspace if not. +2. Run: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace + ``` + Narrow with `--filter ""` when resolving a specific flow; use `--sort name` / `--paginate` as needed. +3. Report flow **names + IDs** (and recent status where shown). When resolving a name for another action, return the single matching ID, or present candidates and ask the user to choose on multiple matches — never guess. + +Read-only: no confirmation needed. Prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials. diff --git a/commands/trigger-flow.md b/commands/trigger-flow.md new file mode 100644 index 0000000..6a1565c --- /dev/null +++ b/commands/trigger-flow.md @@ -0,0 +1,24 @@ +--- +description: Trigger (run) a deployed Postman Flow with inputs, and deploy-then-trigger it if it isn't deployed yet +allowed-tools: Bash, Read +--- + +Trigger a deployed Postman Flow from natural language, using the Postman CLI. Follow the `trigger-flow` skill. + +## Inputs (from the user's message) +- The flow (a 24-char ID, or a name to resolve via `list-flows`) +- Any inputs / query params / headers / scenario +- The workspace ID (ask if a name needs resolving and you don't have it) + +## Steps +1. Resolve the flow ID (use `list-flows` if given a name; disambiguate multiple matches; ask for the workspace if unknown). +2. Build the flags from natural language: `-i k=v`, `-q k=v`, `--headers k=v`, `-s ""`. +3. Show the command, then run it: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger -i amount=4200 + ``` +4. Report the **Run ID**, **HTTP status**, and **response body**. +5. If not deployed → explain and **offer to deploy** (via `deploy-flow`, explicit confirmation required), then re-trigger. If the trigger is disabled → offer `postman flows update --trigger on` (confirm), then trigger. +6. On a non-2xx response → surface status + body and offer `get-flow-run --run-id ` for per-block detail. + +Always prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials — never authenticate twice. Confirm before any mutating action (deploy, enable trigger). diff --git a/skills/deploy-flow/SKILL.md b/skills/deploy-flow/SKILL.md new file mode 100644 index 0000000..f1944ad --- /dev/null +++ b/skills/deploy-flow/SKILL.md @@ -0,0 +1,83 @@ +--- +name: deploy-flow +description: Deploy a Postman Flow so it becomes triggerable, using the Postman CLI. Use when the user wants to deploy, publish, or "make a flow callable/triggerable", or when trigger-flow found a flow that isn't deployed yet and the user confirmed deploying. Deploying is a mutating action — always propose a trigger path and get explicit confirmation before running. +--- + +You are a Postman Flows assistant that deploys Flows using the Postman CLI. Deploying makes a flow triggerable and returns its **Trigger URL**. + +## When to Use This Skill + +Trigger this skill when the user wants to: +- "deploy my flow", "publish the flow", "make this flow triggerable / callable" +- as the second half of a **deploy-then-trigger** flow that `trigger-flow` started (flow wasn't deployed → user confirmed → deploy → trigger) + +--- + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy --path [options] +``` + +Options: +- `-p, --path ` — **required** URL path for the trigger (e.g. `/checkout`) +- `-t, --timeout ` — HTTP session timeout, 5000ms–60000ms (default `10000ms`) +- `-a, --auth` — enable authentication on the trigger + +## Step 1: Resolve the flow ID + +If given a name rather than a 24-char ID, resolve it with the `list-flows` skill (ask which workspace if unknown; disambiguate on multiple matches). (FR-005 dependency) + +## Step 2: Propose a trigger path and CONFIRM + +Deploy **requires** a URL path. Propose a sensible default derived from the flow name: +- "Checkout" → `/checkout` +- "Nightly Report" → `/nightly-report` + +Then **confirm the path and the action with the user before deploying** — deploy is a mutating action and MUST NOT run without explicit confirmation. (FR-002, FR-011) + +Ask about authentication only if relevant ("Should the trigger require auth?"). Add `--auth` only if they say yes. + +## Step 3: Deploy + +Show the exact command, then run it after confirmation: + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy 12345-67890-abcdef --path /checkout +``` + +Report back: +- the resulting **Trigger URL** +- whether the **trigger is enabled**. If the CLI notes the trigger is off, tell the user and offer to enable it: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows update 12345-67890-abcdef --trigger on + ``` + (enabling is also a state change → confirm first). (FR-002, FR-004) + +Example report: +``` +Deployed the Checkout flow. + Trigger URL: https:///checkout + Trigger: enabled +``` + +## Step 4: Hand back to trigger (if part of deploy-then-trigger) + +If deploying was requested so the user could run the flow, hand control back to the `trigger-flow` skill to fire it and report the Run ID + status + response — completing the deploy-then-trigger journey in one conversation. (SC-002) + +--- + +## Error Handling + +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Postman CLI needs authentication. Run: `postman login` (or set `POSTMAN_API_KEY`)." Don't re-authenticate if credentials already exist. +- **Path conflict / invalid path:** surface the CLI's message and propose an alternative path, then re-confirm. + +--- + +## Important Notes (shared authoring baseline) + +- **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** for telemetry attribution. +- **Reuse existing credentials** — no second authentication. (FR-013) +- **Never bypass entitlements** — surface CLI errors, don't assert access. (FR-014) +- **Confirm before mutating.** Deploying and enabling a trigger both change state and require explicit user confirmation. (FR-011) diff --git a/skills/get-flow-run/SKILL.md b/skills/get-flow-run/SKILL.md new file mode 100644 index 0000000..0eabeb6 --- /dev/null +++ b/skills/get-flow-run/SKILL.md @@ -0,0 +1,80 @@ +--- +name: get-flow-run +description: Inspect a specific Postman Flow run by its Run ID using the Postman CLI — per-block logs, which block failed and why, run status, and credits consumed when available. Use when a trigger returned a non-2xx, or the user asks "why did my run fail" or "what happened in run X". Read-only — no confirmation needed. +--- + +You are a Postman Flows assistant that inspects Flow runs using the Postman CLI. + +## When to Use This Skill + +Trigger this skill when: +- a `trigger-flow` call returned a **non-2xx** and the user wants to know why +- the user asks "why did my run fail", "what happened in run X", "show the logs for run " +- the user wants per-block detail, status, or credits consumed for a specific Run ID + +This is a **read-only** operation — run it without asking for confirmation. + +--- + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id [options] +``` + +Options: +- `-r, --run-id ` — **required** (this is the `x-run-id` that `trigger-flow` reported) +- `-l, --logs` — show the detailed event log +- `--filter ` — focus the event log on one or more block IDs (repeatable) + +## Step 1: Get the Run ID + +Use the Run ID the trigger skill just reported (the `x-run-id`). If you don't have one, ask the user for it. + +## Step 2: Inspect + +Start with a summary, then add `--logs` for detail: + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc123 +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc123 --logs +``` + +Narrow to a suspect block: +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc123 --logs --filter blockId1 +``` + +## Step 3: Report + +Parse the output and report, rather than dumping raw logs: +- **which block failed and why** (the failing block + reason) +- the **run status** +- **credits consumed** — surface this when the run history exposes it; if it isn't present, say so rather than inventing a number. (FR-008) + +Example: +``` +Run session-abc123 — failed + Failing block: "HTTP Request (Get Orders)" + Reason: downstream returned 504 after 10s timeout + Status: error + Credits: 3 +Suggestion: the upstream API timed out — retry, or raise the request timeout. +``` + +--- + +## Error Handling + +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Postman CLI needs authentication. Run: `postman login` (or set `POSTMAN_API_KEY`)." Don't re-authenticate if credentials already exist. +- **Run ID not found:** confirm the Run ID (it's the `x-run-id` from the trigger); runs may take a moment to appear in history. + +--- + +## Important Notes (shared authoring baseline) + +- **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** for telemetry attribution. +- **Reuse existing credentials** — no second authentication. (FR-013) +- **Never bypass entitlements** — surface CLI errors, don't assert access. (FR-014) +- Read-only: inspecting a run needs **no** confirmation. (FR-011) diff --git a/skills/list-flows/SKILL.md b/skills/list-flows/SKILL.md new file mode 100644 index 0000000..2939f0d --- /dev/null +++ b/skills/list-flows/SKILL.md @@ -0,0 +1,77 @@ +--- +name: list-flows +description: List Postman Flows in a workspace using the Postman CLI, and resolve a flow name to its 24-character ID. Use when the user asks "which flows do I have", or when another skill needs to turn a flow name into an ID before deploying or triggering. Read-only — no confirmation needed. +--- + +You are a Postman Flows assistant that lists Flows and resolves flow names to IDs using the Postman CLI. + +## When to Use This Skill + +Trigger this skill when: +- the user asks "what flows do I have", "list my flows", "show flows in workspace X" +- another skill (`trigger-flow`, `deploy-flow`, `get-flow-run`) needs to resolve a **flow name → 24-char ID** +- the user references a flow by name without giving an ID + +This is a **read-only** operation — run it without asking for confirmation. + +--- + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace [options] +``` + +Options: +- `-w, --workspace ` — **required** +- `-f, --filter ` — filter by name (name prefix or regex) +- `-s, --sort ` — sort criteria (default `updated`) +- `-p, --paginate` — page through all flows + +## Step 1: Get the workspace ID + +A workspace ID is **required**. If you don't have one, ask the user which workspace to look in. Don't fail silently. (FR-005 dependency) + +## Step 2: List + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace 12345-67890-abcdef +``` + +Narrow with `--filter` when resolving a specific name: +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace 12345-67890-abcdef --filter "Checkout" +``` + +## Step 3: Report / resolve + +- When the user asked to see their flows: report flow **names + IDs** (and recent status where shown). +- When resolving a name for another skill: + - **Single match** → use that ID. + - **Multiple matches** → present the candidates (name + ID) and **ask the user to choose**. Never guess. (Edge case: ambiguous name) + - **No match** → tell the user, and offer to list all flows in the workspace so they can pick. + +Example: +``` +Flows in workspace 12345-67890-abcdef: + 1. Checkout — 6f1a2b3c4d5e6f7a8b9c0d1e (updated 2h ago) + 2. Checkout (old) — 1a2b3c4d5e6f7a8b9c0d1e2f (updated 40d ago) +Two flows match "Checkout" — which one? +``` + +--- + +## Error Handling + +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Postman CLI needs authentication. Run: `postman login` (or set `POSTMAN_API_KEY`)." Don't re-authenticate if credentials already exist. +- **No workspace / invalid workspace:** ask for a valid workspace ID. + +--- + +## Important Notes (shared authoring baseline) + +- **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** for telemetry attribution. +- **Reuse existing credentials** — no second authentication. (FR-013) +- **Never bypass entitlements** — surface CLI errors, don't assert access. (FR-014) +- Read-only: listing needs **no** confirmation. (FR-011) diff --git a/skills/trigger-flow/SKILL.md b/skills/trigger-flow/SKILL.md new file mode 100644 index 0000000..e39e4ba --- /dev/null +++ b/skills/trigger-flow/SKILL.md @@ -0,0 +1,125 @@ +--- +name: trigger-flow +description: Trigger (run) a deployed Postman Flow using the Postman CLI, from natural language. Use when the user wants to run, fire, call, kick off, or execute a Flow with some inputs — e.g. "trigger the Checkout flow with amount=4200". Handles name→ID resolution, and if the flow is not deployed yet it offers to deploy it first (deploy-then-trigger). Pick this over deploy-flow when the intent is to *execute* a flow. +--- + +You are a Postman Flows assistant that triggers deployed Flows using the Postman CLI. + +## When to Use This Skill + +Trigger this skill when the user wants to **run** a Flow: +- "trigger my Checkout flow", "run the NightlyReport flow", "call flow X with these inputs" +- "kick off the flow", "fire the webhook for my flow", "execute the flow with amount=4200" + +Choose `deploy-flow` instead only when the user explicitly wants to *publish/deploy* a flow and not run it. If a flow isn't deployed yet, this skill detects that and offers to deploy it for them — you don't need to switch skills first. + +--- + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger [options] +``` + +Triggering fires a **deployed** flow over its webhook and returns a **Run ID** (`x-run-id`) plus the HTTP status and response body. + +Options: +- `-i, --input ` — payload values (repeatable): `-i amount=4200 -i currency=USD` +- `-f, --input-file ` — payload values from a JSON file (repeatable) +- `-q, --query ` — query parameters (repeatable) +- `--headers ` — custom headers (repeatable): `--headers X-API-Key=123` +- `-s, --scenario ` — use a named scenario from the flow definition +- `-n, --dry-run` — show the request URL + payload without sending (add `--show-secrets` to unmask tokens) +- `-r, --result` — print only the response body + +Flow IDs are 24-character hex. If you only have a name, resolve the ID first (Step 1). + +--- + +## Step 1: Resolve the flow ID + +If the user gave a **24-char ID**, use it directly. + +If the user gave a **name** (e.g. "the Checkout flow"), resolve it to an ID with the `list-flows` skill: +- You need the **workspace ID**. If you don't know it, ask the user which workspace the flow is in. +- List flows in that workspace and match the name. On a single match, use its ID. On **multiple matches**, show the candidates and ask the user to choose — never guess. + +Do not fail with "missing flow ID" — always route to resolution or ask for the workspace. (FR-005) + +## Step 2: Build the inputs + +Translate the user's natural-language request into CLI flags: +- "with amount=4200 and currency=USD" → `-i amount=4200 -i currency=USD` +- "pass ?version=v2" → `-q version=v2` +- "send header X-API-Key 123" → `--headers X-API-Key=123` +- "use the Staging scenario" → `-s "Staging"` + +Always show the exact command before running it. If the user wants to preview without sending, use `--dry-run`. + +## Step 3: Trigger + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger 12345-67890-abcdef -i amount=4200 +``` + +On success, report back **all three**: +- **Run ID** (from the `x-run-id` header) +- **HTTP status** +- **Response body** + +Example report: +``` +Triggered the Checkout flow. + Run ID: session-abc123 + Status: 200 OK + Response: { "ok": true, "orderId": "ord_991" } +``` + +## Step 4: Handle state mismatches + +### Flow is not deployed +If the CLI reports the flow is not deployed (a 404 with a hint like `To deploy it, run: postman flows deploy `): +1. **Explain** that the flow isn't deployed yet, so it can't be triggered. +2. **Offer to deploy it** on the user's behalf using the `deploy-flow` skill — which proposes a trigger path and confirms it. +3. Deploying is a **mutating action**: proceed only after the user **explicitly confirms**. If they decline, do nothing further. +4. After a successful deploy, **re-run the trigger** and report the Run ID + status + response. (FR-003) + +### Trigger is disabled +If the CLI reports the trigger/target is disabled: +1. Explain the trigger is currently off. +2. Offer to enable it — a state change requiring **explicit confirmation**: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows update --trigger on + ``` +3. After enabling (only on confirmation), trigger the flow. (FR-004) + +## Step 5: Handle a failing response + +If the trigger returns a **non-2xx** status, do NOT report a bare failure. Surface the **status and response body**, then point the user to inspecting the run: +- Offer to run the `get-flow-run` skill with the Run ID to see the failing block, reason, and status. + +``` +Trigger returned 500. + Run ID: session-def456 + Response: { "error": "downstream timeout" } +Want me to inspect the run? I can pull the per-block detail with get-flow-run for session-def456. +``` +(FR-006) + +--- + +## Error Handling + +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Postman CLI needs authentication. Run: `postman login` (or set `POSTMAN_API_KEY`)." Do not ask the user to authenticate again if they already have — the plugin reuses existing CLI credentials. +- **Unknown flow / no workspace:** resolve via `list-flows` or ask which workspace, rather than failing. + +--- + +## Important Notes (shared authoring baseline) + +- **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** so flow operations are attributed to this plugin in telemetry. It is harmless if the CLI ignores it. +- **Reuse existing credentials** — never trigger a second authentication when `postman login` / an API key is already set. (FR-013) +- **Never bypass entitlements.** Surface the CLI's own error hints verbatim where useful; do not assert access the CLI doesn't grant. (FR-014) +- **Confirm before mutating.** Deploying and enabling a trigger change state and require explicit user confirmation; triggering an already-deployed+enabled flow and reading do not. (FR-011) +- Always report the **Run ID, HTTP status, and response** on a trigger. Deeper per-block detail is available via `get-flow-run`. From 0e7f823f07d17d9b941071457a54f19b472aa952 Mon Sep 17 00:00:00 2001 From: Romulo Nascimento Date: Fri, 24 Jul 2026 14:31:25 -0300 Subject: [PATCH 2/3] Remove speckit spec IDs from Flows skills and sync doc counts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Flows skills carried trailing spec-artifact identifiers (FR-*, SC-*) in their shipped instructions. Those IDs belong only in specs/, which is authored and committed separately, so strip them — the surrounding text already states each requirement in plain language. Also update CLAUDE.md, which was stale after the four Flows skills and commands were added: correct the command count (11 → 15) and skill count (7 → 11), and list the new flow commands under the CLI section. --- CLAUDE.md | 12 ++++++++---- skills/deploy-flow/SKILL.md | 14 +++++++------- skills/get-flow-run/SKILL.md | 8 ++++---- skills/list-flows/SKILL.md | 8 ++++---- skills/trigger-flow/SKILL.md | 13 ++++++------- 5 files changed, 29 insertions(+), 26 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bcfd762..559d11f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,8 +11,8 @@ The Postman Plugin for Claude Code — a pure-markdown, configuration-driven plu ``` .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:) -skills/*/SKILL.md # 7 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context) +commands/*.md # 15 slash commands (/postman:) +skills/*/SKILL.md # 11 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context, and Flows: list-flows, trigger-flow, deploy-flow, get-flow-run) skills/*/references/*.md # On-demand reference files loaded by skills only when needed agents/readiness-analyzer.md # Sub-agent for API readiness analysis examples/ # Sample output (readiness report) @@ -31,7 +31,7 @@ examples/ # Sample output (readiness report) **Commands** (`commands/*.md`): YAML front matter with `description` and `allowed-tools`. Each defines a structured workflow invoked as `/postman:`. - MCP commands: setup, sync, search, test, mock, docs, security, learn (learn requires Full mode — `searchLearningCenter` is absent in `minimal`/`code`) -- CLI commands: request, generate-spec, run-collection +- CLI commands: request, generate-spec, run-collection, list-flows, trigger-flow, deploy-flow, get-flow-run **Skills** (`skills/*/SKILL.md`): YAML front matter with `name`, `description`, `user-invocable`. Auto-injected context, not directly invoked. `postman-knowledge` provides MCP tool guidance; `agent-ready-apis` provides readiness criteria; `postman-cli` provides CLI and git sync file structure knowledge; `postman-context` provides API discovery, exploration, and code generation from real API definitions. @@ -51,12 +51,16 @@ These are documented in `skills/postman-knowledge/mcp-limitations.md` and must b ## 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. +Several 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 ` - `/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 ` using cloud IDs from `.postman/resources.yaml` - `/postman:context` — Discover, explore, and install APIs via `postman context`. Searches Postman's API network, fetches real API definitions, and generates client code from them. +- `/postman:list-flows` — List flows in a workspace and resolve a flow name to its 24-char ID via `postman flows list` +- `/postman:trigger-flow` — Trigger a deployed flow via `postman flows trigger`, with a deploy-then-trigger fallback when the flow isn't deployed +- `/postman:deploy-flow` — Deploy a flow to make it triggerable via `postman flows deploy` (proposes and confirms a trigger path first) +- `/postman:get-flow-run` — Inspect a run by Run ID via `postman flows get-run` (per-block logs, failing block, status, credits) 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. diff --git a/skills/deploy-flow/SKILL.md b/skills/deploy-flow/SKILL.md index f1944ad..24388bc 100644 --- a/skills/deploy-flow/SKILL.md +++ b/skills/deploy-flow/SKILL.md @@ -26,7 +26,7 @@ Options: ## Step 1: Resolve the flow ID -If given a name rather than a 24-char ID, resolve it with the `list-flows` skill (ask which workspace if unknown; disambiguate on multiple matches). (FR-005 dependency) +If given a name rather than a 24-char ID, resolve it with the `list-flows` skill (ask which workspace if unknown; disambiguate on multiple matches). ## Step 2: Propose a trigger path and CONFIRM @@ -34,7 +34,7 @@ Deploy **requires** a URL path. Propose a sensible default derived from the flow - "Checkout" → `/checkout` - "Nightly Report" → `/nightly-report` -Then **confirm the path and the action with the user before deploying** — deploy is a mutating action and MUST NOT run without explicit confirmation. (FR-002, FR-011) +Then **confirm the path and the action with the user before deploying** — deploy is a mutating action and MUST NOT run without explicit confirmation. Ask about authentication only if relevant ("Should the trigger require auth?"). Add `--auth` only if they say yes. @@ -52,7 +52,7 @@ Report back: ```bash POSTMAN_CLI_SOURCE=claude-code-plugin postman flows update 12345-67890-abcdef --trigger on ``` - (enabling is also a state change → confirm first). (FR-002, FR-004) + (enabling is also a state change → confirm first). Example report: ``` @@ -63,7 +63,7 @@ Deployed the Checkout flow. ## Step 4: Hand back to trigger (if part of deploy-then-trigger) -If deploying was requested so the user could run the flow, hand control back to the `trigger-flow` skill to fire it and report the Run ID + status + response — completing the deploy-then-trigger journey in one conversation. (SC-002) +If deploying was requested so the user could run the flow, hand control back to the `trigger-flow` skill to fire it and report the Run ID + status + response — completing the deploy-then-trigger journey in one conversation. --- @@ -78,6 +78,6 @@ If deploying was requested so the user could run the flow, hand control back to ## Important Notes (shared authoring baseline) - **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** for telemetry attribution. -- **Reuse existing credentials** — no second authentication. (FR-013) -- **Never bypass entitlements** — surface CLI errors, don't assert access. (FR-014) -- **Confirm before mutating.** Deploying and enabling a trigger both change state and require explicit user confirmation. (FR-011) +- **Reuse existing credentials** — no second authentication. +- **Never bypass entitlements** — surface CLI errors, don't assert access. +- **Confirm before mutating.** Deploying and enabling a trigger both change state and require explicit user confirmation. diff --git a/skills/get-flow-run/SKILL.md b/skills/get-flow-run/SKILL.md index 0eabeb6..9909508 100644 --- a/skills/get-flow-run/SKILL.md +++ b/skills/get-flow-run/SKILL.md @@ -50,7 +50,7 @@ POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc Parse the output and report, rather than dumping raw logs: - **which block failed and why** (the failing block + reason) - the **run status** -- **credits consumed** — surface this when the run history exposes it; if it isn't present, say so rather than inventing a number. (FR-008) +- **credits consumed** — surface this when the run history exposes it; if it isn't present, say so rather than inventing a number. Example: ``` @@ -75,6 +75,6 @@ Suggestion: the upstream API timed out — retry, or raise the request timeout. ## Important Notes (shared authoring baseline) - **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** for telemetry attribution. -- **Reuse existing credentials** — no second authentication. (FR-013) -- **Never bypass entitlements** — surface CLI errors, don't assert access. (FR-014) -- Read-only: inspecting a run needs **no** confirmation. (FR-011) +- **Reuse existing credentials** — no second authentication. +- **Never bypass entitlements** — surface CLI errors, don't assert access. +- Read-only: inspecting a run needs **no** confirmation. diff --git a/skills/list-flows/SKILL.md b/skills/list-flows/SKILL.md index 2939f0d..b54180a 100644 --- a/skills/list-flows/SKILL.md +++ b/skills/list-flows/SKILL.md @@ -30,7 +30,7 @@ Options: ## Step 1: Get the workspace ID -A workspace ID is **required**. If you don't have one, ask the user which workspace to look in. Don't fail silently. (FR-005 dependency) +A workspace ID is **required**. If you don't have one, ask the user which workspace to look in. Don't fail silently. ## Step 2: List @@ -72,6 +72,6 @@ Two flows match "Checkout" — which one? ## Important Notes (shared authoring baseline) - **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** for telemetry attribution. -- **Reuse existing credentials** — no second authentication. (FR-013) -- **Never bypass entitlements** — surface CLI errors, don't assert access. (FR-014) -- Read-only: listing needs **no** confirmation. (FR-011) +- **Reuse existing credentials** — no second authentication. +- **Never bypass entitlements** — surface CLI errors, don't assert access. +- Read-only: listing needs **no** confirmation. diff --git a/skills/trigger-flow/SKILL.md b/skills/trigger-flow/SKILL.md index e39e4ba..5916d99 100644 --- a/skills/trigger-flow/SKILL.md +++ b/skills/trigger-flow/SKILL.md @@ -44,7 +44,7 @@ If the user gave a **name** (e.g. "the Checkout flow"), resolve it to an ID with - You need the **workspace ID**. If you don't know it, ask the user which workspace the flow is in. - List flows in that workspace and match the name. On a single match, use its ID. On **multiple matches**, show the candidates and ask the user to choose — never guess. -Do not fail with "missing flow ID" — always route to resolution or ask for the workspace. (FR-005) +Do not fail with "missing flow ID" — always route to resolution or ask for the workspace. ## Step 2: Build the inputs @@ -82,7 +82,7 @@ If the CLI reports the flow is not deployed (a 404 with a hint like `To deploy i 1. **Explain** that the flow isn't deployed yet, so it can't be triggered. 2. **Offer to deploy it** on the user's behalf using the `deploy-flow` skill — which proposes a trigger path and confirms it. 3. Deploying is a **mutating action**: proceed only after the user **explicitly confirms**. If they decline, do nothing further. -4. After a successful deploy, **re-run the trigger** and report the Run ID + status + response. (FR-003) +4. After a successful deploy, **re-run the trigger** and report the Run ID + status + response. ### Trigger is disabled If the CLI reports the trigger/target is disabled: @@ -91,7 +91,7 @@ If the CLI reports the trigger/target is disabled: ```bash POSTMAN_CLI_SOURCE=claude-code-plugin postman flows update --trigger on ``` -3. After enabling (only on confirmation), trigger the flow. (FR-004) +3. After enabling (only on confirmation), trigger the flow. ## Step 5: Handle a failing response @@ -104,7 +104,6 @@ Trigger returned 500. Response: { "error": "downstream timeout" } Want me to inspect the run? I can pull the per-block detail with get-flow-run for session-def456. ``` -(FR-006) --- @@ -119,7 +118,7 @@ Want me to inspect the run? I can pull the per-block detail with get-flow-run fo ## Important Notes (shared authoring baseline) - **Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin`** so flow operations are attributed to this plugin in telemetry. It is harmless if the CLI ignores it. -- **Reuse existing credentials** — never trigger a second authentication when `postman login` / an API key is already set. (FR-013) -- **Never bypass entitlements.** Surface the CLI's own error hints verbatim where useful; do not assert access the CLI doesn't grant. (FR-014) -- **Confirm before mutating.** Deploying and enabling a trigger change state and require explicit user confirmation; triggering an already-deployed+enabled flow and reading do not. (FR-011) +- **Reuse existing credentials** — never trigger a second authentication when `postman login` / an API key is already set. +- **Never bypass entitlements.** Surface the CLI's own error hints verbatim where useful; do not assert access the CLI doesn't grant. +- **Confirm before mutating.** Deploying and enabling a trigger change state and require explicit user confirmation; triggering an already-deployed+enabled flow and reading do not. - Always report the **Run ID, HTTP status, and response** on a trigger. Deeper per-block detail is available via `get-flow-run`. From 5c9ad3640bd75ec283db5e3429a966d91fbc0d99 Mon Sep 17 00:00:00 2001 From: Romulo Nascimento Date: Fri, 24 Jul 2026 14:45:46 -0300 Subject: [PATCH 3/3] Removed credits info --- CLAUDE.md | 2 +- commands/get-flow-run.md | 4 ++-- skills/get-flow-run/SKILL.md | 6 ++---- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 559d11f..c056e76 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,7 +60,7 @@ Several commands use the Postman CLI instead of MCP. They require `postman-cli` - `/postman:list-flows` — List flows in a workspace and resolve a flow name to its 24-char ID via `postman flows list` - `/postman:trigger-flow` — Trigger a deployed flow via `postman flows trigger`, with a deploy-then-trigger fallback when the flow isn't deployed - `/postman:deploy-flow` — Deploy a flow to make it triggerable via `postman flows deploy` (proposes and confirms a trigger path first) -- `/postman:get-flow-run` — Inspect a run by Run ID via `postman flows get-run` (per-block logs, failing block, status, credits) +- `/postman:get-flow-run` — Inspect a run by Run ID via `postman flows get-run` (per-block logs, failing block, status) 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. diff --git a/commands/get-flow-run.md b/commands/get-flow-run.md index 2a36b05..e424c6d 100644 --- a/commands/get-flow-run.md +++ b/commands/get-flow-run.md @@ -1,5 +1,5 @@ --- -description: Inspect a Postman Flow run by its Run ID — per-block logs, failing block, status, and credits consumed +description: Inspect a Postman Flow run by its Run ID — per-block logs, failing block, and status allowed-tools: Bash, Read --- @@ -17,6 +17,6 @@ Inspect a specific Postman Flow run using the Postman CLI. Follow the `get-flow- POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id --logs ``` Narrow to a block with `--filter `. -3. Report **which block failed and why**, the **run status**, and **credits consumed** when the run history exposes it (say so if it doesn't, rather than inventing a number). +3. Report **which block failed and why** and the **run status**. Read-only: no confirmation needed. Prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials. diff --git a/skills/get-flow-run/SKILL.md b/skills/get-flow-run/SKILL.md index 9909508..3ded039 100644 --- a/skills/get-flow-run/SKILL.md +++ b/skills/get-flow-run/SKILL.md @@ -1,6 +1,6 @@ --- name: get-flow-run -description: Inspect a specific Postman Flow run by its Run ID using the Postman CLI — per-block logs, which block failed and why, run status, and credits consumed when available. Use when a trigger returned a non-2xx, or the user asks "why did my run fail" or "what happened in run X". Read-only — no confirmation needed. +description: Inspect a specific Postman Flow run by its Run ID using the Postman CLI — per-block logs, which block failed and why, and run status. Use when a trigger returned a non-2xx, or the user asks "why did my run fail" or "what happened in run X". Read-only — no confirmation needed. --- You are a Postman Flows assistant that inspects Flow runs using the Postman CLI. @@ -10,7 +10,7 @@ You are a Postman Flows assistant that inspects Flow runs using the Postman CLI. Trigger this skill when: - a `trigger-flow` call returned a **non-2xx** and the user wants to know why - the user asks "why did my run fail", "what happened in run X", "show the logs for run " -- the user wants per-block detail, status, or credits consumed for a specific Run ID +- the user wants per-block detail or status for a specific Run ID This is a **read-only** operation — run it without asking for confirmation. @@ -50,7 +50,6 @@ POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc Parse the output and report, rather than dumping raw logs: - **which block failed and why** (the failing block + reason) - the **run status** -- **credits consumed** — surface this when the run history exposes it; if it isn't present, say so rather than inventing a number. Example: ``` @@ -58,7 +57,6 @@ Run session-abc123 — failed Failing block: "HTTP Request (Get Orders)" Reason: downstream returned 504 after 10s timeout Status: error - Credits: 3 Suggestion: the upstream API timed out — retry, or raise the request timeout. ```