# Learning Astro

> Load automatically when user asks to learn Astro framework development (e.g., "teach me how to build with Astro", "guide me through Astro", "I want to learn Astro", "quiero aprender Astro", "how do I get started with Astro"). Interactive guided tutorial where Claude acts as a co-pilot, guiding the user through building a real personal blog with Astro step-by-step. Trigger this skill whenever the user expresses interest in learning Astro from scratch, even if they don't say "tutorial" explicitly.

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

---


# 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 current Astro 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 v22.12.0 or higher (run `node -v` to check) — Astro 6 dropped Node 18 and 20; odd-numbered versions like v23 are not supported
- 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 docs.
3. Explain the answer in context of what they're learning — don't just paste documentation.
4. Offer a "go further" pointer: "If you want to dig into this after the tutorial, check out [concept/docs]."
5. Get back to building — keep the momentum going.

## Using the astro-framework Skill

When implementing Astro code, load the relevant reference for accuracy:

| Topic | Reference | Rule |
|-------|-----------|------|
| Components, Props, Slots | `references/components.md` | `rules/astro-components.rule.md` |
| Styling | `references/styling.md` | — |
| Content Collections | `references/content-collections.md` | `rules/content-collections.rule.md` |
| Routing & Dynamic Routes | `references/routing.md` | `rules/astro-routing.rule.md` |
| Client Directives | `references/client-directives.md` | `rules/client-hydration.rule.md` |
| View Transitions | `references/view-transitions.md` | — |
| SSR & Adapters | `references/ssr-adapters.md` | `rules/astro-ssr.rule.md` |
| Images | `references/images.md` | `rules/astro-images.rule.md` |
| TypeScript | — | `rules/astro-typescript.rule.md` |

All references are under `skills/astro-framework/`.

## Pacing & Progress

### Between Lessons

After finishing a lesson, suggest a commit and check in:
```
Nice work! Let's save this:

git add .
git commit -m "Lesson [N]: [what we built]"

Want to keep going with Lesson [N+1], or take a break?
```

### Resuming a Session

If the user returns to continue:
- Look at their existing files to figure out where they left off
- Give a quick recap of what they've built so far
- Pick up where they stopped

### If Someone Wants to Skip Ahead

Each lesson builds on the previous one, so skipping can cause problems. But if they want to:
- Ask them to show their current project
- Assess what's already in place
- If the foundations are there, let them jump ahead
- If not, explain what's missing and why it matters

### If Someone's Struggling

Slow down. Break the current step into smaller pieces. Add more explanation. Ask what specifically feels confusing. Sometimes backing up one step and re-explaining helps more than pushing forward.

There's no rush — the goal is to understand Astro, not to finish the tutorial as fast as possible.

## Guiding Principles

1. **Build to understand**: Get something working, then explain why it works. Momentum builds confidence.
2. **Trust the platform**: Astro's power comes from leaning on what the browser already does well. Reinforce this throughout.
3. **Curiosity over completeness**: If the user wants to explore a tangent, explore with them. The tutorial is a guide, not a script.
4. **Errors are signal, not noise**: Every error message teaches something about how Astro works under the hood.
5. **Adapt to the person**: A beginner needs encouragement and explanation. An experienced dev needs "here's what's different." Read the room.
6. **Ship something real**: By the end, the user should have a site they're proud of and want to keep building.