Agent-Skills.md

Agent Skills: Astro Islands Expert

Expert Astro Islands Architecture — client:load, client:idle, client:visible, client:media, client:only, server:defer (Server Islands), fallback slots, transition:persist, prop serialization. Use when adding interactivity to Astro pages or rendering dynamic server content.

UncategorizedID: fusengine/agents/astro-islands

Repository

fusengine/agents
fusengineLicense: MIT
7

Install this agent skill to your local

pnpm dlx add-skill https://github.com/fusengine/agents/tree/HEAD/plugins/astro-expert/skills/astro-islands

Skill Files

Browse the full folder contents for astro-islands.

Download Skill

Loading file tree…

plugins/astro-expert/skills/astro-islands/SKILL.md

Skill Metadata

Name
astro-islands
Description
Expert Astro Islands Architecture — client:load, client:idle, client:visible, client:media, client:only, server:defer (Server Islands), fallback slots, transition:persist, prop serialization. Use when adding interactivity to Astro pages or rendering dynamic server content.

Astro Islands Expert

Partial hydration architecture: zero JS by default, selective interactivity via directives.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

  1. fuse-ai-pilot:explore-codebase - Analyze existing components and hydration patterns
  2. fuse-ai-pilot:research-expert - Verify latest Islands docs via Context7/Exa
  3. mcp__context7__query-docs - Get client directive and server:defer examples

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

  • Adding interactive React/Vue/Svelte/Solid components to Astro pages
  • Deferring dynamic server content without blocking page load
  • Persisting component state during View Transitions
  • Optimizing Time to Interactive with lazy hydration

Why Islands Architecture

| Concept | Benefit | |---------|---------| | Zero JS by default | Maximum performance, minimal payload | | Selective hydration | Only interactive components ship JS | | server:defer | Dynamic server content without SSR blocking | | client:visible | Lazy-load below-fold components | | transition:persist | State survives page navigation |

Client Directives

| Directive | When JS Loads | Use Case | |-----------|--------------|----------| | client:load | Immediately on page load | Critical interactive UI | | client:idle | After requestIdleCallback | Non-critical UI | | client:visible | When component enters viewport | Below-fold components | | client:media="(query)" | When media query matches | Responsive components | | client:only="framework" | Client-only, no SSR | Components using browser APIs |

Server Islands

server:defer renders the component on the server after the page loads:

  • Uses slot="fallback" for placeholder content
  • Ideal for personalized or auth-gated content
  • Does not block initial page render
  • Requires a server adapter

Reference Guide

| Need | Reference | |------|-----------| | Architecture overview | overview.md | | Client directive details | client-directives.md | | server:defer patterns | server-islands.md | | transition:persist | transitions.md | | View Transitions (complete) | view-transitions.md | | Prop serialization rules | prop-serialization.md | | Interactive component | templates/interactive-island.md | | Server island with fallback | templates/server-island.md |

Best Practices

  1. Default to no directive — Ship zero JS unless interactivity is required
  2. Prefer client:visible — Defer below-fold components automatically
  3. client:only for browser APIs — localStorage, window, canvas
  4. server:defer for personalized content — Avatars, prices, auth state
  5. transition:persist — Preserve media players or forms during navigation