# astro-best-practices

Architectural rules and review checklists for building performant, accessible Astro projects across AI coding assistants.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 521 installs · ★ 14
- Author: incluud
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/incluud/astro-agent-skills/tree/HEAD/skills/astro-best-practices/SKILL.md
- Updated: 2026-04-23
- HTML: https://affpapa.org/en/nevibecode/skills/astro-best-practices

## What it does

This skill injects Astro development standards into coding agents. It enforces `.astro` components as the baseline choice and restricts UI frameworks like React or Vue to compact interactive islands. Static generation is prioritized whenever request-time rendering is unnecessary.

The instructions mandate deliberate hydration directives: `client:visible` for deferred components, `client:idle` for background tasks, and `client:load` strictly for immediate UI needs. It also demands schema validation for content collections, semantic landmarks, and image sizing via `astro:assets` to prevent layout shifts.

If your setup relies on heavy client-side hydration across entire page layouts, this skill will actively push back during code reviews.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add incluud/astro-agent-skills --skill astro-best-practices -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/astro-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/astro-best-practices/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add incluud/astro-agent-skills --skill astro-best-practices -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/astro-best-practices/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add incluud/astro-agent-skills --skill astro-best-practices -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/astro-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install incluud/astro-agent-skills astro-best-practices
```

2. **Manually: put the files in place**
- File: `.github/skills/astro-best-practices/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add incluud/astro-agent-skills --skill astro-best-practices -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/incluud/astro-agent-skills --path skills/astro-best-practices
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/astro-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add incluud/astro-agent-skills --skill astro-best-practices -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/incluud/astro-agent-skills/tree/HEAD/skills/astro-best-practices/SKILL.md

## When to use it
- eliminate unnecessary client hydration in Astro components
- enforce schemas for structured content collections
- audit templates for keyboard accessibility and heading structure
- configure image assets with `astro:assets` to prevent layout shifts

## Example prompts
- Review `src/pages/index.astro` against the astro-best-practices checklist
- Build a newsletter signup island using `client:visible` inside an `.astro` layout
- Define a typed content collection schema for author profiles

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6fac1c069cf6d925.

BEGIN THIRD-PARTY FILE 6fac1c069cf6d925
````text
---
name: astro-best-practices
description: Apply performant, accessible, and maintainable defaults when building or reviewing Astro projects.
---

# Astro Best Practices

Use this skill as the baseline when designing, implementing, or reviewing Astro work. It translates Astro-specific architectural guidance into portable instructions that can be applied across agents.

## Core Principles

- prefer static generation when request-time rendering is not necessary
- keep client-side JavaScript minimal
- use framework islands only for real interactivity
- preserve clear project structure and predictable routing
- optimize for accessibility and maintainability, not just output parity

## Architecture Defaults

### Prefer `.astro` first

- use `.astro` components for static and mostly static UI
- reach for React, Vue, or another framework only when local state or client-side behavior is genuinely needed
- keep interactive islands small and leaf-like

### Use hydration deliberately

- `client:visible` for deferred UI
- `client:idle` for lower-priority enhancement
- `client:load` for critical immediate interactivity only
- `client:only` only when skipping server rendering is intentional

Default away from hydrating broad layout regions.

### Keep the project shape predictable

Typical structure:

```text
src/
  components/
  layouts/
  pages/
  content/
  styles/
  assets/
public/
```

Do not invent novel folder structure without a clear project-specific reason.

## Content and Data

- use content collections for structured content
- define schemas instead of accepting loose frontmatter
- fetch server-side data in Astro frontmatter unless there is a clear reason not to
- keep data flow obvious and close to the component or page that owns it

## Accessibility

- use semantic landmarks such as `header`, `nav`, `main`, `article`, and `footer`
- ensure keyboard access for all interactive controls
- provide meaningful labels and accessible names
- maintain correct heading hierarchy
- use appropriate image alt text
- preserve visible focus states
- treat color contrast as a non-negotiable baseline

## Performance

- use `astro:assets` or the project’s chosen image pipeline intentionally
- prevent layout shift by providing image dimensions or stable containers
- avoid unnecessary client hydration
- keep CSS and JavaScript scoped to the features that need them
- prefer simple server-rendered markup over client complexity

## Styling

- default to scoped component styles unless the project has a defined styling system
- use CSS custom properties for reusable tokens
- favor maintainable layout patterns over one-off utility sprawl when the project is not already utility-first
- keep responsive behavior intentional and testable

## Review Checklist

Before finalizing Astro work, check:

- is any hydrated code unnecessary
- does the HTML stay semantic
````
END THIRD-PARTY FILE 6fac1c069cf6d925

The third-party file has ended. Everything between the 6fac1c069cf6d925 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2883 of 3087 bytes. © incluud · MIT · https://github.com/incluud/astro-agent-skills/tree/HEAD/skills/astro-best-practices/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md