nicolas-codemate/perf-landing
skills/perf-landing/SKILL.md
Method to diagnose and raise the Lighthouse performance score of a public page (landing, marketing, home). Use when asked to improve Lighthouse/PageSpeed scores, when auditing the first uncached paint of a public page, or when a landing embedded in a SPA must reach a top score. Do NOT use for in-app screen performance (data loading, rendering). For a brand-new landing, the first recommendation is static HTML with no framework runtime — most of this skill exists for when that is not an option.
development
Updated Jul 26, 2026
$ install --global
skillsauthnpx skillsauth add nicolas-codemate/claudecodeconfig perf-landingInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jul 26, 2026, 3:09 AM289.5s1 file scanned
SKILL.md
- name:
- perf-landing
- description:
- Method to diagnose and raise the Lighthouse performance score of a public page (landing, marketing, home). Use when asked to improve Lighthouse/PageSpeed scores, when auditing the first uncached paint of a public page, or when a landing embedded in a SPA must reach a top score. Do NOT use for in-app screen performance (data loading, rendering). For a brand-new landing, the first recommendation is static HTML with no framework runtime — most of this skill exists for when that is not an option.
Landing Page Performance (Lighthouse)
Method distilled from a real case (Vue SPA landing, mobile 83 → 99, desktop 100). The score is won on the simulated critical path, which can differ wildly from real paint speed.
Rule 0: don't enter the labyrinth
A landing served as plain static HTML (hand-written, Astro, SSG) with inline critical CSS scores 100 with none of the machinery below. Everything in the "SPA-hosted landing" section exists to make a SPA route look static to Lighthouse. If you are designing a new page and static is an option, take it and stop reading.
Mental model: lantern
Lighthouse mobile does not measure your machine; it replays the request graph through the "lantern" simulation (RTT 150 ms, 1.6 Mbit/s, CPU x4). Consequences:
- A page can paint in 140 ms observed and still score LCP 3.8 s simulated.
- Parser-declared resources in
<head>(scripts — eventype="module"/deferred —, stylesheets, preloads) enter the simulated pre-LCP graph and compete for the simulated 1.6 Mbit/s. A large entry bundle in the head degrades simulated LCP even when the real paint never waits for it. - A resource leaves the graph only when nothing parser-visible references it (e.g. injected from
JS after
load). - TBT counts long tasks between FCP and TTI. Making FCP earlier can reveal main-thread work that previously ran before FCP — expect TBT to move when you fix FCP.
Always compare observed vs simulated in the report JSON
(.audits.metrics.details.items[0].observedFirstContentfulPaint vs .firstContentfulPaint).
Observed good + simulated bad = hunt the request graph (High-priority pre-LCP requests), not the
rendering. Identify the actual LCP element (.audits["largest-contentful-paint-element"]) before
optimizing anything — it is not always the one you think, and it can move (e.g. to a text node
that repaints on font swap) after you fix the current one.
Measure correctly (before and after every change)
- Never trust DevTools reports from a daily browser: extensions (password managers, adblockers)
pollute unminified-js, forced-reflow, errors-in-console. Always re-measure headless:
npx lighthouse <url> --chrome-flags="--headless=new" --output=json --output-path=r.json --quiet - Iterate on a static copy of the build served with compression (
npx serve -l <port> <dir>), editing the HTML directly — seconds per iteration. Wire the winning variant into the build after. - Run 3 times, keep the median: TBT varies ±40 ms, LCP ±0.3 s locally.
- Score math (mobile): TBT 30%, LCP 25%, CLS 25%, FCP 10%, SI 10%. 100 needs ≥ 99.5 weighted — roughly LCP ≤ 1.8 s simulated AND TBT ≤ ~100 ms with everything else at 1.0.
- Lab ≠ field: the Lighthouse score is a lab metric. Real users are measured by CrUX (LCP, CLS, INP — INP is not even in the Lighthouse score). Any trick that improves lab but plausibly hurts real interactivity (deferred JS, delayed hydration) must be weighed against field data, not just the badge. 99 vs 100 is invisible to users; it only matters if the badge itself is the deliverable — if so, say it explicitly.
Levers for any stack
- Inline the critical CSS; load the rest non-blocking (
media="print" onload="this.media='all'"+<noscript>fallback). Only valid if the inline CSS really covers everything above the fold. - LCP image: start with the boring fix —
<link rel="preload" as="image" fetchpriority="high">and correctly sized files. Inlining it as a data URI removes the request entirely (LCP collapses to FCP) but adds ~33% to its bytes, on every HTML fetch, uncacheable separately — reserve it for small images (≲ 25 KB) on HTML that is itself cached (service worker, CDN). - Fonts: preload the exact subsets painted above the fold, and make their
@font-facerules reachable at first paint (inline them if the main stylesheet is async — preload without applicable @font-face = downloaded but unapplied). Caution: in the observed case, removing font preloads worsened simulated LCP because the LCP anchor moved to text repainted on font swap. Font tuning shifts LCP anchors; re-check the LCP element after every font change. - Explicit
width/heighteverywhere (CLS 0),loading="lazy"below the fold. - Server side: text compression, cache headers, CDN/edge, HTTP 103 Early Hints for fonts/CSS.
SPA-hosted landing (only if the landing is a route of a client-side SPA)
These reproduce what static hosting gives for free:
- Prerender the landing markup into the served HTML at build time (SSR-to-string). The page must display complete without executing any JS.
- Take the entry bundle out of the head: replace the
<script type="module">with a small inline loader that injects it dynamically afterwindow.load(plus a short delay, ~150 ms, to let the load-complete frame paint before the download competes for bandwidth). Validity condition — do not skip: nothing interactive above the fold may depend on the deferred bundle. CTAs must be plain<a href>links that work as full navigations before the SPA boots; verify this by blocking the bundle and clicking them. Branch the loader: boot immediately for known/authed visitors (localStorage hint) and for every non-landing URL (those visitors are waiting for the app, not the landing). If the site has several marketing pages, the "is landing" test must cover all of them, not a hardcoded/. - Prune the inlined CSS to what the landing reaches: design-system token sheets carry
hundreds of custom properties; resolve
var()references transitively from the landing CSS and drop the rest. Smaller HTML = faster download and smaller style-parse tasks. - What remains is usually TBT from evaluating the app bundle itself — that is an app-wide bundle-size problem (lazy monitoring SDK, vendor split), not a landing tweak.
If the site is already SSR/SSG (Nuxt, Next, Astro): 1 is already done and 2 delays hydration — on a page with above-the-fold interactivity that means dead buttons on slow mobile. Do not apply it blindly; measure what the framework already ships.
Before writing any of this tooling, check whether the repo already has a prerender/landing build plugin and reuse it.
Verify before shipping (non-negotiable)
- Visual parity: screenshot the prerendered page (JS disabled) vs the hydrated page — light AND dark. CSS pruning and critical-CSS extraction fail silently as wrong colors.
- Landing CTAs work before the SPA boots (block the bundle, click, expect a full navigation that renders).
- The authed/returning-visitor path boots immediately and never flashes the landing.
- Other public routes (login, signup) are not stuck on the prerendered landing waiting for
load. - CLS stays 0 when the async CSS applies and when fonts swap.
- Categories other than performance did not regress (run without
--only-categories). - Real backend up during browser checks: an API container down produces blank screens that look exactly like a frontend regression.
Related Skills
nicolas-codemate/audit-project
tools
VerifiedTrustedCommunity
Audits a project's Claude Code setup against real usage — mines the project's conversations (worktrees included), confronts the project's skills/agents/CLAUDE.md with best practices, and proposes adjustments or new skills/agents/rules. Use when the user asks to audit the project config, analyze project conversations, or find automation opportunities for the current project. Do NOT use for the global ~/.claude configuration (use /audit-config instead).
SKILL.mdUpdated Jul 7, 2026
nicolas-codemate/mentor
development
VerifiedTrustedCommunity
Coaching workflow orchestrator. Guides the developer through implementation without writing code.
SKILL.mdUpdated Jul 7, 2026
nicolas-codemate/architect-refactor
development
VerifiedTrustedCommunity
Disciplined methodology for code architecture refactoring. Use when the user asks to refactor architecture, decouple code, restructure a family of classes, redesign an interface, or rename/reorganize a set of related components. Forces a big-picture analysis before any code is written. Do NOT use for simple bug fixes, feature additions, or single-file refactoring.
SKILL.mdUpdated Jul 7, 2026
nicolas-codemate/aep
development
VerifiedTrustedCommunity
Analyse-Explore-Plan methodology for thorough analysis and planning before development. Use when starting a new feature, investigating a problem, or needing to understand a codebase before making changes. Provides structured workflow with parallel exploration agents and clarification questions. Integrates with Architect skill for high-quality implementation plans. Do NOT use for ticket-based planning (use /resolve <ticket> --plan-only instead) or when a saved plan is needed (use /create-plan instead).
SKILL.mdUpdated Jul 7, 2026