Astro Developer Skill

Context-loading skill for AI agents and developers working in the Astro monorepo. Loads relevant documentation based on your task.

Quick Decision Matrix

What are you doing?

→

Read these files:

Task

Primary Docs

Supporting Docs

Adding a core feature

architecture.md

,

constraints.md

testing.md

Fixing a bug

debugging.md

architecture.md

Writing/fixing tests

testing.md

constraints.md

Creating an integration

Explore

packages/integrations/

for examples

testing.md

Understanding architecture

architecture.md

-

Dealing with errors

debugging.md

,

constraints.md

testing.md

Understanding constraints

constraints.md

architecture.md

Critical Warnings

Before you start, be aware of these common pitfalls:

Prefer Unit Tests

Write unit-testable code by default. Use integration tests only when necessary →

testing.md

Node.js API Restrictions

Cannot use Node.js APIs in

runtime/

code →

constraints.md

Test Isolation

Must set unique

outDir

for each integration test →

testing.md

Runtime Boundaries

Core vs Vite vs Browser execution contexts →

architecture.md

Prerelease Mode

Changesets target origin/next branch (check .changeset/config.json ) Quick Command Reference

Development

pnpm install

Install (root only)

pnpm run build

Build all packages

pnpm run dev

Watch mode

pnpm run lint

Lint codebase

Testing

pnpm -C packages/astro exec astro-scripts test "test/*/.test.js"

All tests

pnpm -C packages/astro exec astro-scripts test -m "pattern"

Filter tests

pnpm run test:e2e

E2E tests

node --test test/file.test.js

Single test

Examples

pnpm --filter @example/minimal run dev

Run example

Changesets

pnpm exec changeset --empty

Create changeset, no interactive mode

Key File Paths

packages/astro/src/

├── core/ # Node.js execution context (build/dev commands)

├── runtime/

│ ├── server/ # Vite SSR execution context

│ └── client/ # Browser execution context

├── virtual-modules/ # Virtual module entry points

├── content/ # Content layer system

├── vite-plugin-*/ # Vite plugins

└── types/ # Centralized TypeScript types

packages/integrations/ # Official integrations

examples/ # Test your changes here

test/fixtures/ # Test fixtures

Note

Error stack traces in

node_modules/

map to source in

packages/

. See

architecture.md

for details.

Usage

This skill loads relevant context—it doesn't orchestrate workflows. After loading appropriate docs:

Read the recommended files for your task

Apply the patterns and constraints described

Use the commands and file paths provided

Search docs for error messages if you encounter issues

Architecture Quick Summary

Three Execution Contexts:

core/

→ Node.js, build/dev commands, avoid Node APIs except in Vite plugins

runtime/server/

→ Vite SSR, CANNOT use Node APIs

runtime/client/

→ Browser, CANNOT use Node APIs at all

Five Pipeline Types:

RunnablePipeline

→

astro dev

with Vite loader system

NonRunnablePipeline

→

astro dev

without runtime module loading (Cloudflare adapter)

BuildPipeline

→

astro build

+ prerendering

AppPipeline

→ Production serverless/SSR

ContainerPipeline

→ Container API

See

architecture.md

for complete details.

Testing Quick Summary

Philosophy

Prefer unit tests over integration tests. Write unit-testable code by default.

Unit tests

(fast, preferred):

Test pure functions and business logic

Extract business logic from infrastructure

Use dependency injection

Integration tests

(slow, use sparingly):

Only for features that cannot be unit tested (virtual modules, full build pipeline)

Always set unique

outDir

to avoid cache pollution

See

testing.md

for complete patterns and examples.

When NOT to Use This Skill

Bug triage

Use the

triage

skill instead

GitHub Actions analysis

Use the

analyze-github-action-logs

skill

Simple questions

Just ask directly, don't load this skill Related Documentation Root: /AGENTS.md Root: /CONTRIBUTING.md Astro docs: https://docs.astro.build/llms.txt Package: packages/astro/src/core/README.md Build plugins: packages/astro/src/core/build/plugins/README.md