k6 guides
Same pattern as otel-guides (one file per language) and
observability-cli-guides (one file per backend): a selection map whose
callers open exactly the reference they need instead of re-deriving k6
usage from memory. Here the selection axis is the topic.
Fetching the docs
grafana.com/docs/k6/latest/ serves raw markdown by appending .md to
any page URL, or via an Accept: text/markdown header.
https://grafana.com/llms.txt (curated index) and
https://grafana.com/llms-full.txt (~1.4 MB, ~1000 docs/k6/latest
URLs) exist at the site root - the cheapest way to enumerate the k6 doc
tree when this skill's reference files need re-verifying; per-page
fetching via the .md suffix is still how the content itself is read.
Both live at the site root, not under /docs/k6/latest/ (that path
404s) - a natural first mistake, verify against the root before
concluding they don't exist.
An underscore written outside backticks may come back
backslash-escaped. Names the pages write as code keep their
underscores; names written as plain text - the metrics reference's
first column is the case that bites - are served as
dropped\_iterations, so a grep for the bare name finds nothing on a
page that does document the metric. It is not a property of tables:
verified live (this machine, 2026-09-06) on the fetched .md of
using-k6/metrics/reference/ (56 escaped underscores, every one of
them an unbackticked name in a table's first column; grep -c dropped_iterations -> 0, grep -c 'dropped\\_iterations' -> 1),
against using-k6/k6-options/reference/ and using-k6/thresholds/
(143 and 7 table data rows, zero escaped underscores - both write
their names as code). Before concluding a metric or an option is
undocumented, grep with the underscore made optional
(grep -i 'dropped.\?_iterations') or on the unambiguous fragment
alone (grep -i dropped).
Which reference
| Question |
Reference |
| Is k6 installed? How do I install/detect it? |
install.md |
| What replay line may a preflight hand the mission? |
install.md, its closing section |
| How do I run a k6 script, read its output, know if it passed? |
running-tests.md |
How do I validate a script without running the benchmark - k6 inspect, a one-iteration smoke? |
running-tests.md |
Why is res.body null / why does res.json() throw? |
scripting.md |
| How do I write the script - requests, checks, thresholds, staged load? |
scripting.md |
| Which test type fits this investigation - smoke, load, stress, soak, spike, breakpoint? |
test-types.md |
| What does a benchmark's authoring need decided, and by whom - human or agent? |
authoring-inputs.md |
| Does k6 support the service's protocol (gRPC, WebSockets, ...)? |
protocols.md |
| How do I drive an MCP server - the session handshake, SSE bodies, one session per VU? |
mcp.md |
| Is this browser/frontend performance testing rather than API load? |
browser.md |
Conventions
- Reference content is a snapshot ("last verified YYYY-MM") - the
fetched official page always overrides it. Recommendations must come
from a fetched page, never from memory; anything unfetchable is marked
unverified rather than presented as sourced.
- The k6 major version is stated.
latest currently documents k6
v2 - install.md names it, and scripting.md never recommends a
removed executor or command. A skill that silently mixes v1 and v2
guidance produces scripts that fail to start.
- These references cover k6 itself - never this project's
.odd/benchmarks/ format, never the manifest schema. That knowledge
lives with odd-memory's benchmark reference and
k6-benchmark-expert.
1---2name: k6-guides3description: Curated map of the official k6 load-testing docs - installation, running a script, scripting (checks/thresholds/scenarios), test types, protocols, and which questions a benchmark's inputs require before it can be authored. Use when authoring or reasoning about a k6 benchmark - pick the topic, open its reference file, and follow the linked official docs. Read by /odd-instrument-bench (which questions to ask), k6-benchmark-expert (authoring and validating), a stored benchmark's replay (running one), and the /odd-instrument-bench, /odd-observe, and /odd-verify preflights (ensuring k6 is present).4---56# k6 guides78Same pattern as `otel-guides` (one file per language) and9`observability-cli-guides` (one file per backend): a selection map whose10callers open exactly the reference they need instead of re-deriving k611usage from memory. Here the selection axis is the topic.1213## Fetching the docs1415`grafana.com/docs/k6/latest/` serves raw markdown by appending `.md` to16any page URL, or via an `Accept: text/markdown` header.17`https://grafana.com/llms.txt` (curated index) and18`https://grafana.com/llms-full.txt` (~1.4 MB, ~1000 `docs/k6/latest`19URLs) exist at the site root - the cheapest way to enumerate the k6 doc20tree when this skill's reference files need re-verifying; per-page21fetching via the `.md` suffix is still how the content itself is read.22Both live at the site **root**, not under `/docs/k6/latest/` (that path23404s) - a natural first mistake, verify against the root before24concluding they don't exist.2526**An underscore written outside backticks may come back27backslash-escaped.** Names the pages write as code keep their28underscores; names written as plain text - the metrics reference's29first column is the case that bites - are served as30`dropped\_iterations`, so a grep for the bare name finds nothing on a31page that does document the metric. It is not a property of tables:32verified live (this machine, 2026-09-06) on the fetched `.md` of33`using-k6/metrics/reference/` (56 escaped underscores, every one of34them an unbackticked name in a table's first column; `grep -c35dropped_iterations` -> `0`, `grep -c 'dropped\\_iterations'` -> `1`),36against `using-k6/k6-options/reference/` and `using-k6/thresholds/`37(143 and 7 table data rows, **zero** escaped underscores - both write38their names as code). Before concluding a metric or an option is39undocumented, grep with the underscore made optional40(`grep -i 'dropped.\?_iterations'`) or on the unambiguous fragment41alone (`grep -i dropped`).4243## Which reference4445| Question | Reference |46| --- | --- |47| Is k6 installed? How do I install/detect it? | [install.md](references/install.md) |48| What replay line may a preflight hand the mission? | [install.md](references/install.md), its closing section |49| How do I run a k6 script, read its output, know if it passed? | [running-tests.md](references/running-tests.md) |50| How do I validate a script without running the benchmark - `k6 inspect`, a one-iteration smoke? | [running-tests.md](references/running-tests.md) |51| Why is `res.body` null / why does `res.json()` throw? | [scripting.md](references/scripting.md) |52| How do I write the script - requests, checks, thresholds, staged load? | [scripting.md](references/scripting.md) |53| Which test type fits this investigation - smoke, load, stress, soak, spike, breakpoint? | [test-types.md](references/test-types.md) |54| What does a benchmark's authoring need decided, and by whom - human or agent? | [authoring-inputs.md](references/authoring-inputs.md) |55| Does k6 support the service's protocol (gRPC, WebSockets, ...)? | [protocols.md](references/protocols.md) |56| How do I drive an MCP server - the session handshake, SSE bodies, one session per VU? | [mcp.md](references/mcp.md) |57| Is this browser/frontend performance testing rather than API load? | [browser.md](references/browser.md) |5859## Conventions6061- Reference content is a **snapshot** ("last verified YYYY-MM") - the62 fetched official page always overrides it. Recommendations must come63 from a fetched page, never from memory; anything unfetchable is marked64 unverified rather than presented as sourced.65- **The k6 major version is stated.** `latest` currently documents k666 **v2** - `install.md` names it, and `scripting.md` never recommends a67 removed executor or command. A skill that silently mixes v1 and v268 guidance produces scripts that fail to start.69- These references cover k6 **itself** - never this project's70 `.odd/benchmarks/` format, never the manifest schema. That knowledge71 lives with `odd-memory`'s `benchmark` reference and72 `k6-benchmark-expert`.
using-system