| name | benchmark |
| description | Performance measurement with Core Web Vitals thresholds — baseline capture, regression detection, optional PageSpeed Insights |
Benchmark Skill
Performance measurement with hardcoded Core Web Vitals thresholds, 3-pass median reporting, and regression detection against a saved baseline. Measure, do not guess. Think of a baseline as a before photo: without it, you cannot tell whether the change made things better, worse, or did nothing.
What Claude Gets Wrong Without This Skill
Without a protocol, performance "checks" produce a single data point with no comparison context. One curl request is not a measurement: it is a sample. One sample is dominated by network variance, server cold starts, and caching state. A 3-pass median is a measurement.
The other failure mode is missing the baseline: making a change, running a check, seeing numbers, and having no reference to know whether those numbers are a regression.
Invocation
/benchmark <url> # Full audit with baseline comparison
/benchmark <url> --baseline # Capture baseline before making changes
/benchmark <url> --quick # Single-pass timing, no baseline
/benchmark <url> --pages /,/dash # Specify multiple pages
/benchmark --diff # Pages touched by current branch only
/benchmark --trend # Show historical trend from saved snapshots
Core Web Vitals Thresholds (Hardcoded)
| Metric | Good | Needs Work | Poor |
|---|
| TTFB (Time to First Byte) | < 800ms | 800ms-1.8s | > 1.8s |
| FCP (First Contentful Paint) | < 1.8s | 1.8-3s | > 3s |
| LCP (Largest Contentful Paint) | < 2.5s | 2.5-4s | > 4s |
These thresholds are not configurable. They are the Google CWV standard.
Regression Thresholds
| Signal | Timing | Bundle Size |
|---|
| REGRESSION | > 50% increase OR > 500ms absolute | > 25% increase |
| WARNING | > 20% increase | > 10% increase |
Phase 1: Curl Measurement (Always Runs)
For each target page, run 3 passes and report the median:
curl -o /dev/null -s -w "TTFB:%{time_starttransfer} Total:%{time_total} Size:%{size_download}" <url>
Collect: TTFB, total load time, response size. Use --quick for a single pass when a rough number is sufficient and speed matters more than precision.
Phase 2: PageSpeed Insights (Optional Enhancement)
If GOOGLE_API_KEY is set:
curl -s "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<url>&strategy=mobile&key=$GOOGLE_API_KEY"
Extract: LCP, FCP, TTFB real-user p75 field data and Lighthouse lab scores.
If GOOGLE_API_KEY is not set: skip this phase. Report: "Field data unavailable: set GOOGLE_API_KEY for real-user metrics." Do not fail or warn: this is an optional enrichment, not a requirement.
Phase 3: Baseline Comparison
If a baseline exists at context/benchmarks/<url-slug>-baseline.json:
- Compare each metric against baseline values
- Apply regression and warning thresholds
- Report delta as both absolute value and percentage
If no baseline exists and --baseline was not passed:
- Report absolute values against CWV thresholds only
- Note: "No baseline captured: run
/benchmark <url> --baseline before making changes to enable regression detection."
When --baseline is passed: capture the current measurements as the baseline and save to context/benchmarks/<url-slug>-baseline.json. Do not run a comparison: you are establishing the reference point.
Output Format
## Benchmark: <url>
Date: [date]
Pages tested: [list]
### <page>
TTFB: [value] ([delta vs baseline if available]): [GOOD | NEEDS WORK | POOR]
FCP: [value if available] : [GOOD | NEEDS WORK | POOR]
LCP: [value if available] : [GOOD | NEEDS WORK | POOR]
Size: [bytes] ([delta])
Verdict: PASS | WARNING | REGRESSION
[If regression]: Slowest resource: [resource] at [time]ms
[If PSI available]: Real-user p75 LCP: [value]: [GOOD | NEEDS WORK | POOR]
Final verdict across all pages: PASS | WARNING | REGRESSION
Snapshot
Save each run to context/benchmarks/[url-slug]-[date].json. Baseline snapshots save to context/benchmarks/[url-slug]-baseline.json on --baseline runs. The --trend flag reads all saved snapshots for a URL and reports directional movement.
Anti-Patterns
Do not report a single curl pass as a benchmark. Single-pass numbers are dominated by variance. Run 3 passes and report the median.
Do not treat WARNING as PASS. A 20% regression in TTFB is a signal worth investigating before deploying.
Do not skip capturing a baseline before making changes. A regression you cannot prove is a regression you cannot fix with confidence.
Do not fail the run because GOOGLE_API_KEY is not set. Field data is an enrichment, not a requirement.
Mandatory Checklist
- Verify 3 passes were run per page and the median was reported (unless --quick was used)
- Verify CWV thresholds were applied to all available metrics
- Verify baseline comparison ran if a baseline file exists
- Verify PageSpeed Insights phase was either run (if key present) or explicitly noted as unavailable
- Verify regression and warning thresholds were applied to all deltas
- Verify the final verdict across all pages was reported
- Verify results were saved to context/benchmarks/[url-slug]-[date].json
