The Complete Production SOP: How to Deploy and Run Lighthouse CI Performance Budget Gates in PRs in Autonomous AI Agents
Step-by-step SOP to install and run Lighthouse CI Performance Budget Gates in Codex, Claude Code, and Cursor. Prevent PR Core Web Vitals regressions.
Technical Overview & Architectural Context
Without strict performance budget skills, autonomous AI coding agents regularly introduce regressions when adding modern frontend dependencies, client-side analytics scripts, and unoptimized layout-shifting components. Because typical agent testing suites only assert functional unit correctness and TypeScript compilation, agents unknowingly merge changes that destroy Cumulative Layout Shift (CLS), blow past Largest Contentful Paint (LCP) limits, and degrade First Input Delay (FID) / Interaction to Next Paint (INP). The 'lighthouse-ci-budget-performance-gate' skill enforces deterministic boundaries across the development lifecycle. It forces the coding agent to define explicit, numeric threshold gates inside a lighthouserc.json specification, wire up ephemeral local static servers, execute multiple audit runs to smooth out statistical variance, and halt pull request delivery if performance budgets fall below acceptable score thresholds (such as 0.90 for performance categories or 2500ms for LCP).
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules.
Autonomous coding runtimes like Claude Code, Cursor, Codex, and Windsurf inspect standard skill registries under the `.agents/skills` or `.cursor/rules` workspace path. Injecting this skill instructs the agent engine to intercept frontend builds and apply strict Lighthouse CI verification assertions whenever performance-critical PR changes are authored.
mkdir -p .agents/skills/lighthouse-ci-budget-performance-gate && curl -fsSL https://askills.dev/api/skills/lighthouse-ci-budget-performance-gate/raw -o .agents/skills/lighthouse-ci-budget-performance-gate/SKILL.md---
name: "lighthouse-ci-budget-performance-gate"
description: "Automate Core Web Vitals audits and prevent performance regressions in pull requests."
metadata:
author: "Google Chrome"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "configure lighthouserc.json"
- "enforce performance budget lhci"
- "core web vitals ci gate"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Mounting the skill locally inside `.agents/skills` avoids dumping large performance rule manuals into the persistent system prompt, saving hundreds of tokens per conversational turn.
Ensure that your agent runtime has permission to read `.agents/skills/` without being blocked by restricted file-access configurations in Cursor or Codex settings.
Authoring lighthouserc.json and CI Budget Matrix
Direct the agent to generate standard Lighthouse CI configurations targeting Core Web Vitals.
The agent must generate a root `lighthouserc.json` configured with assertions that match your production SLOs. The configuration specifies a static serve command or dev server start command, multiple runs to negate CPU fluctuations, and hard error thresholds on critical performance vectors like LCP and CLS.
npm install --save-dev @lhci/cli{
"ci": {
"collect": {
"numberOfRuns": 3,
"startServerCommand": "npm run start",
"startServerReadyPattern": "ready on",
"url": ["http://localhost:3000/"]
},
"assert": {
"assertions": {
"categories:performance": ["error", { "minScore": 0.9 }],
"largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
"total-blocking-time": ["error", { "maxNumericValue": 300 }]
}
},
"upload": {
"target": "temporary-public-storage"
}
}
}Configure `startServerReadyPattern` accurately so Lighthouse does not launch audits against a port that is still warming up or compiling bundles.
Avoid setting `minScore: 1.0` in CI environments; headless CI virtual CPUs exhibit clock variance that triggers false positives unless realistic tolerance margins are set.
Triggering the Performance Gate in Agent Workflows
Invoke deterministic budget enforcement during feature implementation using frontline triggers.
Issue natural language prompts containing triggers specified in the skill frontmatter. The agent will recognize the intent, verify that the frontend build artifact exists, validate the `lighthouserc.json` rules, and run the LHCI collection and assertion routines.
npx lhci autorun --config=./lighthouserc.jsonRun `lhci autorun` locally before submitting pull requests to detect large image assets or uncompressed vendor bundles early.
In headless Linux environments or CI workers, ensure `chrome-headless-shell` or `chromium` is installed; missing dependencies cause LHCI to fail silently with empty output directories.
GitHub Actions Workflow Integration & PR Status Gate
Integrate the LHCI assertion gate into automated CI pipelines to block failing pull requests.
Direct the agent to generate a `.github/workflows/lighthouse-gate.yml` action. The action checks out the PR branch, builds production assets, runs `lhci autorun`, and fails the pull request status check if any assertion drops below the budget configured in `lighthouserc.json`.
git add lighthouserc.json .github/workflows/lighthouse-gate.yml && git commit -m 'ci: enforce Lighthouse Core Web Vitals budget gate'name: Core Web Vitals CI Gate
on: [pull_request]
jobs:
lhci:
name: Lighthouse Audit
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- run: npm ci
- run: npm run build
- name: Run Lighthouse CI
run: npx @lhci/cli autorunInspect the generated Markdown summary from `@lhci/cli autorun` and configure your agent to post it directly into the PR review thread for instant transparency.
Ensure the application server stops cleanly after LHCI audits complete; hanging server child processes can stall CI jobs until runner timeout.
Real-World Scenario: Prevent Performance Regressions in an E-Commerce Landing Page PR
“We are adding an interactive product carousel and dynamic analytics scripts to the landing page. Enforce performance budget lhci and configure lighthouserc.json to ensure LCP stays below 2500ms and CLS remains under 0.1 before this PR can merge.”
Runtime Troubleshooting & Failure Modes
Root Cause: A newly introduced hero banner, uncompressed media asset, or client-side hydrated widget delayed above-the-fold rendering beyond the maximum numeric value.
Use next/image or convert assets to WebP/AVIF with explicit dimensions and preloading: <link rel="preload" href="/hero.webp" as="image" type="image/webp" fetchpriority="high">Root Cause: The server initialization command specified in lighthouserc.json failed to launch or startServerReadyPattern did not match stdout output before timeout.
Update lighthouserc.json with extended timeout and correct pattern: "startServerReadyTimeout": 30000, "startServerReadyPattern": "(Ready in|started server on|Listening on)"Frequently Asked Questions (Lighthouse CI Performance Budget Gates in PRs SOP)
Q:Can I use Lighthouse CI Performance Budget Gates in PRs across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill adheres to the open SKILL.md specification. Once committed to your repository under `.agents/skills/lighthouse-ci-budget-performance-gate/SKILL.md` or linked into your global runtime configuration, it is recognized uniformly across Codex, Claude Code CLI, Cursor, and Windsurf.
Q:How does Lighthouse CI Performance Budget Gates in PRs prevent context window overflow during long agent sessions?
Instead of prompting the agent with hundreds of lines detailing Core Web Vitals definitions and diagnostic tips, the skill provides a modular, declarative SOP. The agent activates the lighthouserc.json generation rules only when performance triggers match, preserving token bandwidth for application code.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100 and only requires workspace-level file access (`fs_write: workspace`) to create configuration files and CI workflows. It forbids unauthorized shell execution and network access outside standard project boundaries.
Ready to equip your autonomous agent with Lighthouse CI Performance Budget Gates in PRs?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.