# Benchmark

> Benchmark Skill

- Skill: `andrem-sec/benchmark` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andrem-sec/benchmark`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrem-sec/benchmark/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: andrem-sec (https://skillmd.com/u/andrem-sec)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andrem-sec/benchmark

---


# 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:

```bash
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:

```bash
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

1. Verify 3 passes were run per page and the median was reported (unless --quick was used)
2. Verify CWV thresholds were applied to all available metrics
3. Verify baseline comparison ran if a baseline file exists
4. Verify PageSpeed Insights phase was either run (if key present) or explicitly noted as unavailable
5. Verify regression and warning thresholds were applied to all deltas
6. Verify the final verdict across all pages was reported
7. Verify results were saved to context/benchmarks/[url-slug]-[date].json