Verified SOP & TutorialAudited Score 98/100

The Complete Production SOP: How to Deploy and Run Web Vitals & Chrome DevTools Profiler in Autonomous AI Agents

Step-by-step SOP to install and run the Web Vitals & Chrome DevTools Profiler skill in Codex, Claude Code, and Cursor to resolve LCP, CLS, and INP bottlenecks.

View 1-Click Spec

Target Runtimes:codexclaude-codecursorwindsurf

5 min read • Updated for 2026

Technical Overview & Architectural Context

Autonomous coding agents like Claude Code, Codex, and Cursor frequently fail when attempting frontend performance optimizations. Without deterministic profiling standards, agents attempt naive micro-optimizations—such as wrapping random callbacks in useMemo, altering CSS animations without layout stability analysis, or lazy-loading above-the-fold hero images. These unguided edits often degrade Largest Contentful Paint (LCP), induce Cumulative Layout Shift (CLS), and amplify Interaction to Next Paint (INP) latency through synchronous task scheduling. The Web Vitals & Chrome DevTools Profiler skill equips coding agents with a structured diagnostic protocol. It directs the agent to analyze synthetic and real-user trace data, inspect main-thread long tasks exceeding 50ms, audit font swap definitions, and measure DOM tree depth before touching source code. By enforcing strict verification gates (such as Lighthouse CI checks and flame chart parsing), this skill ensures performance refactors measurably improve user-centric metrics without introducing regressions.

Prerequisites & Environment Requirements

Codex CLI/Desktop, Claude Code CLI, Cursor, or Windsurf installed with workspace permissions

Node.js 20+ LTS with pnpm or npm installed in workspace sandbox

Google Chrome or Chromium installed locally for headless DevTools profiling

@lhci/cli or lighthouse installed globally or locally as a dev dependency

Verified Search Intents & Long-Tail Queries Solved

SEO Audit Score: 98/100

This operational tutorial is engineered to provide deterministic solutions for these developer search queries:

#install performance-profiler in cursor ide#claude code core web vitals profiler rules#codex devtools performance-profiler setup tutorial#how to fix inp performance-profiler agent execution error#deterministic fullstack web vitals agent SOP#optimize lcp cls inp with autonomous coding agent#chrome devtools trace profiler prompt triggers for claude code#performance-profiler sandbox permissions and security score

Step-by-Step Execution Playbook

Local Environment Setup & SKILL.md Mounting

Mount the performance-profiler SKILL.md manifest into the agent runtime directory.

Autonomous runtimes such as Claude Code and Cursor look for procedural rules in `.agent/skills/` or `.claude/skills/`. Creating this hierarchy and injecting the official performance-profiler skill establishes declarative triggers and execution constraints before file parsing starts.

Terminal Command

mkdir -p .agent/skills/performance-profiler && curl -fsSL https://askills.dev/api/skills/performance-profiler/raw -o .agent/skills/performance-profiler/SKILL.md

.agent/skills/performance-profiler/SKILL.md

---
name: "performance-profiler"
description: "Optimize Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), and Interaction to Next Paint (INP)."
category: "fullstack"
---

# Web Vitals & Chrome DevTools Profiler Rules

1. Before modifying UI components, extract a performance baseline using headless Lighthouse or DevTools traces.
2. Prioritize high-impact bottlenecks: Main-Thread tasks > 50ms (INP), un-sized media (CLS), critical rendering path blockers (LCP).
3. Re-run trace benchmarks after every change to prevent regressions.

Production Pro-Tip

Keep the SKILL.md file compact and reference external trace artifacts by path rather than piping multi-megabyte JSON traces directly into the LLM context window.

Sandbox Gotcha

Ensure directory permissions grant read/write access to your agent sandbox; non-root Docker sandboxes often default mounted `.agent` directories to read-only.

Environment Secrets & Dependency Validation

Configure headless browser flags and install core profiling dependencies.

Chrome DevTools profiling requires headless Chromium execution permissions. Configure environment variables such as CHROME_PATH and flags to prevent sandbox failures in headless continuous integration or agent sub-shells.

Terminal Command

npm install -D lighthouse @lhci/cli puppeteer-core && export CHROME_PATH=$(which google-chrome || which chromium)

Production Pro-Tip

Set `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true` if your agent environment already includes a system Chromium binary to save runtime disk space and bootstrap time.

Sandbox Gotcha

