Skip to main content
skill CX Codex

astro · oakoss — Claude Code skill: what it does, how to install

Feeds the agent Astro patterns: content collections, island hydration, view transitions, rendering modes. Useful when most pages are static with a few interactive parts.

MIT 111 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill astro -a claude-code
Open on GitHub

What astro does

The skill hands the agent a reference for Astro: content collections with Zod schemas and loaders, island hydration directives (client:load, client:idle, client:visible, client:only), view transitions through <ClientRouter />, static and server output modes, server islands, Astro DB and onRequest middleware. It also lists common mistakes, such as putting a client: directive on a plain .astro component or naming the collections file anything other than src/content.config.ts.

Hydration is where the choices matter. client:load fires right away, client:idle and client:visible wait, and client:only needs the framework name spelled out. The skill carries user-invocable: false, so the agent picks it up on its own once a task touches a content site. For a highly interactive single-page app it is the wrong tool, and the author says so.

Install with npx skills add oakoss/agent-skills --skill astro -a claude-code; the file lands at ~/.claude/skills/astro/SKILL.md.

What it helps with

  • describe a blog collection schema in src/content.config.ts with Zod validation
  • pick a hydration directive for one interactive widget on a static page
  • render React components inside an .astro page
  • generate routes from collection entries with getStaticPaths()
  • check auth in onRequest middleware before routes run

Example prompts for the agent

  • Set up a blog content collection with a Zod schema and list the posts with getCollection.
  • Keep the site on output: 'static' and switch the /dashboard page to prerender = false.
  • Add <ClientRouter /> to the shared layout to turn on view transitions.

How to install astro

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill astro -a claude-code

2Manually: put the files in place

~/.claude/skills/astro/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/astro/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about astro

How do I install the astro skill in Claude Code?

Run npx skills add oakoss/agent-skills --skill astro -a claude-code. The skill file is written to ~/.claude/skills/astro/SKILL.md.

What does the astro skill do?

It gives the agent Astro patterns for content collections, island hydration, view transitions, rendering modes, Astro DB and middleware, plus a list of common mistakes.

Which rendering mode fits a mostly static site?

Keep output: 'static' and set prerender = false only on the pages that need a server. Moving everything to output: 'server' renders every page on demand.

Source text

SKILL.md · MIT
---
name: astro
description: |
  Astro web framework patterns for content-driven sites. Covers content collections with Zod schemas and loaders, island architecture with selective hydration directives, view transitions with ClientRouter, server-side and hybrid rendering modes, server islands, Astro DB with astro:db, middleware with onRequest, and framework integrations (React, Svelte, Vue).

  Use when building content-driven websites, configuring island hydration strategies, setting up view transitions, choosing between static and server rendering, integrating UI framework components, defining content collection schemas, or adding middleware.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://docs.astro.build'
user-invocable: false
---

# Astro

## Overview

Astro is an **all-in-one web framework** for building fast, content-focused websites. It uses an islands architecture that ships zero JavaScript by default, hydrating only interactive components on demand. Components from React, Svelte, Vue, Solid, and Preact can coexist in a single project.

**When to use:** Content-driven sites (blogs, docs, marketing), portfolios, e-commerce storefronts, any site where most pages are primarily static with isolated interactive regions.

**When NOT to use:** Highly interactive single-page applications (dashboards, real-time collaboration tools), apps requiring full client-side routing with shared global state across all components.

## Quick Reference

