Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Bootstrap your editor with k6 x agent
The k6 x agent command scaffolds an AI-assisted k6 testing workflow in your project. A single invocation drops portable SKILL.md bundles into your editor’s expected locations and registers the k6 MCP server in your editor’s MCP configuration — so you don’t have to author MCP client configuration by hand.
k6 x agent is a subcommand extension shipped with k6. The first time you run it, k6 transparently fetches the extension; subsequent invocations start immediately.
What k6 x agent init does for you
For each editor you target, init will:
- Install bundled skills: Write portable
SKILL.mdfiles (or the editor’s equivalent rule format) into the locations your editor reads from. Skills auto-activate based on user intent, for example “write a smoke test” or “convert this Playwright script”. - Register the k6 MCP server: Surgically merge a
k6entry into the editor’s MCP config (.mcp.json,.cursor/mcp.json,.vscode/mcp.json, …) so your assistant can callvalidate_script,run_script, and the rest of the k6 MCP tools. - Stay out of your way: Files written by
k6 x agentcarry an ownership marker. Re-runninginitis idempotent. Files you’ve edited locally are never overwritten unless you pass--force.
Prerequisites
- k6 v2.0 or later on your
PATH(install k6). - A project directory you want to scaffold into (run the command from the project root).
- One of the editors in Supported targets.
Quickstart
From the root of your k6 project:
k6 x agent init claude-code # one editor
k6 x agent init claude-code cursor # several
k6 x agent init --all # every supported target
k6 x agent status # verify what got installedThen open your editor and ask it to plan or write a k6 test. The bundled skills auto-activate based on intent — for example, “write a smoke test for the login flow” or “convert this Playwright script to k6”.
Note
Before any disk writes, you can run
k6 x agent init --dry-run <target>to preview every file the command would create or merge, with byte counts and write modes.
Supported targets
Note
Cline’s MCP configuration is global rather than project-scoped.
k6 x agent init clineprints the JSON snippet you need to paste intocline_mcp_settings.jsoninstead of writing it for you.
If your editor isn’t listed, see Editors not supported by k6 x agent below for manual setup.
Bundled skills
The skills below are embedded in the binary and installed for every target. They are written in portable SKILL.md format and auto-activate when your assistant detects matching intent in the conversation.
Run k6 x agent skills show <name> to print a skill’s full SKILL.md to stdout.
Commands
init flags
Example status output
Agent installation status
[+] Claude Code
- .mcp.json detected
[-] Cursor
- Missing: .cursor/mcp.json
- Hint: k6 x agent init cursor
[+] k6 MCP support
- Found at /usr/local/bin/k6A [+] next to k6 MCP support confirms that the editor will be able to launch k6 x mcp when your assistant connects.
Safety
k6 x agent is conservative about what it writes:
- It never creates or modifies user-owned top-level files such as
AGENTS.mdorREADME.md. - For shared JSON config files (
.mcp.json,.cursor/mcp.json,.vscode/mcp.json,opencode.json), only thek6entry is touched. Other servers and unrelated keys in the file are preserved. - Files inside
xk6-subcommand-agent-owned folders are stamped with an ownership marker. Re-runninginitis idempotent, and--forceis required to overwrite a file you have edited locally. --dry-runprints the full plan before any disk write, so you can review every path and write mode up front.
For the full design, see xk6-subcommand-agent/docs/DESIGN.md.
Troubleshooting
folder already existsor file collision — re-run with--forceto overwrite managed files.k6 x agentnever deletes files it does not own.- Status shows
[-] k6 MCP support—k6is not on the editor’sPATH. Install k6 from Install k6, and make sure your editor is launched in a shell that can find it. - Cline MCP entry missing — Cline’s MCP configuration is global. Copy the JSON snippet printed by
k6 x agent init clineintocline_mcp_settings.json. - Unsupported editor — see Editors not supported by
k6 x agentfor manual MCP setup guidance.
Editors not supported by k6 x agent
If your editor or MCP client isn’t in the Supported targets table, you can still register the k6 MCP server manually — it works with any client that speaks stdio.
Before you start:
- If you launch the server via the k6 subcommand (
k6 x mcp), ensurek6is on yourPATH. - If you launch the standalone
mcp-k6binary, ensure bothmcp-k6andk6are on yourPATH. - If you launch the server in Docker, ensure Docker is installed and running.
How MCP works
The Model Context Protocol (MCP) is a standard way for AI assistants to communicate with external tools. At its core, an MCP server is a program that:
- Reads JSON-RPC messages from stdin.
- Writes JSON-RPC responses to stdout.
- Advertises tools, resources, and prompts that the AI can use.
When you configure an MCP client, you define the command it should launch — the MCP server binary — and the client communicates with it over stdio.
What to configure
Most MCP clients ask for the following information:
Consult your client’s documentation for the exact configuration file location and format. Look for sections about “MCP servers”, “tool servers”, or “stdio servers”.
Next steps
- Learn what your assistant can do once the server is wired up: Tools, prompts, and resources.

