passionfruit-perf
Skill0 starsChanged 12 days agoMITView on GitHub
Use when editing any media component (`<Image>`, `YouTubeFacade`, `SpotifyFacade`), `BaseLayout.astro`, files under `src/pages/`, or adding new client scripts. Loads image-loading discipline, no-JS-when-CSS-suffices, third-party host CSP rules.
- Reads credentials
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- brandSkill
- deploySkill
- new-postSkill
- new-team-memberSkill
- onboardSkill
- passionfruit-a11ySkill
- passionfruit-contentSkill
- passionfruit-designSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Raw
<img src="...">: instead of <Image> — loses AVIF/WebP, loses responsive sizing, often causes CLS.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
passionfruit performance rules
passionfruit is a static-output Astro site. Performance comes from disciplined defaults: lazy-load below the fold, facades for heavy embeds, CSS over JS for behavior, no third-party host without a CSP update. Most regressions come from skipping one of these — don't.
Hard rules
- Astro
<Image>fromastro:assets, never raw<img>for project assets. Astro generates AVIF + WebP, picks responsive sizes, and handleswidth/heightto prevent CLS. A raw<img>skips all of it. loading="eager"only for above-the-fold imagery — hero image, first card row, anything in the LCP candidate set. Everything below uses theloading="lazy"default. Eager loading off-screen images steals from the LCP budget.- Heavy embeds use facade components. YouTube, Spotify, Vimeo, etc. go through the facades in
src/components/(YouTubeFacade.astro,SpotifyFacade.astro). Never embed the third-party iframe directly — facades respect cookie consent and defer the real embed until the user interacts. - CSS over JS for animation and behavior. CSS transitions, keyframes,
:hover,:focus-visible, andIntersectionObservercover the vast majority of cases. Don't reach for a JS animation library when CSS does the job. - Update
public/_headersCSP before adding any third-party host. Scripts, fonts, iframes, images from a new origin all need the CSP updated first. Violations show up silently in PostHog when reporting is enabled (PUBLIC_POSTHOG_API_KEYset at build time triggers thereport-todirective). - Prefer
client:idleorclient:visibleoverclient:loadon Astro components.client:loadblocks the main thread during hydration;client:idlewaits for idle time andclient:visiblewaits until the component is on-screen. Useclient:loadonly when the component must be interactive on first paint. - Tracking scripts need consent. Anything that tracks visitors loads only after
window.hasAnalyticsConsent()is true, and must stop whenpassionfruit:consent-changedreports a withdrawal. Set host-only cookies, orCookieConsentcan't clear them.
Common mistakes
- Raw
<img src="...">instead of<Image>— loses AVIF/WebP, loses responsive sizing, often causes CLS. - YouTube iframe embedded directly — bloats LCP by hundreds of kilobytes, ignores cookie consent, drags in third-party JS before the user has shown intent.
client:loadon a component that only needs a CSS hover state. Hydration cost for nothing — strip the directive and use CSS.- Adding a third-party script, font, or embed and forgetting the CSP. The browser blocks it silently in production. Open DevTools → Console to see the CSP violation; better, update
public/_headersfirst. - Heavy
<script>blocks in component templates — Astro ships them as-is. Keep client scripts small and intentional; if it grows, move it to a real file and hydrate a small island. - Importing a large library to use one function. Tree-shaking helps but rarely fully. Prefer the standard-library equivalent or the small focused package.
Where to look
- This skill auto-loads on perf-touching edits — read it first.
public/_headers— CSP directives and cache rules (long-cache/_astro/*, short-revalidate HTML). Update the CSP here before adding any third-party host.src/components/YouTubeFacade.astroandsrc/components/SpotifyFacade.astro— the canonical facade patterns. Copy the shape if you need a new facade.scripts/postbuild-headers.mjs— wires up CSP violation reporting to PostHog (opt-in viaPUBLIC_POSTHOG_API_KEY).BaseLayout.astro— head-level perf knobs (preloads, font-display, locale-specific OG image).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

