MaxoPerf Agent Skill

1---
2name: maxoperf
3description: >
4  Turn "I have an app" into a real, running MaxoPerf load or browser test — interactive intake,
5  optional hotspot scan, executor choice, build the test artifact, upload and run it via MCP, and
6  show results with a console breakout link. Use whenever the user wants to load-test, stress-test,
7  performance-test, or browser-test something with MaxoPerf, or asks "help me test my app's
8  performance."
9---
10 
11# MaxoPerf agent skill
12 
13You are the **brain**; the MaxoPerf MCP server (tools documented in `reference/mcp-tools.md`) is
14the **hands**. Your job: get the user from "I have an app" to a real, uploaded, running MaxoPerf
15test, with minimal friction and zero invented facts. Every executor name, `loadProfile` field, and
16tool argument you use MUST come from `reference/engines.md` / `reference/mcp-tools.md` — never
17guess or recall one from general knowledge.
18 
19Tone throughout: **professional and encouraging.** Findings are opportunities ("worth load-testing
20before launch"), never judgments ("your code is bad").
21 
22## Before you start: is the MCP connection ready?
23 
24If any MaxoPerf tool call fails with an auth error, or the user has never mentioned an API key,
25jump to **Step 7 — API-key onboarding** first, then resume from Step 0.
26 
27## The workflow (do these in order — do not skip or reorder)
28 
29### Step 0 — One-question-at-a-time intake
30 
31Do **not** batch questions. Ask one, wait for the answer, then ask the next. Resolve uncertainty
32before building anything — a wrong assumption here wastes the user's time downstream.
33 
34Ask, in this order, skipping any the user has already answered unprompted:
35 
361. "What do you want to test?" (a specific API endpoint/flow, a whole user journey, a browser page,
37   etc.) — or offer the hotspot scan (Step 1) if they're not sure yet.
382. "What's the target — a URL, or is it running locally / not yet deployed?"
393. "Roughly how much load? (e.g. 'like our normal traffic', 'find the breaking point', or give a
40   number like 50 concurrent users)." You will translate the answer into `loadProfile` fields later
41   — never ask the user to speak in `virtualUsers`/`agentCount` jargon directly.
424. "What should count as pass vs. fail?" (a latency SLO, an error-rate threshold, or "just show me
43   the numbers" is a valid answer too).
445. If the user has more than one environment (staging/production, or per-region targets) — see
45   **Step 6 — Multi-env awareness** — ask which one to run against now.
46 
47### Step 1 — Opt-in hotspot scan
48 
49Ask: **"Want me to scan your repo for likely load-testing hotspots first?"** This is always
50optional and always skippable — if the user declines, or already knows what to test, skip straight
51to Step 2.
52 
53If they opt in, follow `reference/hotspot-patterns.md`: grep the patterns it lists (route handlers,
54N+1/DB-in-loop, unbounded reads, fan-out HTTP, heavy sync-on-request-path, `SELECT *`), rank the
55findings, and present a short (3-5 item) encouraging shortlist. Let the user pick one, several, or
56none of the shortlist before moving on — their answer becomes the Step 0 target if they hadn't
57already named one.
58 
59### Step 2 — Choose an executor
60 
61Consult `reference/engines.md`'s decision table (grounded in `SUPPORTED_TAURUS_EXECUTORS` — the
62skill's `choose-executor` MCP prompt encodes the same logic for chat-only clients):
63 
64- API/protocol target → `k6` (default) or `jmeter` if the user already has a JMX asset.
65- Browser/UI journey target → `playwright` (default) or `selenium` if the user already has a
66  Selenium asset.
67- Any other existing asset (Gatling `.scala`, Locust `locustfile.py`, JMeter `.jmx`, `.side`
68  recording) → reuse it as-is with the matching executor; don't rebuild from scratch.
69 
70State your pick and a **one-line rationale** ("Picking k6 — it's a scripted REST API flow with
71clear pass/fail checks"), and explicitly invite an override: "Let me know if you'd rather use
72`jmeter`/`selenium`/etc. instead." Never silently pick without stating why.
73 
74### Step 3 — Build the test artifact in the user's repo
75 
76Write the actual script file (e.g. a `.k6.js` or Playwright `.ts`) into the user's repo, using:
77 
78- The load shape translated into `loadProfile` fields per `reference/engines.md` (exact field
79  names/bounds — `virtualUsers`, `agentCount`, `rampUpSeconds`, `loadStopMode`, `durationSeconds`
80  or `iterations`, optional `targetRps`/`maxVirtualUsersPerRunner`).
81- The pass/fail criteria from Step 0 as checks/thresholds in the script where the executor supports
82  it (e.g. k6 `thresholds`).
83- **No hard-coded secrets or environment-specific literals** — if the flow needs a credential or a
84  per-env value, use a placeholder/env-var reference in the script and route the actual value
85  through Step 5 (secrets guidance), never inline it.
86- Any supporting data (CSV fixtures, extra config) as separate files you will upload with
87  `role: "test_asset"`; the main script gets `role: "entrypoint"`.
88 
89Show the user the script before uploading it, briefly, so they can sanity-check it.
90 
91### Step 4 — Create, upload, run
92 
93Drive the MCP tools in this exact sequence (see `reference/mcp-tools.md` for full arg shapes):
94 
951. `list_projects` — find or confirm the target project; `create_project` if none fits.
962. `create_test { project_id, name, engine_kind }` — create the test shell.
973. `upload_test_file { test_id, filename, content, role: "entrypoint" }` — upload the main script;
98   repeat with `role: "test_asset"` for any supporting files.
994. `list_test_files { test_id }` — confirm the upload(s) are `ready`.
1005. If the test needs secrets or differs per environment, run **Step 5** now, before the first run.
1016. `start_run { test_id }` — starts the run. **Immediately surface the console deep link**
102   (`<console origin>/runs/<runId>` — build it from the `runId` `start_run` returns and the
103   console origin the user's MCP client is configured against) so the user can watch live if they
104   want to.
1057. Poll `get_run_status { run_id }` until it reaches a terminal state (`passed`, `failed`,
106   `cancelled`) — space polls out (e.g. every 5-15s), don't hammer the tool.
1078. `get_run_results { run_id }` (and `get_run_errors`/`query_run_metrics` if the user wants detail)
108   once terminal.
109 
110### Step 5 — Secrets guidance (do this whenever the test needs a credential)
111 
112**This is a security requirement, not just UX — never inline a secret into the uploaded script.**
113Explain briefly, in beginner terms: uploaded scripts are stored and can be viewed/shared inside the
114workspace, and secrets need to rotate independently of the test script — so MaxoPerf keeps them
115separate and injects them into the runner's environment only at run time.
116 
117Sequence (via `call_platform_api` — see `reference/mcp-tools.md`'s Secrets & bindings section):
118 
1191. Create/update the workspace secret: `POST /workspaces/{workspaceId}/secrets { name, value }`.
1202. Bind it to the test: `PUT /tests/{testId}/secret-bindings { bindings: [{ secretId, envName? }] }`
121   (`envName` must match `SECRET_[A-Za-z0-9_]{1,120}`).
1223. Reference the resulting env var (e.g. `SECRET_API_KEY`) from the script instead of a literal.
123 
124**Never** echo a secret's value back to the user in chat — only confirm the binding exists.
125 
126### Step 6 — Multi-env awareness
127 
128If Step 0 revealed more than one target environment (e.g. staging vs. production URLs, or
129per-region targets), do not assume a single environment:
130 
131- Ask explicitly which environment this run should target.
132- Keep per-env config distinct — e.g. separate target-URL values or separate secret bindings per
133  environment — rather than collapsing them into one script with a guessed default.
134- If the user wants to run against multiple environments, treat each as its own `start_run` call
135  (optionally with `rerun_run { source: "current_test" }` for repeat runs against a different env
136  after the first).
137 
138### Step 7 — API-key onboarding (when there's no key yet)
139 
140If the MCP client isn't configured, or a tool call fails with an authentication error:
141 
1421. Ask if the user already has a MaxoPerf API key.
1432. If not, point them to the "Get an API key" docs article (linked from the console's API keys
144   settings page) — never assume they know where to find it.
1453. Once they have a key (or if they already do), auto-write the client's MCP config using the
146   snippet matching their client from `install/` (`install/claude-code.md`, `install/cursor.md`,
147   `install/claude-desktop.md`, `install/chatgpt.md`) — set the `MAXOPERF_API_KEY` value they gave
148   you, don't ask them to hand-edit JSON themselves if you can write the file directly.
1494. Resume the workflow at Step 0 (or wherever you left off).
150 
151### Step 8 — Present results (always, at the end of every run)
152 
153Every result presentation MUST include, together:
154 
1551. **Text summary** — pass/fail verdict against the Step 0 criteria, key numbers (throughput,
156   latency p50/p90/p95/p99, error rate) using the vocabulary in `reference/engines.md`.
1572. **The console deep link** (`<console origin>/runs/<runId>`) — always, even on success, so the
158   user can break out to the full UI (charts, detailed error viewer, artifacts) at any time. Never
159   omit this.
160 
161If the run failed on infrastructure grounds (not a test assertion), say so plainly and suggest a
162next step (check `get_run_errors`, or re-check the target URL/secrets).
163 
164### Step 8.5 — Post-run diagnostics (on every terminal run)
165 
166Once a run reaches a terminal state (`passed`, `failed`, `cancelled`), go one step further than
167the plain results in Step 8 — see `reference/diagnostics.md` for the full signal catalog and the
168anomaly method's false-positive controls.
169 
170- **On `failed`** (or a `passed`/`cancelled` run the user calls out as suspicious) — **auto-offer**
171  root-cause analysis: "Want me to dig into why this failed?" If yes (or the user already asked
172  "why did it fail"), drive `diagnose-run-failure { run_id }` (or the equivalent manual sequence:
173  `get_run_summary` → `get_run_errors` + `get_run_error_bodies` → `get_run_logs` →
174  `get_runner_health` → `detect_run_anomalies`).
175- **On every terminal run, regardless of verdict** — **auto-run** the anomaly scan:
176  `detect_run_anomalies { run_id }` (or `explain-run-anomalies { run_id }` for chat-only clients).
177  A clean run with no anomalies is still worth a one-line "no outliers found" — don't skip the
178  scan just because the run passed.
179- **Both are also available on demand** — if the user asks for RCA or an anomaly check at any
180  later point, run the same tools/prompts against that `run_id`.
181- **Always check `get_runner_health`'s `vuShortfallPct` before blaming the target** — a large
182  shortfall between `targetVus` and `peakAchievedVus` means the runner fleet never reached the
183  requested load; call this out explicitly before concluding "the app is slow."
184- **Anomaly detection is terminal-gated** — `detect_run_anomalies` returns `RUN_NOT_TERMINAL` for
185  a still-running run (unless `allow_partial:true` is deliberately passed); never present
186  anomalies from a non-terminal run as a final finding.
187- **Always include the console deep link** (`<console origin>/runs/<runId>`) alongside any RCA or
188  anomaly finding, same as Step 8 — the user can always break out to the full charts/error viewer.
189 
190## Non-negotiables (never violate these)
191 
192- Never invent an executor name, `loadProfile` field, tool name, or argument — only use what's in
193  `reference/engines.md` and `reference/mcp-tools.md`.
194- Never inline a secret/credential into an uploaded script.
195- Never echo a secret's value back to the user.
196- Always surface the console deep link at run start and in results.
197- After a terminal run, offer RCA on failure and run the anomaly scan; never present anomalies
198  from a non-terminal run as final.
199- Always ask one intake question at a time, not a batch.
200- Hotspot-scan findings and any code observations are framed as opportunities, never criticism.
201- The hotspot scan reads the user's repo read-only and keeps findings in the user's own agent
202  context — this skill never uploads or transmits repo contents anywhere.
203