| Pattern                | API / Directive                                   | Key Points                                            |
| ---------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| Content collection     | `defineCollection({ loader, schema })`            | Zod schemas, glob/file loaders, type-safe queries     |
| Query collection       | `getCollection('blog')`                           | Returns typed array, supports filter callback         |
| Single entry           | `getEntry('blog', 'my-post')`                     | Fetch by collection name and entry ID                 |
| Island (load)          | `<Component client:load />`                       | Hydrate immediately on page load                      |
| Island (idle)          | `<Component client:idle />`                       | Hydrate when browser is idle                          |
| Island (visible)       | `<Component client:visible />`                    | Hydrate when component enters viewport                |
| Island (media)         | `<Component client:media="(max-width: 768px)" />` | Hydrate on media query match                          |
| Island (client-only)   | `<Component client:only="react" />`               | Skip SSR, render only on client                       |
| View transitions       | `<ClientRouter />`                                | Add to `<head>`, enables SPA-like navigation          |
| Persist state          | `transition:persist`                              | Maintain island state across navigations              |
| Programmatic navigate  | `navigate(href)`                                  | Client-side navigation from scripts                   |
| Static output          | `output: 'static'`                                | Pre-render all pages at build time (default)          |
| Server output          | `output: 'server'`                                | Server-render all pages on demand                     |
| Hybrid (opt-in SSR)    | `output: 'static'` + per-page `prerender = false` | Static by default, opt individual pages into SSR      |
| Hybrid (opt-in static) | `output: 'server'` + per-page `prerender = true`  | SSR by default, opt individual pages into static      |
| Server islands         | `<Component server:defer />`                      | Defer server rendering for dynamic content in static  |
| Middleware             | `onRequest(context, next)`                        | Runs before every route, chain with `sequence()`      |
| Astro DB table         | `defineTable({ columns })`                        | Type-safe SQL with column definitions                 |
| Framework component    | Import `.jsx` / `.svelte` / `.vue`                | Auto-detected by file extension                       |
| Integration            | `astro add react`                                 | CLI to add framework adapters and tools               |
| Render content         | `const { Content } = await entry.render()`        | Compile Markdown/MDX to component                     |
| Dynamic routes         | `getStaticPaths()` + collection query             | Generate pages from collection entries                |
| API endpoint           | `export const GET: APIRoute`                      | Server-rendered REST endpoints                        |
| Shared island state    | `nanostores`                                      | Reactive state across framework boundaries            |
| Environment variables  | `import.meta.env.PUBLIC_*`                        | `PUBLIC_` prefix for client-accessible vars           |
| Transition animation   | `transition:animate="slide"`                      | `initial`, `fade`, `slide`, `none`                    |
| Prefetch links         | `data-astro-prefetch`                             | `hover`, `viewport`, `load`, or `false`               |
| Collection reference   | `reference('authors')`                            | Type-safe cross-collection relations                  |
| Script re-execution    | `data-astro-rerun`                                | Re-run `<script>` on every view transition navigation |
| Redirect               | `context.redirect(url, status)`                   | Redirect from middleware or server pages              |

## Common Mistakes

| Mistake                                           | Correct Pattern                                                           |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| Adding `client:` directive to `.astro` components | Only UI framework components (React, Svelte, Vue) accept `client:`        |
| Using `client:load` everywhere                    | Default to `client:idle` or `client:visible`; use `client:load` sparingly |
| Forgetting framework string with `client:only`    | Must specify framework: `client:only="react"`                             |
| Mixing framework components in non-Astro files    | Only `.astro` files can compose components from multiple frameworks       |
| Using `output: 'server'` for mostly static sites  | Use `output: 'static'` with per-page `prerender = false` for hybrid       |
| Omitting `<ClientRouter />` for view transitions  | Must be in `<head>` of every page (use shared layout)                     |
| Content config not at `src/content.config.ts`     | File must be named `content.config.ts` in `src/` root                     |
| Not awaiting `getCollection()` calls              | Always `await` collection queries in frontmatter                          |
| Importing from `astro:content` in client scripts  | Content APIs are server-only; pass data as props to client components     |
| Placing middleware outside `src/middleware.ts`    | Middleware must be at `src/middleware.ts` or `src/middleware/index.ts`    |
| Passing functions as props to islands             | Only serializable data crosses the server/client boundary                 |
| Using `transition:persist` without matching pages | Component must appear on both old and new page with same persist value    |
| Missing adapter for server/hybrid mode            | Install an adapter: `npx astro add vercel` (or node, netlify, etc.)       |

## Delegation

- **Pattern discovery**: Use `Explore` agent
- **Build configuration**: Use `Task` agent
- **Code review**: Delegate to `code-reviewer` agent

