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

Creating/updating a PR pull-requests.md 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