astro-developer

AI Community

Repo stars 59,805
Author repo astro

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Comprehensive guide for developing in the Astro monorepo. Covers architecture, debugging, testing, and critical constraints. Use…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Quick Decision Matrix”, “Critical Warnings”, “Quick Command Reference”, “Key File Paths”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name astro-developer directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Quick Decision Matrix / Critical Warnings / Quick Command Reference” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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

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

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: AI
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @withastro · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: macOS · Linux · Windows
Runtime requirements: Node.js
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview astro-developer.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# 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](architecture.md), [constraints.md](constraints.md) | [testing.md](testing.md)           |
| Fixing a bug               | [debugging.md](debugging.md)                                         | [architecture.md](architecture.md) |
| Writing/fixing tests       | [testing.md](testing.md)                                             | [constraints.md](constraints.md)   |
| Creating an integration    | Explore `packages/integrations/` for examples                        | [testing.md](testing.md)           |
| Understanding architecture | [architecture.md](architecture.md)                                   | -                                  |
| Dealing with errors        | [debugging.md](debugging.md), [constraints.md](constraints.md)       | [testing.md](testing.md)           |
| Understanding constraints  | [constraints.md](constraints.md)                                     | [architecture.md](architecture.md) |

## Critical Warnings

**Before you start, be aware of these common pitfalls:**

1. **Prefer Unit Tests**: Write unit-testable code by default. Use integration tests only when necessary → [testing.md](testing.md)

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Quick Decision Matrix → Critical Warnings → Quick Command Reference → Key File Paths → Usage → Architecture Quick Summary
terms    -> What are you doing? · Read these files · Before you start, be aware of these common pitfalls · Prefer Unit Tests · Node.js API Restrictions · Test Isolation · Runtime Boundaries · Prerelease Mode
files/cmd -> packages/integrations/ · runtime/ · outDir · origin/next · .changeset/config.json · nodemodules/ · packages/ · astro dev
body sha256 -> acc6acff9bb8