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
npx skills add tech-leads-club/agent-skills --skill perf-astro -a claude-codeWhat 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-crittersand@playform/compressintoastro.config.mjs, then show me what still delays the first render. - Look at my
Layout.astro— do the fonts use themedia="print"trick and does the hero image havefetchpriority="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-code2Manually: put the files in place
~/.claude/skills/perf-astro/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/perf-astro/
1Skills CLI (Vercel)
npx skills add tech-leads-club/agent-skills --skill perf-astro -a codex2Manually: put the files in place
.agents/skills/perf-astro/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tech-leads-club/agent-skills --skill perf-astro -a cursor2Manually: put the files in place
.cursor/skills/perf-astro/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tech-leads-club/agent-skills 'packages/skills-catalog/skills/(performance)/perf-astro'2Manually: put the files in place
.github/skills/perf-astro/SKILL.md1Skills CLI (Vercel)
npx skills add tech-leads-club/agent-skills --skill perf-astro -a gemini-cli2Platform CLI
gemini skills install https://github.com/tech-leads-club/agent-skills --path 'packages/skills-catalog/skills/(performance)/perf-astro'Manually: put the files in place
.devin/skills/perf-astro/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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