diff --git a/.gemini/commands/webperf.toml b/.gemini/commands/webperf.toml
new file mode 100644
index 0000000..af0ab10
--- /dev/null
+++ b/.gemini/commands/webperf.toml
@@ -0,0 +1,32 @@
+description = "Run a web performance audit via the web-performance-auditor persona"
+
+prompt = """
+/webperf targets web applications specifically. Do not use it for utility libraries, CLIs, or server-only code with no browser-facing output.
+
+## Determine the mode
+
+Deep mode — activate when any of these is available:
+- A Lighthouse JSON report file (e.g. `npx lighthouse <url> --output json --output-path ./report.json`, or `npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json` from the Chrome DevTools MCP CLI)
+- A PageSpeed Insights JSON response (includes Lighthouse + CrUX)
+- A CrUX API response (requires CRUX_API_KEY or GOOGLE_API_KEY)
+- A DevTools performance trace
+- A live URL plus the chrome-devtools MCP server configured in the harness (capture metrics directly via lighthouse_audit and performance_* tools)
+- The Chrome DevTools MCP CLI invoked locally (via `npx -p chrome-devtools-mcp chrome-devtools <tool>`), passing the JSON output to the agent
+
+Quick mode — default when none of the above are available. Scan source code for structural anti-patterns and label every finding as `potential impact`.
+
+## Run the audit
+
+Act as the web-performance-auditor persona (agents/web-performance-auditor.md) and follow it exactly. Work from:
+
+- The files, components, or diff under review
+- Any artifact paths (Lighthouse JSON, PSI JSON, CrUX response, trace) or pasted JSON content
+- The target URL or page name when known
+- The mode you expect (Quick or Deep); surface missing inputs if Deep was intended
+
+Return a scorecard (only populated with sourced values — mark unmeasured fields `not measured`, never fabricate metrics), a ranked list of findings, positive observations, and proactive recommendations.
+
+## Output
+
+Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command.
+"""
diff --git a/CLAUDE.md b/CLAUDE.md
index 44990c2..d8699aa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,9 +6,9 @@ This is the agent-skills project — a collection of production-grade engineerin
 
 ```
 skills/       → Core skills (SKILL.md per directory)
-agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor)
+agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
 hooks/        → Session lifecycle hooks
-.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship)
+.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
 references/   → Supplementary checklists (testing, performance, security, accessibility)
 docs/         → Setup guides for different tools
 ```
diff --git a/README.md b/README.md
index 9cc8dca..6995a18 100644
--- a/README.md
+++ b/README.md
@@ -203,6 +203,7 @@ Pre-configured specialist personas for targeted reviews:
 | [code-reviewer](agents/code-reviewer.md) | Senior Staff Engineer | Five-axis code review with "would a staff engineer approve this?" standard |
 | [test-engineer](agents/test-engineer.md) | QA Specialist | Test strategy, coverage analysis, and the Prove-It pattern |
 | [security-auditor](agents/security-auditor.md) | Security Engineer | Vulnerability detection, threat modeling, OWASP assessment |
+| [web-performance-auditor](agents/web-performance-auditor.md) | Web Performance Engineer | Core Web Vitals audit with Quick/Deep modes and a metric-honesty rule; run it via `/webperf` |
 
 ---
 
@@ -279,7 +280,7 @@ agent-skills/
 │   ├── observability-and-instrumentation/ # Ship
 │   ├── shipping-and-launch/           #   Ship
 │   └── using-agent-skills/            #   Meta: how to use this pack
-├── agents/                            # 3 specialist personas
+├── agents/                            # 4 specialist personas
 ├── references/                        # 4 supplementary checklists
 ├── hooks/                             # Session lifecycle hooks
 ├── .claude/commands/                  # 7 slash commands (Claude Code)
diff --git a/docs/getting-started.md b/docs/getting-started.md
index da83429..e704195 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -96,6 +96,7 @@ The `agents/` directory contains pre-configured agent personas:
 | `code-reviewer.md` | Five-axis code review |
 | `test-engineer.md` | Test strategy and writing |
 | `security-auditor.md` | Vulnerability detection |
+| `web-performance-auditor.md` | Core Web Vitals & performance audit (via `/webperf`) |
 
 Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.
 
@@ -112,6 +113,7 @@ The `.claude/commands/` directory contains slash commands for Claude Code:
 | `/test` | test-driven-development |
 | `/review` | code-review-and-quality |
 | `/ship` | shipping-and-launch |
+| `/webperf` | web-performance-auditor (specialist agent, web apps only) |
 
 ## Using References