2btwist/dotagents/perf-harness-init
Claude Code and agent skill by 2btwist/dotagents
- community
Checking that the SKILL.md file is still in the repository.
Scaffold the full performance harness into any React/web project (Next.js, Vite-React, or plain web). Installs the measurement engines, copies the configs + the perf-check verifier CLI from this skill's templates, sets telemetry-off, wires CI, and calibrates budgets. Invoke in a fresh repo to make it perf-gated. Triggers "set up the perf harness", "add perf gating to this project", "init perf harness".
Install
npx vskill@latest install 2btwist/dotagents/perf-harness-initSKILL.md
The same SKILL.md was published earlier as 2btwist/dotagents/perf-harness-init.
perf-harness-init
Turns any React/web repo into a perf-gated project using the layered harness (design: portfolio specs/plans/2026-06-22-groundwork-perf-harness.md). All resources live in this skill's templates/ dir — copy, adapt, calibrate.
Scope check (do first)
- ✅ Web apps: Next.js, Vite-React, plain web. The browser layer (Lighthouse,
Playwright, CWV, CPU profiles) works for any web app.
- ⚠️ The templates are written React-first. Three pieces are React-only: the
React Scan overlay, perf/render-count.test.tsx, and the Vitest component layer (vitest.config.ts's @vitejs/plugin-react, vitest.setup.ts's Testing Library cleanup). Step 3 says what a non-React repo does with each.
- ❌ Not for backend/CLI/library projects (no page to measure). Stop and say so.
Detect the stack: read package.json + next.config.* / vite.config.*.
Steps
- Install deps (respect the repo's package manager; use
socketprefix if available):
- Core:
vitest vite jsdom @playwright/test @axe-core/playwright @lhci/cli size-limit @size-limit/file tsx lighthouse
(@axe-core/playwright is imported by e2e/invariants/a11y.spec.ts — without it the a11y invariant fails to load, not to assert.)
- React:
@vitejs/plugin-react @testing-library/react @testing-library/dom react-scan eslint-plugin-react-hooks - Next.js only:
@next/bundle-analyzer; Vite only:rollup-plugin-visualizer - If deployed on Vercel:
@vercel/speed-insights(runtime dep) - Then
pnpm exec playwright install chromium(ignore-scripts skips the auto-download).
- Copy templates from
<this skill dir>/templates/into the repo root, adapting:
vitest.config.ts,vitest.setup.ts,playwright.config.ts,lighthouserc.js,.size-limit.js,budgets.json,perf/,tools/perf-check/,e2e/,PERF.md.github-workflows/perf.yml→.github/workflows/perf.yml.
- Adapt per stack:
- Next.js: keep
.size-limit.jspath.next/static/chunks/**/*.js; serve =next start; wrapnext.configwith@next/bundle-analyzer. - Vite:
.size-limit.jspathdist/assets/*.js; serve =vite preview --port 3000;lighthouserc.jsstartServerCommand =vite preview --port 3000; swap analyzer forrollup-plugin-visualizer. - Non-React web: drop the
react()plugin and thepluginskey from
vitest.config.ts, drop setupFiles and do not copy vitest.setup.ts, and do not copy perf/render-count.test.tsx. The browser layer (e2e/, Lighthouse, size-limit, perf-check) is unchanged.
- Update
playwright.config.tswebServer command +lighthouserc.jsto the repo's build/serve. - Fill the smoke test's title.
e2e/invariants/smoke.spec.tsships with a
__PROJECT_TITLE__ placeholder that fails until replaced. Put this project's real <title> there, as a regex specific enough that an empty render fails it. A pattern matching any title would stay green over a blank page.
- Wire scripts into
package.json:test,test:watch,e2e,e2e:perf,size,lh,analyze,perf:check,perf:calibrate,perf(copy fromtemplates/PERF.md's reference table). - Telemetry off: set
NO_TELEMETRY=1,NEXT_TELEMETRY_DISABLED=1,DO_NOT_TRACK=1wherever this harness holds project env (Claude Code:.claude/settings.jsonenv), and in.github/workflows/perf.ymlso CI measures the same thing; runpnpm exec next telemetry disableif Next. Telemetry calls are network work inside the measured window. - React only: add dev-only React Scan init in the root client provider/layout (guard
NODE_ENV==="development"); raisereact-hooks/exhaustive-depsto error. - Calibrate:
pnpm build→ serve →pnpm perf:calibrate→ stop. Fillsbudgets.jsonfrom measured prod values (measure-then-ratchet). - Verify:
pnpm test,pnpm lint,pnpm buildgreen;pnpm perf:check --jsonemits a verdict.
Known gotchas (already solved in the templates)
perf-checkshells out (child_process) to lighthouse + size-limit — the node APIs break under tsx/esbuild (__name, unicorn-magic). Don't "fix" them back to imports.- Use
@size-limit/file(notpreset-app) — preset-app needs a Chromium it can't get under ignore-scripts. - Playwright transpiles to CJS — no
import.meta.urlin specs (read files via cwd).
Composes with
- `perf-loop` skill — the diff-driven autonomous test+optimize run loop (this skill only sets up the gates it polls).
- `mcp__MCP_DOCKER__browser_*` — the agent's live browser tools for exploration (no third-party browser-testing dep needed; we removed Expect in favor of these).
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingoptional/perf/skills/perf-harness-init/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/2btwist/dotagents/perf-harness-init)