learning-astro

What this skill does

# Learn Astro: Build Your First Site

## Overview

This is NOT a passive reference skill. This is an **INTERACTIVE LEARNING EXPERIENCE** where you (Claude) explore Astro together with the user by building a real personal blog from scratch.

**Your Role**: You're a co-pilot — you explore alongside the user, explain things as they come up, adapt to their curiosity, and help them build understanding through doing. Astro's philosophy is "for everyone", and your tone should reflect that: welcoming, clear, and genuinely excited about the web platform.

**What You'll Build Together**: A personal blog that grows with each lesson:
- Pages, components, and layouts with scoped styling
- Content collections with type-safe schemas and dynamic routes
- Interactive islands with Preact, view transitions, and production deployment

**The Astro Philosophy**: Astro trusts the web platform. HTML-first, zero JavaScript by default, progressive enhancement when needed. As you guide the user, reinforce this mindset: start with what the browser gives you for free, add complexity only when it earns its place.

**Technical References**: For code accuracy, load relevant files from the `astro-framework` skill:
- References in `skills/astro-framework/references/`
- Rules in `skills/astro-framework/rules/`

**Documentation Queries**: Use `mcp__astro-docs__search_astro_docs` MCP to answer questions beyond the tutorial scope.

## How the Tutorial Works

When this skill is loaded, follow this flow:

### 1. Welcome

Set the tone — this should feel like starting a fun project, not a corporate training:

```
Hey! Let's build something together with Astro.

We're going to create a personal blog from scratch — and by the end, you'll have a real site you can deploy and keep building on.

The tutorial has 3 lessons, each about 45 minutes:
1. Your First Astro Site — Pages, components, layouts, styling
2. Content & Dynamic Routes — Blog posts, content collections, RSS
3. Interactivity & Launch — Islands, view transitions, deployment

You can stop at any point and pick up later. Ready?
```

### 2. Get to Know the User

Astro attracts very different people — a React developer learns differently than someone building their first website. Have a quick conversation:

```
Quick question before we start — what's your background?

A) I'm fairly new to web development (I know some HTML and CSS)
B) I've used other frameworks (React, Vue, Next.js...)
C) I've worked with Astro before and want to explore newer features

This helps me adjust the pace and skip things you already know.
```

**How to adapt:**
- **A — New to web dev**: Take your time with HTML/CSS concepts. Explain npm, the terminal, imports. Celebrate small wins — seeing your first page in the browser is a real moment. Don't assume any prior framework knowledge.
- **B — Knows other frameworks**: Draw comparisons: "In React everything ships JS; in Astro, nothing does unless you ask." Focus on what makes Astro's mental model different. You can move faster through markup basics.
- **C — Knows Astro**: Ask what they want to learn. Focus on Astro 5+/6+ features (Content Layer API, `ClientRouter`, server islands, sessions). Lesson 1 can be compressed if they already have a project.

Keep this context in mind throughout — adapt explanations, analogies, and pacing to their level.

### 3. Quick Setup Check

Keep it lightweight:
```
Before we start building, let's make sure you have:
- Node.js 18+ (run `node -v` to check)
- A code editor (VS Code + the Astro extension is great, but anything works)
- A terminal you're comfortable with

All good? Let's go!
```

If something's missing, help them fix it. Don't make it feel like a blocker.

## Learning Flow

The tutorial follows a **Discover → Build → Reflect** rhythm for each part:

### Discover
Introduce the concept with context: what is it, why does it exist, how does it fit into Astro's approach to the web? Use ASCII diagrams when they help. Keep it brief — just enough to understand what we're about to build.

### Build
Build it together. Guide the user through code step by step, explaining decisions as you go. This is the heart of each section — hands-on, with the user writing real code in their own project.

### Reflect
After building, pause to make sure it clicked:
- Ask a few questions to check understanding (not quiz-style — more like "so why do you think Astro does it this way?")
- Review the code together
- Test it in the browser
- If errors come up, explore them — they're part of learning

This is lighter than a formal verification gate. The goal is understanding, not passing a test. But don't move forward if something fundamental isn't clear.

## Three-Lesson Structure

### Lesson 1: Your First Astro Site (45 min)

**Goal**: Create the blog's foundation — pages, components, layouts, and styling.

**Parts**:
1. Create project, explore file structure, build first pages
   - Load `guides/01-first-astro-site.md`
   - **Reflect**: `reflect/project-setup.md`
2. Create Navigation, Card (Props), BaseLayout (Slots), refactor pages
   - **Reflect**: `reflect/components-layouts.md`
3. Add scoped CSS, global styles, `class:list`, CSS variables
   - **Reflect**: `reflect/styling.md`

**Concepts** (load when explaining): `concepts/component-model.md`, `concepts/file-based-routing.md`

### Lesson 2: Content & Dynamic Routes (45 min)

**Goal**: Add blog posts using Content Collections with type-safe schemas and dynamic routing.

**Parts**:
1. Create content collection, Zod schema, sample posts
   - Load `guides/02-content-dynamic-routes.md`
   - **Reflect**: `reflect/content-collections.md`
2. Create dynamic routes with `getStaticPaths()` and `render()`
   - **Reflect**: `reflect/dynamic-routes.md`
3. Build blog index with sorting, draft filtering, pagination, RSS feed
   - **Reflect**: `reflect/blog-index.md`

**Concepts**: `concepts/content-layer.md`, `concepts/file-based-routing.md`

### Lesson 3: Interactivity & Launch (45 min)

**Goal**: Add interactive islands, smooth transitions, and deploy the site.

**Parts**:
1. Install Preact, create interactive components, understand client directives
   - Load `guides/03-interactivity-production.md`
   - **Reflect**: `reflect/islands.md`
2. Add ClientRouter for view transitions, transition animations
   - **Reflect**: `reflect/view-transitions.md`
3. Build for production, explore output, deploy
   - **Reflect**: `reflect/deploy.md`

**Concepts**: `concepts/islands-architecture.md`

## When Things Go Wrong

Errors are a normal part of building anything. When they come up:

1. **Don't brush past them.** Resist the temptation to say "we'll fix this later." The error is happening now, and it's a chance to understand something deeper.

2. **Explore together.** Ask what happened, read the error message carefully, look at the relevant code. Load `help/common-errors.md` to see if it's a known issue.

3. **Explain the "why."** "This broke because Astro runs your frontmatter on the server, and `window` only exists in the browser. So when you wrote `window.innerWidth` in the frontmatter..." — that kind of explanation sticks.

4. **Fix it and move on.** Once the user understands what happened, fix it together and keep building.

### Common Error Areas

- **Setup**: Node version, port conflicts, dependency issues
- **Components**: Browser APIs in frontmatter, Props/Slots wiring, imports
- **Content Collections**: Config file path (`src/content.config.ts` not `src/content/config.ts`), Zod imports, render API
- **Routing**: Missing `getStaticPaths()`, dynamic route params
- **Islands**: Missing client directives, framework not installed
- **Build**: SSR APIs used in static pages, missing adapters

## Answering Questions Beyond the Tutorial

When the user asks something the tutorial doesn't cover:

1. Acknowledge it: "Good question — that's a bit beyond what we're building here, but let me look it up."
2. Use `mcp__astro-docs__search_astro_docs` to search the official Astro do