> If the `tailwind` skill is available, delegate styling and Tailwind CSS configuration to it.
> If the `vitest` skill is available, delegate unit testing patterns to it.
> If the `playwright` skill is available, delegate end-to-end testing patterns to it.
> If the `vite` skill is available, delegate build configuration and Vite plugin setup to it.
> If the `drizzle` skill is available, delegate advanced database query patterns to it.
> If the `sentry` skill is available, delegate error monitoring and observability setup to it.
> If the `pino-logging` skill is available, delegate server-side logging configuration to it.
> If the `tanstack-query` skill is available, delegate client-side data fetching and caching to it.

## References

- [Content collections, schemas, loaders, and querying](references/content-collections.md)
- [Island architecture and hydration directives](references/island-architecture.md)
- [View transitions and client-side navigation](references/view-transitions.md)
- [Rendering modes: static, server, and hybrid](references/rendering-modes.md)
- [Middleware patterns and request handling](references/middleware.md)
- [Framework component integration (React, Svelte, Vue)](references/framework-integration.md)
- [Astro DB schema, seeding, and queries](references/astro-db.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

astro by other authors comes first.

astro astrolicious Teaches your agent the Astro web framework: pages, components, SSR adapters, content collections and deployment. Useful once a project is on Astro. CX Codex +1 20,000installs astro Mindrally Tells the agent how to build Astro sites: static generation, partial hydration, file-based routing and as little client-side JavaScript as possible. CX Codex +1 933installs astro suhaibjanjua This skill guides Astro projects with Markdown or MDX content and selectively hydrated interactive components. Use it for blogs, documentation, and portfolio sites. CX Codex +1 157installs astro-framework delineas astro-framework — a skill that turns your coding agent into a senior Astro engineer. Useful once a content site needs islands, server rendering or the Content Layer API. CX Codex +1 2,200installs clerk-astro-patterns clerk clerk-astro-patterns — a skill for Claude Code that guides Clerk authentication patterns in Astro 5. Sets up middleware, server-rendered views, client islands, and API endpoints. CX Codex +1 15,000installs integration-astro-ssr PostHog integration-astro-ssr adds PostHog analytics to server-rendered Astro setups with API endpoints. Connects frontend tracking with backend routes. CX Codex +1 109installs astro-sites-manager ft.ia.br astro-sites-manager is a Claude Code skill for setting up and updating Astro v7 projects, configuring background dev servers for AI workflows, and querying the astro-docs MCP server. CX Codex +1 ★ 141repo stars astro-expert 0xfurai astro-expert is a Claude Code subagent for planning Astro architecture, organizing content collections, and optimizing static site performance. CX Codex ★ 1,029repo stars islands-architecture patterns.dev Teaches the agent the islands architecture pattern. It covers content-heavy pages where most of the markup is static and only a few regions need interactivity. CX Codex +1 646installs

From the same set106

The whole set →
meta-skill-creator The meta-skill-creator skill guides you through building and validating agent skills that follow the Agent Skills open standard. Use it to plan a SKILL.md and organize supporting files. CX Codex +1 114installs figma-developer figma-developer pulls colours, type styles and icons out of Figma over the REST API and turns them into CSS variables and React components. Useful when the design file moves faster than your code. CX Codex +1 114installs tanstack-store A reference skill that teaches the agent how TanStack Store works: stores, derived values, batching, effects. Useful when state is shared across components. CX Codex +1 113installs hono Guides coding agents in building lightweight APIs, middleware pipelines, and RPC servers using the Hono framework. CX Codex +1 112installs db-enforcer db-enforcer is a Claude Code skill that checks PostgreSQL integrity and alignment with Prisma. It activates for schema design, migration work, and RLS policy setup. CX Codex +1 109installs electricsql Briefs your coding agent on ElectricSQL: streaming slices of Postgres to the client through Shapes, plus the proxy and write patterns around it. CX Codex +1 109installs trpc trpc is a Claude Code skill for building type-safe TypeScript APIs with tRPC v11. It comes into play when working on routers, procedures, React clients, or tests. CX Codex +1 109installs tauri This Claude Code skill covers Tauri v2 apps with web frontends and Rust backends. It activates for project setup, IPC, permissions, or app releases. CX Codex +1 108installs

Project sponsors

Companies that keep this analytics open