/k6-perf-test-website

name: k6-perf-test-website
description: >
  Use when the user wants to performance-test, load-test, or stress-test
  a public website end-to-end with k6. Produces a hybrid (protocol +
  browser) test suite, SLO-backed thresholds, a load-generator monitor
  sidecar, and a Grafana-side investigation playbook for backends the
  user owns. Triggers on "perf test my site", "performance test my
  site", "load test this URL",
  "stress test my web app", "I want to load test [URL]", "set up k6
  against my website", "write a k6 suite for [site]", "see if my site
  handles N concurrent users", or "how does my site perform under
  traffic". Use this skill whenever the user mentions k6, load testing,
  stress testing, performance testing, or wants to validate a website
  under traffic — even if they don't explicitly use the word "test" or
  ask for the specific outputs this skill produces.

`k6-perf-test-website`

An end-to-end, opinionated workflow for performance-testing any public website with k6. The skill produces:

• A scaffolded project with one folder per user-described workflow.
• Functional protocol + browser tests (must pass before load testing).
• Hybrid load tests (protocol scenario + 1 browser VU) per test type

(smoke / average / stress / spike / soak / breakpoint).

• SLO-backed thresholds with per-endpoint tagging and Web Vitals.
• A cross-platform load-generator monitor sidecar.
• Optional Grafana-side investigation when the user owns the backend.
• A structured Markdown report at the end.

This skill enforces a few opinions you should not silently override:

• **Always elicit workflows first.** Don't guess.
• **Functional tests must be green before load tests run.**
• **Always monitor the load generator** — server-looks-slow is often

laptop-looks-slow.

• **Local for validation, cloud for scale** — but ask the user where

to run each test type; don't hardcode.

• **No shared `tests/lib/`.** Iteration-body duplication is preferred;

each script reads cleanly on its own during incident review.

Prerequisites

• **k6 ≥ v2.0.0** (`k6 version`) — required for stable `k6/browser`,

`expect()`, async/await iteration functions, and per-request `tags`.

• **Node.js ≥ 20** + npm.
• **Playwright** with the Chromium download

(`npx playwright install chromium`).

• **`har-to-k6`** (`npm i -D har-to-k6`).
• Network access from the load-generator host to the target site.

Tools the skill prefers when installed:

• `mcp-k6` — script creation, Playwright→k6/browser migration, API

lookup. Prefer over hand-writing k6 boilerplate.

• `mcp-grafana` — in-session Prometheus/Loki/Tempo/Pyroscope queries

during §9 backend investigation.

• `gcx` — Grafana Cloud CLI for shell-friendly queries, datasource

discovery, and Grafana Cloud k6 cloud-run dispatch.

• `k6` binary — local validation runs and breakpoint hunting.
• `k6 x docs` (xk6-docs) — look up k6 API surface when writing or

editing scripts without `mcp-k6` available.

If these tools are not configured the skill falls back to plain CLI tools (`k6`, `npx`, `curl`) and hand-written scripts. The skill does not own toolchain setup; defer to the user's existing setup process.

Explicit non-goals:

• Protocol-only suites (out of scope for this skill).
• API-only / non-browser apps.
• Mobile-native testing.
• Capacity planning beyond finding and tagging a breakpoint.

Workflow overview

Tick these off in order. Each step has a section below.

1. Elicit workflows from the user. [§1](#1-elicit-workflows) 2. Scaffold the project from `assets/`. [§2](#2-scaffold-the-project) 3. Record each workflow with Playwright. [§3](#3-record-each-workflow) 4. Build functional protocol + browser tests; run `tests/run-all.sh` until green. [§4](#4-build-functional-tests) 5. Design SLO-backed thresholds and per-endpoint tags. [§5](#5-design-slos-and-thresholds) 6. Build hybrid load tests, one file per test type. [§6](#6-build-hybrid-load-tests) 7. Run validation locally with the LG sidecar. [§7](#7-run-locally-with-lg-sidecar) 8. Push to Grafana Cloud k6 for the test types the user chose for cloud. [§8](#8-push-to-grafana-cloud-k6) 9. Investigate the backend with Grafana (if owned). [§9](#9-investigate-the-backend) 10. Report back to the user. [§10](#10-report-back)

1. Elicit workflows

**The single most important step.** Without explicit workflows, every later step is guesswork.

Ask the user the questions in `references/workflow-elicitation.md` and record answers in a `runbook.md` alongside the scaffolded project.

You must capture: 2-4 named workflows, credentials, read vs write, destructive actions to avoid during soak, worry list, existing SLOs, backend ownership and Grafana access, and **per test type** whether each runs locally or in Grafana Cloud k6.

If the user can't name at least one workflow, **stop and clarify**; do not proceed.

2. Scaffold the project

Copy the `assets/` tree from this skill into the user's chosen directory. The skill's `assets/` directory is at `<SKILL_DIR>/assets/`, where `<SKILL_DIR>` is the absolute path to this skill's directory — your harness exposes this (e.g. opencode prefixes skill metadata with a `Base directory for this skill:` line). If you can't determine `<SKILL_DIR>` from context, ask the user.

cp -R "<SKILL_DIR>/assets/." "<target-dir>/"

If `cp -R` is blocked by sandbox permissions, copy files individually via your agent's file-write tool.

The scaffolded layout:

<target-dir>/
├── package.json
├── .gitignore
├── README.md
├── runbook.md                       # you create from §1 answers
├── recordings/
│   ├── README.md
│   └── scripts/
│       └── recorder.template.js     # copy per workflow → wN-<short-name>.js, …
├── tests/
│   ├── run-all.sh
│   └── workflow.template/           # copy per workflow → wN-<short-name>/, …
│       ├── from-har.js
│       ├── protocol.js
│       ├── browser.js
│       ├── smoke.js
│       ├── average.js
│       ├── stress.js
│