/k6

name: k6
license: Apache-2.0
description: Generate, validate, and review k6 test scripts — load, stress, spike, soak, smoke, breakpoint, functional, and protocol. Covers HTTP, WebSocket, gRPC, browser, all executors, thresholds, checks, custom metrics, the k6-testing library, k6 Cloud execution, and the xk6 extension ecosystem; uses the xk6-docs CLI (with grafana.com web fallback) for docs lookup and validates every script by running it. Use when writing, generating, validating, or debugging any k6 or load-test script (including plain-language asks like "load test this API" or "stress test my service"), choosing executors/scenarios, or setting thresholds. For end-to-end website performance suites use k6-perf-test-website; for documenting k6 itself use k6-docs.

k6 Script Generation

> **Efficiency note:** This is a short linear recipe (read example → adapt → save → validate → review). A todo list would just mirror the headings without adding value, so skip the planning overhead and execute the steps directly. > > **Agent-agnostic:** The steps below describe capabilities, not specific tools. Where a step says "fetch a URL" or "write a file", use whatever your agent provides for that capability (e.g. a web-fetch tool, a file-write tool, or shell `curl`/`tee`).

---

Step 1: Pick the right example file

Read only the file that matches the user's request. Examples provide structural scaffolding — the correct scaffold, option shapes, and import patterns.

| User needs | Read this file | |-----------|---------------| | HTTP REST, auth flow, batch requests | `examples/http.js` | | HTML parsing with parseHTML, SharedArray | `examples/html.js` | | WebSocket | `examples/websocket.js` | | gRPC | `examples/grpc.js` | | Browser automation | `examples/browser.js` | | Browser + functional test / `expect()` / k6-testing | `examples/functional.js` (browser scenario) | | Functional/integration tests, `expect()`, k6-testing | `examples/functional.js` | | Custom metrics, execution module, handleSummary, per-vu-iterations | `examples/metrics.js` | | Load patterns, all executors (ramping, arrival rate, per-VU, etc.) | `examples/executors.js` | | Cloud run, `--local-execution`, `cloud` options | `examples/cloud.js` | | Crypto (HMAC, MD5, SHA256) or encoding (base64) | `examples/crypto-encoding.js` | | xk6-faker | `examples/ext-faker.js` | | xk6-redis | `examples/ext-redis.js` | | xk6-sql / sqlite3 / postgres | `examples/ext-sql.js` | | xk6-exec | `examples/ext-exec.js` | | xk6-dns | `examples/ext-dns.js` | | xk6-tls | `examples/ext-tls.js` | | xk6-tcp | `examples/ext-tcp.js` | | xk6-crawler | `examples/ext-crawler.js` |

Example files live in the `examples/` directory alongside this `SKILL.md`.

**When the request matches multiple rows** (e.g. "browser" + "functional test"), prefer the row whose assertion style fits the intent. If the user says "functional test", "assert", "verify", or "expect", use `functional.js` even if the test involves a browser — it demonstrates `expect()` with auto-retrying browser matchers. Use `browser.js` for browser load/performance tests that don't emphasize correctness assertions.

---

Step 2: Adapt the example

Use the loaded example as the starting point. Adapt it to the user's exact requirements:

• Change endpoints, VU counts, durations, thresholds
• Add or remove scenario steps
• Rename functions and variables to match the domain
• Every expression must be complete and runnable — no `{ ... }`, `// TODO`, or stubs
• **Match the request — don't over-build.** Implement exactly what was asked. Don't add custom request tags, extra `sleep()` calls, additional endpoints, or `options` the user didn't request. Unrequested complexity lowers quality and reduces adherence to the spec.

For multi-scenario scripts (browser + HTTP, cloud): use named `scenarios` with `exec` pointing to separate exported functions.

---

Step 3: Fill gaps with docs (only if needed)

The example covers common patterns. Adapt from it directly. **Skip this step entirely** if the example provides everything you need.

**Only reach for docs if**:

• The user asks for an API or option not demonstrated in the example, **or**
• You are not confident about the exact signature, option name, or return type

When a gap exists, first establish the docs command (one-time per session).

The `k6 x docs` CLI renders content only when it detects a TTY. Since agents run non-interactively, wrap every call with `script` to allocate a pseudo-TTY and pipe the ANSI-stripped content to stdout:

# Detect OS once (macOS vs Linux have different `script` flags):
if [[ "$(uname -s)" == "Darwin" ]]; then
  DOCS_CMD="script -q /dev/null k6 x docs"
else
  DOCS_CMD="script -qc 'k6 x docs' /dev/null"
fi

# Verify it works — should print a topic list, NOT a "browse files" guide:
$DOCS_CMD 2>/dev/null | head -5

If the output still shows "k6 documentation is a directory of markdown files", the TTY wrapper isn't working. Fall back to **web docs** under `https://grafana.com/docs/k6/latest/` — fetch pages with whatever web-fetch capability your agent has (a built-in fetch tool, or `curl` in a shell).

If `k6 x docs` fails outright (command not found, provisioning or 404 errors), read `SETUP.md` — it covers auto-provisioning on k6 v1.7.0+ and the manual xk6 build for older versions.

Then look up what you need:

$DOCS_CMD <path>              # e.g. javascript-api k6-http
$DOCS_CMD <path> --depth 2
$DOCS_CMD search <term>

Common CLI paths and the 2-call strategy are in `docs-guidance.md`.

**Do not use unpkg, @types/k6, or any npm type definition URLs.**

---

Step 4: Save

Line 1 of every script must be a generated-by comment. Get the current UTC timestamp first (the file content depends on it, so this can't be parallelized with the write):

date -u +%Y-%m-%dT%H:%M:%SZ

Then include it as line 1:

// Generated by grafana-k6 on 2026-03-25T22:02:20.203Z

Save to `k6/scripts/<de