Preface¶

Front-end performance optimization is an unavoidable topic for developers. Slow pages drive users away; dropping Lighthouse scores hurt SEO and conversions. The common workflow involves opening Chrome DevTools, recording a Performance Trace, then troubleshooting step-by-step against metrics like LCP, INP, CLS and others. While this process is well-established, it involves a lot of repetitive work: navigating to the page, recording the trace, reading insights, checking network requests, then cross-referencing with code to adjust configurations.

Cloudflare has published a Skill named web-perf in its official Agent Skills repository. It formalizes the workflow of “conducting web performance audits using Chrome DevTools MCP” into a fixed set of steps, allowing AI coding tools that support the Agent Skills standard (such as Cursor, Claude Code, OpenAI Codex, etc.) to execute the audit in stages during a conversation, rather than just giving vague suggestions based on the model’s pre-trained knowledge.

This article is based on the official repository’s SKILL.md and cloudflare/skills README, explaining what this Skill is, how to install it, and how to use it.

What it is¶

web-perf is an Agent Skill maintained by Cloudflare, located at skills/web-perf/ in the cloudflare/skills repository. The official one-sentence positioning is: Use Chrome DevTools MCP to analyze web performance, measure Core Web Vitals (LCP, INP, CLS) as well as supplementary metrics like FCP, TBT, Speed Index, and identify render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps.

The trigger scenario is clear: when you ask the Agent to audit, analyze, debug, or optimize page loading performance, Lighthouse scores, or site speed, it will follow the checklist in the Skill to proceed. The Skill also emphasizes one point: metric thresholds and tool APIs may become outdated. Prioritize retrieving information from up-to-date official documentation instead of relying solely on the model’s pre-trained knowledge. Recommended sources include web.dev’s Vitals explanations, Chrome DevTools performance documentation, and Lighthouse performance scoring documentation.

Core Capabilities¶

Combined with the official SKILL.md, the capabilities can be summarized into five parts:

1. Performance Traces and Core Web Vitals
   Open the target page via navigate_page, then use performance_start_trace (it is recommended to set autoStop: true and reload: true) to record a cold start trace; then use performance_analyze_insight to parse insights such as LCP breakdown, CLS culprits, render-blocking resources, document latency, and network dependency graphs.

2. Network and Resource Bottlenecks
   Use list_network_requests / get_network_request to check requests for Scripts, Stylesheets, Documents, Fonts, Images and other resources, paying attention to render-blocking resources, dependency chains, missing preload links, weak cache headers, oversized uncompressed resources, and invalid preconnects.

3. Accessibility Snapshots
   Use take_snapshot(verbose: true) to capture the accessibility tree, and flag high-priority issues like duplicate/missing ARIA IDs, insufficient color contrast, focus traps, and interactive elements without accessible names.

4. Build-Side Analysis with a Code Repository
   If auditing a non-third-party site, the Skill will also identify frameworks and bundlers based on configurations like webpack/vite/next, and check optimization points such as tree-shaking, unused JS/CSS, polyfills, minification, and production sourcemaps.

5. Output and Priority Discipline
   It requires delivering a metric summary table, a list of issues sorted by impact, and actionable repair suggestions (preferably with code or configuration snippets). The principles include: quantifying impact with estimated benefits, documenting but not strongly pushing “issues” with zero benefits, verifying before suggesting deletions, and clearly stating that a site already performs well if it meets standards.

Installation and Activation¶

web-perf is part of the Cloudflare Skills collection, and the installation method matches the repository’s README.

Install with npx skills (can install only this Skill)¶

npx skills add https://github.com/cloudflare/skills --skill web-perf

You can also add the entire repository at once:

npx skills add https://github.com/cloudflare/skills

Claude Code¶

Install via the plugin marketplace:

/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare

Cursor¶

You can install it from the Cursor Marketplace, or fill in cloudflare/skills in Settings > Rules > Add Rule > Remote Rule (Github).

Manually copy to each tool’s Skills directory¶

After cloning the repository, copy skills/web-perf to the corresponding directory, for example:

Required Configuration: Chrome DevTools MCP¶

The Skill clearly requires confirming that you can call navigate_page or performance_start_trace before starting. If these functions are unavailable, you should stop execution and prompt the user to add the following configuration to their MCP settings:

"chrome-devtools": {
  "type": "local",
  "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
}

Without this MCP suite, the Agent will not be able to truly record and parse performance traces, and the main workflow of the Skill cannot run.

Typical Usage¶

After installing the Skill and configuring the chrome-devtools MCP, you can directly ask the Agent for a requirement like:

Please audit the page performance of https://example.com, focusing on Core Web Vitals, render-blocking resources and network dependency chains, and provide actionable optimization suggestions sorted by impact.

Following the official workflow, the Agent will generally proceed according to the following checklist:

Audit Progress:
- [ ] Phase 1: Performance trace (navigate + record)
- [ ] Phase 2: Core Web Vitals analysis (includes CLS culprits)
- [ ] Phase 3: Network analysis
- [ ] Phase 4: Accessibility snapshot
- [ ] Phase 5: Codebase analysis (skip if third-party site)

Key tool call examples (from the official Quick Reference):

navigate_page(url: "https://example.com")
performance_start_trace(autoStop: true, reload: true)
performance_analyze_insight(insightSetId: "<id-from-trace>", insightName: "LCPBreakdown")
list_network_requests(resourceTypes: ["Script", "Stylesheet", "Document", "Font", "Image"])
take_snapshot(verbose: true)

Common insight names include: LCPBreakdown, CLSCulprits, RenderBlocking, DocumentLatency, NetworkRequestsDepGraph. The official also reminds that insight names may vary across different Chrome DevTools versions. If a call fails, you should first check the actual available list from the insightSetId in the trace response.

The final output generally includes four parts: a Core Web Vitals summary table (metrics, values, good / needs-improvement / poor status), Top Issues sorted by priority, specific Recommendations, and (if code permissions are available) Codebase Findings.

Applicable Scenarios and Notes¶

It is suitable for these situations:
- Conducting a repeatable performance audit on key landing pages before launch or during regression testing;
- After Lighthouse / Core Web Vitals scores drop, pinpointing specific resources and code changes that caused the score decline;
- Having a local front-end repository, and wanting the Agent to cross-reference traces with build configurations from tools like Vite, Webpack, Next.js to provide targeted suggestions.

Notes for usage:
1. Depends on a real browser and MCP, not just pure text reasoning; do not fabricate conclusions when the MCP is not configured.
2. Skip the codebase analysis phase when auditing third-party sites, and only base conclusions on page and network evidence.
3. Suggestions must be verifiable: For example, confirm whether there are actually requests going to a specific origin before deleting a preconnect link; do not treat “render-blocking resources” with an estimated time saving of 0ms as a high-priority item.
4. Use current official documentation for threshold values: The TTFB / FCP / LCP / INP / TBT / CLS / Speed Index ranges given in the Skill are for reference only; double-check them against web.dev / Lighthouse documentation before writing reports or presenting results.

Summary¶

web-perf formalizes the workflow of “open DevTools → record trace → read insights → check network → (optional) review build configurations” into an executable Skill for Agents, making it easy to integrate front-end performance audits into daily conversational development workflows. Its value does not lie in inventing new metrics, but in enforcing real measurement, sorting by impact, and tying recommendations to specific files and configurations as much as possible.

Official address: https://github.com/cloudflare/skills/tree/main/skills/web-perf
Repository overview and installation instructions: https://github.com/cloudflare/skills
skills.sh installation page: https://www.skills.sh/cloudflare/skills/web-perf