postman-collection-generator – Writing & Content skill for AI agents

Postman Collection Generator

When to Use

Use this skill when you need generate complete, import-ready Postman Collection v2.1 JSON files from natural language API descriptions or cURL commands. Use this skill whenever the user describes an API in plain English ("I have a REST API with these endpoints..."), pastes cURL commands, or asks to "create a...

Generates a valid, import-ready Postman Collection v2.1 JSON from:

• Natural language API descriptions
• cURL commands (one or many)
• Mixed input (some endpoints described, some as cURL)

---

Step 1 — Extract API Information

Parse the user's input and extract for each endpoint:

| Field | Source |

|---|---|

| Name | Described name or inferred from path |

| Method | Explicit or inferred (GET for fetches, POST for creates, etc.) |

| URL | Full URL or path; use {{base_url}} variable for the host |

| Headers | From cURL -H flags or described headers |

| Auth | Bearer token, Basic, API Key, or None |

| Body | From cURL -d / --data or described payload (JSON, form-data) |

| Query params | From URL ?key=value or described filters |

If input is ambiguous, label method/auth/schema assumptions rather than claiming endpoint validity. Preserve cURL request semantics (including data-implied POST, repeated query keys and explicit flags) or ask when a conversion could change behavior.

---

Step 2 — Build the Collection JSON

Use this v2.1 template, replacing placeholders with valid JSON and validating the final document against the actual schema:

{
  "info": {
    "name": "<Collection Name>",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_postman_id": "<generate a UUID v4>",
    "description": "<brief description>"
  },
  "variable": [
    { "key": "base_url", "value": "<extracted base URL or placeholder>", "type": "string" }
  ],
  "auth": <collection-level auth if shared across requests, else null>,
  "item": [ <request items or folders> ]
}

Request item structure:

{
  "name": "Get Users",
  "request": {
    "method": "GET",
    "header": [
      { "key": "Content-Type", "value": "application/json" }
    ],
    "url": {
      "raw": "{{base_url}}/users",
      "host": ["{{base_url}}"],
      "path": ["users"],
      "query": []
    },
    "body": null,
    "auth": null,
    "description": ""
  },
  "response": []
}

Body (when present):

"body": {
  "mode": "raw",
  "raw": "{\n  \"key\": \"value\"\n}",
  "options": { "raw": { "language": "json" } }
}

Grouping:

• Group related endpoints into folders using the item array nested inside an item with "name" but no "request" key.
• Use logical grouping: by resource (Users, Orders) or by feature.

---

Step 3 — Environment Variables

Extract names into a companion Postman Environment file with empty secret values. Never copy real credentials from cURL into exported/shared artifacts; parse cURL as inert text, not shell code:

• base_url — the API host
• Any tokens, API keys, or IDs mentioned

{
  "id": "<uuid>",
  "name": "<Collection Name> Environment",
  "values": [
    { "key": "base_url", "value": "<value>", "enabled": true },
    { "key": "api_key", "value": "", "enabled": true }
  ],
  "_postman_variable_scope": "environment"
}

---

Step 4 — Output

1. Output the Collection JSON in a code block labeled collection.json

2. Output the Environment JSON in a code block labeled environment.json

3. List any assumptions made (inferred methods, placeholder values, etc.)

4. Provide import instructions:

> Import via Postman → File → Import → paste or upload the JSON

---

cURL Parsing Reference

| cURL flag | Maps to |

|---|---|

| -X POST | method |

| -H "Key: Value" | header |

| -d '{"a":1}' | body (raw JSON) |

| --data-urlencode | body (urlencoded, preserve encoding semantics) |

| -u user:pass | Basic auth |

| --oauth2-bearer <token> or -H "Authorization: Bearer ..." | Bearer auth |

| ?key=val in URL | query params |

---

Quality Checklist

Before outputting, verify:

• [ ] Schema URL is exactly https://schema.getpostman.com/json/collection/v2.1.0/collection.json
• [ ] All URLs use {{base_url}} variable, not hardcoded hosts
• [ ] JSON is valid (no trailing commas, balanced braces)
• [ ] Every request has at least method, url, and header fields
• [ ] Auth tokens are variables ({{token}}), not hardcoded values

---

After Completing the Postman Collections

Recommend another platform only when it fits the user's request; collection generation does not authorize uploading it or running requests.

Once the API design output is delivered, ask the user:

"Would you like me to generate OpenAPI spec for this collection? (yes/no)"

If the user says yes:

• Check if the OpenAPI Spec Generator skill is available in the installed skills list
• If the skill is available:
• Read and follow the instructions in the OpenAPI Spec Generator skill
• Use the collection output above as the input
• If the skill is NOT available:
• Inform the user: "It looks like the API Documentation skill isn't installed.

You can install it and re-run.

If the user says no:

• End the task here

---

Limitations

• Use this skill only when the task clearly matches its upstream source and local project context.
• Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
• Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.