Running headless Chrome in containerized agent sandboxes requires `--no-sandbox` and `--disable-dev-shm-usage` flags to prevent unexpected SIGTRAP crashes.

Intent Matching & Trigger Invocation

Activate the profiler using structured prompts matching the skill triggers.

Instruct the autonomous agent with an explicit performance optimization command. The runtime matches the skill frontmatter keywords ('LCP', 'INP', 'CLS', 'performance-profiler') and loads the procedural rules into active context.

Production Pro-Tip

Include the specific target URL, viewport dimensions (mobile vs desktop), and the targeted metric in the prompt to reduce exploratory token overhead.

Sandbox Gotcha

Omitting the environment context (e.g., local dev server vs production build) may cause the agent to profile unminified dev bundles, producing inaccurate metrics.

Verification, Linting & Output Quality Gate

Execute automated headless profiling to guarantee metric improvements before accepting code.

The skill mandates a post-refactor validation step. The agent must trigger a synthetic audit or test runner to confirm that the changes did not break layout or increase bundle size.

Terminal Command

npx lhci collect --url=http://localhost:3000 --numberOfRuns=3 && npx lhci assert

Production Pro-Tip

Always inspect the git diff to ensure the agent did not bypass performance bottlenecks by omitting needed analytics scripts or essential stylesheet imports.

Sandbox Gotcha

Local dev servers with Hot Module Replacement (HMR) active add overhead to INP measurements. Always test against a built preview (`pnpm build && pnpm start`).

Real-World Scenario: Eliminating INP spikes caused by React re-renders on a dashboard datagrid

Tested Trigger Prompt (Feed directly into Codex, Claude, or Cursor):

“Analyze our DataGrid component at src/components/DataGrid.tsx using the performance-profiler skill. We have high INP (> 350ms) during cell edits. Identify long main-thread tasks, optimize the interaction, and verify that INP drops under 100ms.”

Deterministic Agent Verification Pipeline:

Agent inspects .agent/skills/performance-profiler/SKILL.md to load DevTools profiling procedures.

Agent executes a headless trace or simulated typing interaction using Puppeteer/Lighthouse to record baseline input delay and processing duration.

Agent discovers redundant re-rendering of 1,000 unvirtualized cells triggered by unbatched state updates in cell change handlers.

Agent refactors DataGrid.tsx using `@tanstack/react-virtual` and delegates non-critical updates to `startTransition` or web workers.

Agent spins up a production build, re-runs the trace, and verifies that main-thread blocking time during interaction dropped from 380ms to 42ms.

Runtime Troubleshooting & Failure Modes

Error: Error: Failed to launch the browser process: zygote_host_impl_linux.cc: No usable sandbox! Update your kernel or see...

Root Cause: Headless Chrome was executed by the agent inside an unprivileged Docker or Linux sandbox without disabling the setuid sandbox.

Resolution Command / Fix:

export CHROME_FLAGS="--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage --headless=new"

Error: LHError: NO_LCP: The page did not display any content fulfilling the Largest Contentful Paint criteria.

Root Cause: The agent attempted to measure a client-side rendered page before authentication or initial bundle hydration completed, timing out the Lighthouse audit.

Resolution Command / Fix:

npx lhci collect --url=http://localhost:3000/dashboard --settings.maxWaitForLoad=45000 --settings.pauseAfterFcpMs=2000

Frequently Asked Questions (Web Vitals & Chrome DevTools Profiler SOP)

Q:Can I use Web Vitals & Chrome DevTools Profiler across Codex, Claude Code, and Cursor simultaneously?

Yes. The SKILL.md specification is runtime-agnostic. Placing the manifest in `.agent/skills/performance-profiler` or linking it inside runtime config files (such as `.cursorrules` or `.claude.json`) enables consistent procedural adherence across all modern AI environments.

Q:How does Web Vitals & Chrome DevTools Profiler prevent context window overflow during long agent sessions?

The skill mandates writing raw trace logs and flame charts to disk and instructs the agent to query summary metrics via CLI commands (such as Lighthouse assertions or custom parse scripts) instead of printing raw DevTools JSON dumps into chat.

Q:Does this skill require escalated root or container permissions?

No. The skill maintains a 98/100 security score and runs entirely in user-space workspace directories. Headless Chrome requires standard unprivileged user flags (`--no-sandbox`) within containerized sandboxes.

Ready to equip your autonomous agent with Web Vitals & Chrome DevTools Profiler?

Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.

Get 1-Click Install Spec