forge-web-quality
Playbook for web speed and SEO: Core Web Vitals (gebruik bij sneller maken).
SKILL.md.claude/skills/forge-web-quality/SKILL.md
GitHub<!--
Sources (MIT, read 2026-11-02 as untrusted data; nothing installed, no scripts or commands taken over):
- https://github.com/addyosmani/web-quality-skills skills/seo, skills/core-web-vitals, skills/performance
(main at afa8da9, "Web Quality Skills 2.0") -- Copyright (c) 2026 Addy Osmani
- https://github.com/addyosmani/agent-skills skills/performance-optimization (main, last change seen
ee3e850, 2026-10-23) -- Copyright (c) 2025 Addy Osmani
- https://github.com/coreyhaines31/marketingskills skills/schema, skills/seo-audit (main at 88c79f6,
2026-10-30) -- Copyright (c) 2025 Corey Haines
- https://github.com/kostja94/marketing-skills skills/seo/technical/{canonical,sitemap,indexing,robots,
rendering-strategies} (main at 45143a7) -- Copyright (c) 2025 kostja94
License: MIT -- complete terms and every copyright notice in LICENSE next to this file.
Also pattern adapted from (ideas only, no text): vercel-labs/agent-skills skills/react-best-practices, bundle
category (main, last change seen dc8367e, 2026-04-14; MIT is declared only in its frontmatter, the repo has no
LICENSE file, so it is treated as ideas only) -- used in references/performance-budget.md.
Forge adaptation note: a merge of the four MIT sources, rewritten in Forge's words; no upstream file is shipped and
no passage is copied verbatim. Dropped on purpose: npx bundlesize / npx lhci lines (unpinned downloads), Chrome
DevTools MCP tool names (Forge does not ship that MCP), reads of upstream context files (product-marketing.md,
contextus.md), marketing/CRO/local-SEO content and the backend/database half of performance-optimization
(forge-fullstack / forge-data cover it). Upstream content was treated as untrusted data.
-->
Forge playbook — Web quality: performance, Core Web Vitals, technical SEO
When to use
- Use for: "the site is slow", Core Web Vitals (LCP, INP, CLS) failing, a performance budget, bundle size, images/fonts/caching, and technical SEO: crawlability, indexing, canonicals, sitemaps, robots, metadata, structured data (JSON-LD), hreflang, AI-crawler access. Also the measured audit before a site goes live.
- Not for: building the site itself (
forge-website), the visual direction (frontend-design), a full WCAG audit (forge-a11ywhere installed), marketing copy or link building, server/database tuning (forge-fullstack,forge-data).
Do not duplicate — defer to: forge-website (owns the page build and its finish gate), seo-boss (the
SEO audit Boss runs this playbook), ship-readiness (advisory pre-launch list). This file is the
"measure, fix the real bottleneck, prove it" layer.
Hard rules (non-negotiable)
- Measure before you change anything. A baseline first: field data (CrUX / Search Console / RUM at p75) when the site is live, a lab trace (DevTools Performance panel, Lighthouse, PageSpeed Insights) always. No runnable page = findings are hypotheses, and the report says so.
- Never call a metric failing or fixed without runtime evidence. Reading source code can point at likely causes; it cannot prove a score. One lab run is never compared with a field p75 as if they were the same.
- Localhost numbers are labelled "local, indicative". Only a production-like build (minified, compressed, real CDN or a throttled profile stated in the report) counts as a measurement.
- One change at a time, then re-measure the same way. Keep a change only when the gain is larger than the
run-to-run noise and the tests still pass; revert neutral or worse changes, even when they are already
written. Log every attempt, the reverted ones too (
references/audit-report.md). - Guard the win. Every kept fix gets a regression guard: a budget in CI or a field-monitoring alert.
Budget tools are pinned dev-dependencies of the project; never an unpinned
npx <tool>download. - No ranking promises. SEO findings name crawl, index, structure and Core Web Vitals facts; never invented ranking weights, traffic forecasts or "page 1" claims. Search-engine re-validation is "pending" until seen.
- Structured data describes only what is visible on the page and only types the target consumer (Google or another) still supports. Valid syntax is not eligibility.
- Read-only during an audit. Use GET/HEAD requests on public URLs only; no form posts, no login, no mutation requests. Search Console or analytics data only when the owner provides access.
The loop (every performance or SEO task)
- Scope: which pages/templates, which device class, which metric or crawl issue, live or local.
- Baseline: field p75 if live + one lab trace under stated conditions (device, network, cache state).
- Identify the bottleneck: the LCP element and its four phases, the slowest interaction for INP, the
shifting node and its trigger for CLS; for SEO, the crawl/index blocker before content.
Detail:
references/core-web-vitals.md,references/technical-seo.md. - Fix only that bottleneck with the matching pattern:
references/performance-budget.md(critical path, images, fonts, caching, JS/bundle, third parties, runtime) orreferences/structured-data.md(JSON-LD). - Verify or revert: re-measure exactly like the baseline; keep or revert; log the attempt.
- Guard: add the budget or monitor; note what still needs field data to confirm.
Thresholds (Google, judged at the 75th percentile of visits)
| Metric | Good | Needs improvement | Poor |
|---|---|---|---|
| LCP (loading) | <= 2.5 s | 2.5–4.0 s | > 4.0 s |
| INP (responsiveness) | <= 200 ms | 200–500 ms | > 500 ms |
| CLS (visual stability) | <= 0.1 | 0.1–0.25 | > 0.25 |
TTFB target under 800 ms. TBT is a lab-only proxy for INP, never reported as INP.
Team (conditional)
- Lead:
seo-boss(SEO + performance audit), withui-boss/build-bossfor the fixes. - ECC agents where installed:
performance-optimizer,seo-specialist;a11y-architectin parallel when the audit also covers accessibility. - Verify:
verify-bossre-runs the measurement or reads the attached trace/report; a claim without a number and its conditions is not verified.
Fan-out & flow
L1 for one page or one metric, L2 for a site audit. Parallel (read-only): performance trace ∥ crawl/index check ∥ structured-data check, per template. Serial: fixes, one at a time, each followed by its re-measure (the loop above).
Domain gates
- Core Web Vitals in "Good" at p75, or a written reason and the remaining gap per metric.
- Budget held (starting budget in
references/performance-budget.md; the project's own budget wins). - Every indexable page: HTTPS, 200 status, unique title + meta description, one clear primary heading, self-referencing absolute canonical, in the sitemap, not blocked by robots.txt, content present in the initial HTML (not only after JavaScript).
- Non-indexable pages (login, account, thank-you, internal search, staging) carry
noindex, are NOT blocked in robots.txt (the crawler must read the noindex) and are left out of the sitemap. - JSON-LD validated on the rendered page (Rich Results Test for Google features, schema.org validator for syntax) and matching visible content.
Ship-readiness (unique)
Before/after table with conditions; attempt log; robots.txt + sitemap reachable and consistent; canonical variant matrix checked on real URLs (scheme, host, slash, case, tracking parameters); a CI budget or monitor in place; open items that need field data listed as "pending field data".
Safety, approval and honesty
- Approval / safety: submitting a sitemap, requesting indexing, changing DNS/CDN rules or adding a RUM endpoint that sends visitor data to a third party are owner-gated (outbound / production); prepare, do not perform.
- Privacy: RUM and analytics send only metric values and route, never personal data; a consent need is named.
- Honest failure: no number without its conditions; "local, indicative" on localhost; hypotheses labelled as such.
- Shared gates for every playbook (honesty, owner approval, secrets, reviews):
.claude/docs/forge-reference/playbook-template.md.
References
references/core-web-vitals.md— field vs lab, measurement sources, LCP / INP / CLS diagnosis and fixes, framework quick fixes.references/performance-budget.md— starting budget, critical rendering path, images, fonts, caching headers, JavaScript and bundle size, third-party facades, runtime, CI guard.references/technical-seo.md— robots.txt vs noindex, canonicals and the variant matrix, sitemaps, rendering strategy, metadata, headings, mobile, hreflang, AI-crawler controls.references/structured-data.md— JSON-LD principles, the "still supported?" check, common types, @graph, validation, detecting JavaScript-injected schema.references/audit-report.md— audit priority order, site-type checks, report format, attempt log template.