# k6-test-maintenance

A skill for maintaining existing k6 test scripts: tightens thresholds from trend data, migrates scripts to new k6 releases, and fixes tests after service changes.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2700 installs · ★ 290
- Author: grafana
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/grafana/skills/tree/HEAD/skills/grafana-k6/k6-test-maintenance/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/k6-test-maintenance

## What it does

Five maintenance tasks are covered: tightening thresholds against observed metrics, migrating a script to a newer k6 release, adapting a test after the service changes, refactoring, and auditing against current best practices. Each one has a step-by-step procedure in `references/workflows.md`.

The core rule is behavior-aware change control. Syntactic edits such as renaming a variable or switching `let` to `const` get applied directly. Anything that shifts metrics, pass/fail results, timing or load shape comes back as a diff with rationale and waits for confirmation. That bar is set deliberately low, because a change like `p(95)<500` to `p(95)<420` can ripple into CI gates and SLO math.

Before touching k6 APIs or imports, the skill checks current docs and cites the source. That needs either mcp-k6 with `validate_script` and `get_documentation`, or the `k6 x docs` CLI. Scripts hosted in Grafana Cloud are edited only through `k6-manage`, following GET, backup, edit, validate, PUT. Every edit runs through `k6 inspect`, and runtime-logic changes also need a cloud run.

## Requirements
- Works with: Grafana

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add grafana/skills --skill k6-test-maintenance -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/k6-test-maintenance/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/k6-test-maintenance/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add grafana/skills --skill k6-test-maintenance -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/k6-test-maintenance/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add grafana/skills --skill k6-test-maintenance -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/k6-test-maintenance/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install grafana/skills k6-test-maintenance
```

2. **Manually: put the files in place**
- File: `.github/skills/k6-test-maintenance/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add grafana/skills --skill k6-test-maintenance -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/grafana/skills --path skills/grafana-k6/k6-test-maintenance
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/k6-test-maintenance/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add grafana/skills --skill k6-test-maintenance -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/grafana/skills/tree/HEAD/skills/grafana-k6/k6-test-maintenance/SKILL.md

## When to use it
- tighten thresholds from trend data instead of guessing
- migrate a script to a new k6 release without breaking imports
- repair a test after the service changes an endpoint
- strip dead code and outdated patterns from a test
- check a script against current k6 documentation

## Example prompts
- fix my k6 test, it started failing after the deploy
- tighten the thresholds using the latest run data
- migrate this script to the new k6 version and show me the diff

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2e99517d32d16320.

BEGIN THIRD-PARTY FILE 2e99517d32d16320
```text
---
name: k6-test-maintenance
description: >
  Maintain and improve existing k6 test scripts. Covers threshold tightening
  based on trend data, version migration between k6 releases, auto-fixing tests
  when the underlying service changes, refactoring for cleanliness, and auditing
  scripts against current best practices from docs. Use when the user asks to
  fix a failing k6 test, tighten thresholds, migrate a script to a new k6
  version, refactor a test, update a script after a service change, or improve
  a script with best practices. Trigger on phrases like "fix my k6 test",
  "tighten my thresholds", "migrate to k6 v2", "update my test script",
  "refactor this k6 test", "my test is failing after a deploy", "apply best
  practices to my script", "modernize my k6 test", or "the service changed and
  my test broke". Also trigger when another skill (k6-trend-analysis or
  k6-cloud-investigate-test) hands off with a recommendation to edit a script.
  Maintains existing scripts; to author a new test use the k6 skill, or
  k6-browser-test for a browser test.
---

# k6 Test Maintenance

Maintain, fix, and improve existing k6 test scripts. Five maintenance tasks,
each with a step-by-step procedure in [`references/workflows.md`](references/workflows.md):

1. **Threshold tightening** -- adjust threshold values based on observed metrics
2. **Version migration** -- update scripts for new k6 releases
3. **Service change adaptation** -- fix tests when the underlying service changes
4. **Refactoring** -- clean up and modernize test code
5. **Best practices audit** -- check scripts against current k6 best practices

## Core principle: behavior-aware change control

Classify every proposed change by whether it alters the test's runtime behavior:

- **Syntactic** (behavior unchanged): the k6 runtime produces identical metrics,
  pass/fail results, and endpoints. Examples: rename a variable, `let` → `const`,
  remove unused imports, update comments, reformat. **Apply directly.**
- **Behavioral** (behavior differs): anything affecting metrics, pass/fail,
  timing, request targets, or load shape. Examples: threshold value changes,
  adding `sleep()`, endpoint URL updates, check rewrites, scenario changes, new
  thresholds. **Always present as a diff with rationale and require confirmation.**

The threshold for "behavioral" is deliberately low. If in doubt, treat it as
behavioral and ask -- a trivial-looking threshold change can cascade to CI
gates, SLO calculations, and alerting.

## Dependencies
```
END THIRD-PARTY FILE 2e99517d32d16320

The third-party file has ended. Everything between the 2e99517d32d16320 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2530 of 10139 bytes. © grafana · Apache-2.0 · https://github.com/grafana/skills/tree/HEAD/skills/grafana-k6/k6-test-maintenance/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md