Astro Optimizer

Audit an Astro codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Astro's promise is HTML first and JavaScript only where you ask for it, so the first question is always what is being hydrated that does not need to be. Hydration, caching and CSP changes can alter behavior or security, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the project root (package.json with astro, plus astro.config.*). Record: Astro major, output mode (static by default, or server), adapter, integrations, UI framework renderers, content collections, site, Node version and package manager. If output: 'hybrid' is still present, the project predates Astro 5.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, astro.config.* and .astro/.ts/.js/.mdx sources for version leftovers, hydration cost, image/font gaps, XSS and cache misuse, with file:line evidence. Use --json to post-process.
• Classify the pain: slow load (JS/CSS/images/fonts), bad LCP or CLS, slow interactions (heavy islands), slow SSR/TTFB (origin/cache), slow build (collections/images), or code health/upgrade. Ask which hurts if unclear.
• If the user only gave a URL, say a code audit needs the repo; meanwhile collect field data (CrUX/PageSpeed Insights) and do not guess at causes. Read references/tooling.md once to see what can actually be measured here.
• Astro sites often contain React/Svelte/Vue islands. Optimize the island boundary here; for component internals inside an island, hand off to the matching framework optimizer.

2. Audit

The script finds cheap leads; you find the rest by reading. Read astro.config.*, the base layout, the home page, the 3-5 most important routes, and every component with a client:* directive. Load only what applies:

Measure, never guess. Build for production, run it (astro preview or the adapter's server), and measure that. Count islands by directive, inspect transferred JS per island, and check the LCP image and font requests. Dev-server timings mean nothing, and a single Lighthouse run is weaker evidence than field p75 data.

Mark each finding Confirmed (build output, network panel, code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as ASTRO_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table sorted by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- client:load to client:visible/client:idle, delete client directives from components that render static markup, use <Image>/<Picture> with layout and real dimensions, preload the one real font, enable prefetch, remove unused integrations, add cache headers. Low risk.
2. Structural -- replace a framework island with .astro + <script>/custom element, split a header island into a small cart island, move personalization into a server:defer island, prerender routes that do not need request data, move ad-hoc content globs to collections, adopt route caching. Name each behavior change.
3. Heavy -- Astro 5 to 6 to 7 upgrade, removing a UI framework or adapter, changing image service, adopting view transitions site-wide. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

4b. Experimental gate (ask before enabling)

Astro's experimental flags (clientPrerender, incrementalBuild, parallelPrerender, svgOptimization, collectionStorage, staticRedirectPage, plus adapter experimental CDN cache providers) can help, but they may change between minors, need host support, or change output. Never enable them as part of a "quick win": list only the ones that fit this project in an Experimental candidates section with benefit, risk, rollback and the version that introduced them, then ask which, if any, the user wants. Declined flags stay out of the plan.

5. Fix

Only approved items, in small groups. After each: npx astro check (if installed), the project's lint and tests, then npx astro build. A break must trace to one change. Do not mix an upgrade with optimization edits. If an approved change turns out to expose per-user data to a shared cache, or to remove interactivity users had, stop and ask.

6. Verify and wrap up

Re-measure the same scenario: transferred JS per island, island count by directive, LCP/INP/CLS on a production build, build wall time and page count, and SSR TTFB for server-rendered routes. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Ship less JavaScript. An island is a cost, not a feature. Every client:* directive must earn its framework runtime.
• Choose the cheapest directive that keeps the interaction. client:visible below the fold, client:idle for non-urgent, client:load only for above-the-fold interactivity, client:only only when SSR is impossible.
• Static by default, dynamic by exception. prerender = false is a decision with a hosting and cache cost; keep it off routes that can be built.
• Server islands beat making the whole page dynamic. Defer the avatar, cart count or price, cache the shell.
• Content collections beat ad-hoc globs for structured content, and build-time beats request-time unless freshness is the point.
• Images and fonts decide LCP and CLS. A hero image in public/ with no width/height is a finding, not a style choice.
• Caching is correctness first. Never let a shared CDN or route rule cache a per-user response; state the staleness trade-off for every cache change.
• Do not break HTML, SEO or accessibility for speed. Keep semantic markup, real links, alt text, focus handling and error pages.
• Docs move. Astro 5, 6 and 7 differ (removed Astro.glob/ViewTransitions, strict Rust compiler, new Markdown pipeline). Check the docs for the version in package.json, not memory.