Skip to main content
skill CX Codex

perf-astro skill for Claude Code: Astro performance to 95+ Lighthouse

The perf-astro Claude Code skill tunes Astro builds with inlined critical CSS, minification, non-blocking fonts and an LCP preload, aiming for 95+ Lighthouse scores.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tech-leads-club/agent-skills --skill perf-astro -a claude-code
Open on GitHub

What perf-astro does

The skill walks an Astro project through a fixed set of build changes. astro-critters scans the rendered HTML, picks the CSS the first screen needs, inlines it and lazy-loads the rest; the build log prints how many kilobytes went in. @playform/compress then minifies HTML, CSS and JS, with images and SVG left out of the sample config so an external optimizer can handle them.

The Layout.astro pattern covers the head of the page: a font-display: swap fallback, Google Fonts loaded non-blocking through media="print" plus onload, a preload for the LCP image with fetchpriority="high", and analytics attached to scroll, click or touchstart instead of firing on parse. To see the result: npx lighthouse https://your-site.com --preset=perf --form-factor=mobile.

Scope is narrow. Those integrations only apply to Astro, and on another framework the config buys nothing — reach for perf-web-optimization or core-web-vitals instead. Running audits belongs to perf-lighthouse.

What it helps with

  • inline critical CSS during the Astro build
  • stop Google Fonts from blocking the first render
  • raise fetch priority on the LCP image
  • hold analytics until the first scroll or tap
  • switch on HTML, CSS and JS minification in astro.config.mjs

Example prompts for the agent

  • Wire astro-critters and @playform/compress into astro.config.mjs, then show me what still delays the first render.
  • Look at my Layout.astro — do the fonts use the media="print" trick and does the hero image have fetchpriority="high"?
  • Build me a checklist for LCP and deferred third-party scripts in this Astro site.

How to install perf-astro

1Skills CLI (Vercel)

npx skills add tech-leads-club/agent-skills --skill perf-astro -a claude-code

2Manually: put the files in place

~/.claude/skills/perf-astro/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/perf-astro/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about perf-astro

How do I install perf-astro in Claude Code?

Run npx skills add tech-leads-club/agent-skills --skill perf-astro -a claude-code. The skill file lands at ~/.claude/skills/perf-astro/SKILL.md.

What does perf-astro do?

It applies Astro-side performance work: critical CSS inlining, build minification, font loading that does not block paint, and a preload for the main image. A Layout.astro template and a checklist come with it.

Does perf-astro run Lighthouse audits?

No. Audits live in perf-lighthouse; this skill changes the Astro config and layout so the numbers move. For a non-Astro site use perf-web-optimization or core-web-vitals.

Source text

SKILL.md · MIT
---
name: perf-astro
description: 'Astro-specific performance optimizations for 95+ Lighthouse scores. Covers critical CSS inlining, compression, font loading, and LCP optimization. Use when optimizing Astro site performance, improving Astro Lighthouse scores, or configuring astro-critters. Do NOT use for non-Astro sites (use perf-web-optimization or core-web-vitals) or running Lighthouse audits (use perf-lighthouse).'
---

# Astro Performance Playbook

Astro-specific optimizations for 95+ Lighthouse scores.

## Quick Setup

```bash
npm install astro-critters @playform/compress
```

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'
import critters from 'astro-critters'
import compress from '@playform/compress'

export default defineConfig({
  integrations: [
    critters(),
    compress({
      CSS: true,
      HTML: true,
      JavaScript: true,
      Image: false,
      SVG: false,
    }),
  ],
})
```

## Integrations

### astro-critters

Automatically extracts and inlines critical CSS. No configuration needed.

What it does:

- Scans rendered HTML for above-the-fold elements
- Inlines only the CSS those elements need
- Lazy-loads the rest

Build output shows what it inlined:

```
Inlined 40.70 kB (80% of original 50.50 kB) of _astro/index.xxx.css.
```

### @playform/compress

Minifies HTML, CSS, and JavaScript in the final build.

Options:

```js
compress({
  CSS: true, // Minify CSS
  HTML: true, // Minify HTML
  JavaScript: true, // Minify JS
  Image: false, // Skip if using external image optimization
  SVG: false, // Skip if SVGs are already optimized
})
```

## Layout Pattern

Structure your `Layout.astro` for performance:

```astro
---
import '../styles/global.css'
---

<!doctype html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <!-- Font fallback (prevents FOIT) -->
    <style>
      @font-face {
        font-family: 'Inter';
        font-display: swap;
        src: local('Inter');
      }
    </style>

    <!-- Non-blocking Google Fonts -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link
      rel="stylesheet"
      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
      media="print"
      onload="this.media='all'"
    />
    <noscript>
      <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap">
    </noscript>

    <!-- Preload LCP images -->
    <link rel="preload" as="image" href="/hero.png" fetchpriority="high">

    <title>{title}</title>

    <!-- Defer third-party scripts -->
    <script>
      let loaded = false;
      function loadAnalytics() {
        if (loaded) return;
        loaded = true;
        // Load GTM, analytics, etc.
      }
      ['scroll', 'click', 'touchstart'].forEach(e => {
        document.addEventListener(e, loadAnalytics, { once: true, passive: true });
      });
      setTimeout(loadAnalytics, 5000);
    </script>
  </head>
  <body>
    <slot />
  </body>
</html>
```

## Measuring

```bash
npx lighthouse https://your-site.com --preset=perf --form-factor=mobile
```

See also:

- **perf-lighthouse** - Running audits, reading reports, setting budgets
- **perf-web-optimization** - Core Web Vitals, bundle size, caching strategies

## Checklist

- [ ] `astro-critters` installed and configured
- [ ] `@playform/compress` installed and configured
- [ ] Google Fonts use `media="print" onload` pattern
- [ ] Third-party scripts deferred to user interaction
- [ ] LCP images preloaded in `<head>`

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set130

The whole set →
rerender-functional-setstate The rerender-functional-setstate rule recommends functional state updates when the next React value depends on the current one. It helps callbacks avoid stale state and unnecessary dependencies. CX Codex +1 ★ 7,191repo stars state-lift-state state-lift-state — a Claude Code rule that moves React state into a provider component, so siblings outside the main UI read and update it without prop drilling or refs. CX Codex +1 ★ 7,191repo stars js-batch-dom-css js-batch-dom-css prevents layout thrashing by separating style updates from layout queries. Helps Claude write performant DOM and React code. CX Codex +1 ★ 7,191repo stars docs-writer The docs-writer skill creates, edits, and reviews project documentation. Use it for READMEs, Markdown files, and pages under docs/. CX Codex +1 ★ 7,191repo stars tactical-ddd Audits domain models for anemia and refactors them into rich aggregates using tactical DDD patterns in Claude Code. CX Codex +1 ★ 7,191repo stars nx-workspace nx-workspace — a skill for exploring an Nx monorepo from the CLI: list projects, read resolved config, find affected projects and wire affected commands into CI. CX Codex +1 ★ 7,191repo stars perf-web-optimization perf-web-optimization guides front-end performance tuning by shrinking JS bundles, deferring heavy scripts, and configuring cache headers. Best when pages load slowly or fail speed benchmarks. CX Codex +1 ★ 7,191repo stars state-context-interface The state-context-interface rule separates a component’s UI from its state implementation with a context split into state, actions, and meta. Use it when the same UI needs to work with different providers. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open