🎯

astro

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill astro

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/astro
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/astro/
  • All projects ~/.claude/skills/astro/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Astro framework assistance covering content collections, Islands architecture, zero-JS by default, and multi-framework integration. Use when building content-focused websites, blogs, documentation, or marketing pages.

Astro

Astro is a content-driven web framework pioneering Islands Architecture, shipping zero client-side JavaScript by default and hydrating interactive components on demand.

When to Use

  • Content-Driven Websites & Portals: Blogs, documentation, marketing sites, and e-commerce product catalogs.
  • Zero-JS Default Architecture: Delivering maximum Lighthouse performance with Islands Architecture.
  • Multi-Framework Integrations: Mixing React, Vue, Svelte, and Solid components in a single project.
  • Hybrid Static & Server-Rendered Sites: Pre-rendering static pages while utilizing SSR routes for authenticated dashboards.

Quick Start

---
// Server-side code (Frontmatter) runs at build/request time
const data = await fetch('https://api.myjson.com').then(r => r.json());
---

<html>
  <body>
    <h1>{data.title}</h1>
    <!-- Client Directive: This React component hydrates on load -->
    <MyReactComponent client:load />

    <!-- This Svelte component hydrates only when visible -->
    <MySvelteComponent client:visible />
  </body>
</html>

Core Concepts

Component Islands & Client Directives

Hydrating JavaScript only where interactive functionality is required:

---
// Server-side script runs only during build or request rendering
import Header from '../components/Header.astro';
import InteractiveCart from '../components/InteractiveCart.jsx';
import Footer from '../components/Footer.astro';

const pageTitle = "Astro 5 E-Commerce";
---

<html lang="en">
  <head>
    <title>{pageTitle}</title>
  </head>
  <body>
    <!-- 0KB JavaScript: Static HTML -->
    <Header title={pageTitle} />

    <main>
      <h1>Featured Catalog</h1>
      <!-- Island hydrated only when visible in viewport -->
      <InteractiveCart client:visible initialCount={0} />
    </main>

    <!-- 0KB JavaScript -->
    <Footer />
  </body>
</html>

Content Collections with Type-Safe Schemas

Validating Markdown and MDX content with Zod schemas:

// src/content/config.ts
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    publishDate: z.date(),
    author: z.string().default("Core Team"),
    tags: z.array(z.string()),
    draft: z.boolean().default(false),
  }),
});

export const collections = {
  blog: blogCollection,
};

Server Endpoints & Dynamic API Routes

Exposing REST endpoints for dynamic data fetching:

// src/pages/api/newsletter.ts
import type { APIRoute } from "astro";

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();
  const email = data.email;

  if (!email || !email.includes("@")) {
    return new Response(JSON.stringify({ error: "Valid email required" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify({ message: "Subscribed successfully" }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
};

Common Patterns

Interactive Component Island with Client Directives

Problem: Shipping unnecessary JavaScript for largely static content pages.

Solution: Use Astro Islands architecture with client:visible or client:idle:

---
// src/pages/index.astro
import Layout from '../layouts/Layout.astro';
import StaticHero from '../components/StaticHero.astro';
import SearchBar from '../components/SearchBar.jsx'; // React component
---

<Layout title="Welcome">
  <!-- Rendered to pure zero-JS HTML -->
  <StaticHero title="Fast by default" />

  <!-- Hydrated only when visible in viewport -->
  <SearchBar client:visible />
</Layout>

Best Practices

Do:

  • Use Astro Server Islands (server:defer) to defer slow, dynamic parts of static pages for instant TTFB.
  • Leverage Content Collections for all Markdown and MDX files to ensure compile-time schema validation.
  • Use <Image /> component from astro:assets to automate WebP conversion and responsive srcset.
  • Keep interactive islands isolated and small (client:idle or client:visible).

Don't:

  • Use client:load on components below the fold; hydrate only when necessary.
  • Import client UI framework libraries into .astro frontmatter unless rendering them as islands.
  • Use client-side navigation (ViewTransitions) without auditing third-party script re-execution.

Troubleshooting

ErrorCauseSolution
Cannot find module '../components/...'Typo in component import or missing .astro file extension.Explicitly include .astro extension on all Astro component imports.
document is not definedAccessing browser DOM during static build SSR phase.Guard DOM access inside typeof document !== 'undefined' or client:only.
Content collection schema validation failedMarkdown frontmatter does not match Zod schema in src/content/config.ts.Correct frontmatter fields to adhere to the defined collection schema.

References

More from this repository10