# Astro Guide

> Use when editing or scaffolding Astro sites with islands architecture. Triggers on `.astro` files, `astro:content` imports, `Astro.props`, `client:` hydration directives, content-collection schemas, and on prompts about pages, layouts, MDX, content collections, image optimization, view transitions, or accessibility in an Astro project, even when the user doesn't say 'Astro'.

- Skill: `xonovex/astro-guide` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add xonovex/astro-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xonovex/astro-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: xonovex (https://skillmd.com/u/xonovex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xonovex/astro-guide

---


# Astro Coding Guidelines

## Essentials

- **Islands architecture** - Default to static HTML, hydrate only where needed, see [references/islands-architecture.md](references/islands-architecture.md)
- **Project structure** - Use `src/pages`, `src/components`, `src/layouts`, `src/content`, see [references/project-structure.md](references/project-structure.md)
- **Content collections** - Use `astro:content` with schema-validated frontmatter; schema design in **zod-guide**, see [references/content-collections.md](references/content-collections.md)
- **Framework components** - Integrate React, Vue, or other frameworks, see [references/components.md](references/components.md)
- **Accessibility** - Use semantic HTML, alt text, ARIA as needed, see [references/accessibility.md](references/accessibility.md)

## Gotchas

- Default rendering is server-side / static: components don't ship JavaScript unless explicitly hydrated with `client:*` directives
- Content Collections enforce a Zod schema at build time; an invalid frontmatter field fails the build, not the page
- `Astro.glob()` is build-time and scans at compile; runtime data needs `getStaticPaths` or endpoints
- Framework components (React/Vue/Svelte) only hydrate on the directive you pick: `client:load`, `client:idle`, `client:visible`, `client:media`, `client:only`

## Progressive disclosure

- Read [references/islands-architecture.md](references/islands-architecture.md) - Load when deciding which components need client-side JavaScript
- Read [references/project-structure.md](references/project-structure.md) - Load when organizing files and directories
- Read [references/content-collections.md](references/content-collections.md) - Load when managing blog posts, docs, or structured content
- Read [references/components.md](references/components.md) - Load when integrating React, Vue, or other framework components
- Read [references/accessibility.md](references/accessibility.md) - Load when adding keyboard navigation or screen reader support