Merge pull request #16 from Postman-Devrel/003-flow-skills

Add Postman Flows CLI skills and slash commands

Author: romulo-nascimento

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:<name>)
-skills/*/SKILL.md            # 7 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context)
+commands/*.md                # 15 slash commands (/postman:<name>)
+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:<name>`.
 - 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 <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`
 - `/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)
 
 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.
 

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 <flowId> --path /checkout
+   ```
+4. Report the **Trigger URL** and whether the **trigger is enabled**. If it's off, offer `postman flows update <flowId> --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.

commands/get-flow-run.md

@@ -0,0 +1,22 @@
+---
+description: Inspect a Postman Flow run by its Run ID — per-block logs, failing block, and status
+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 <runId>
+   POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id <runId> --logs
+   ```
+   Narrow to a block with `--filter <blockId>`.
+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.

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 <workspaceId>
+   ```
+   Narrow with `--filter "<name>"` 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.

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 "<scenario>"`.
+3. Show the command, then run it:
+   ```bash
+   POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger <flowId> -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 <flowId> --trigger on` (confirm), then trigger.
+6. On a non-2xx response → surface status + body and offer `get-flow-run --run-id <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).

skills/deploy-flow/SKILL.md

@@ -0,0 +1,64 @@
+---
+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, or when trigger-flow found an undeployed flow and the user confirmed.
+---
+
+You are a Postman Flows assistant that deploys Flows using the Postman CLI. Deploying makes a flow triggerable and returns its **Trigger URL**.
+
+## The command this wraps
+
+```bash
+POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy <flowId> --path </path> [options]
+```
+
+Options:
+- `-p, --path <path>` — **required** URL path for the trigger (e.g. `/checkout`)
+- `-t, --timeout <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).
+
+## 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`
+
+Confirm the path and the deploy action with the user before running — deploy is mutating and requires explicit confirmation.
+
+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).
+
+Example report:
+```
+Deployed the Checkout flow.
+  Trigger URL: https://<host>/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.
+
+---
+
+Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules.
+
+Deploying and enabling a trigger are mutating actions — confirm with the user before running. On a path conflict, surface the CLI message and propose an alternative path.

skills/deploy-flow/references/flows-cli-baseline.md

@@ -0,0 +1,9 @@
+# Flows CLI Baseline
+
+These rules apply to every Flows CLI skill.
+
+- Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin` for telemetry attribution.
+- Reuse existing `postman login` / API key credentials. Do not trigger a second authentication.
+- Surface CLI errors verbatim. Do not assert access the CLI does not grant.
+- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`"
+- **Not authenticated:** "Run `postman login` (or set `POSTMAN_API_KEY`)."

skills/get-flow-run/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: get-flow-run
+description: Inspect a Postman Flow run by Run ID using the Postman CLI — per-block logs, failing block, and status. Use when a trigger returned a non-2xx or the user asks why a run failed.
+---
+
+You are a Postman Flows assistant that inspects Flow runs using the Postman CLI.
+
+## The command this wraps
+
+```bash
+POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id <runId> [options]
+```
+
+Options:
+- `-r, --run-id <runId>` — **required** (this is the `x-run-id` that `trigger-flow` reported)
+- `-l, --logs` — show the detailed event log
+- `--filter <blockId>` — 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**
+
+Example:
+```
+Run session-abc123 — failed
+  Failing block: "HTTP Request (Get Orders)"
+  Reason:        downstream returned 504 after 10s timeout
+  Status:        error
+Suggestion: the upstream API timed out — retry, or raise the request timeout.
+```
+
+---
+
+Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules.
+
+This is a read-only operation — no confirmation needed. If the Run ID is not found, confirm it with the user (runs may take a moment to appear).

skills/get-flow-run/references/flows-cli-baseline.md

@@ -0,0 +1,9 @@
+# Flows CLI Baseline
+
+These rules apply to every Flows CLI skill.
+
+- Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin` for telemetry attribution.
+- Reuse existing `postman login` / API key credentials. Do not trigger a second authentication.
+- Surface CLI errors verbatim. Do not assert access the CLI does not grant.
+- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`"
+- **Not authenticated:** "Run `postman login` (or set `POSTMAN_API_KEY`)."

skills/list-flows/SKILL.md

@@ -0,0 +1,55 @@
+---
+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 they have, or when another skill needs to resolve a flow name to an ID before deploying or triggering.
+---
+
+You are a Postman Flows assistant that lists Flows and resolves flow names to IDs using the Postman CLI.
+
+## The command this wraps
+
+```bash
+POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace <workspaceId> [options]
+```
+
+Options:
+- `-w, --workspace <workspaceId>` — **required**
+- `-f, --filter <pattern>` — filter by name (name prefix or regex)
+- `-s, --sort <name|updated>` — 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.
+
+## 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?
+```
+
+---
+
+Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules.
+
+This is a read-only operation — no confirmation needed.