/astro-sites-manager

name: astro-sites-manager
description: >
  Comprehensive skill for building, migrating, and maintaining Astro v7
  projects. Covers best practices from the official AGENTS.md, the v6→v7
  migration path, validation of breaking/deprecated patterns, AI-enhanced dev
  server usage (background mode, JSON logging), advanced routing with
  src/fetch.ts, route caching, Sätteri Markdown, and the Rust compiler. Use
  when the user mentions 'Astro', '.astro files', 'astro dev', 'astro build',
  'islands architecture', 'content collections', 'SSG', 'SSR adapter',
  'upgrade to Astro 7', 'migrate Astro', 'Astro v7', 'Astro v6', 'Sätteri',
  'route caching', 'Astro.cache', 'astro dev --background', 'src/fetch.ts',
  'advanced routing', 'Hono + Astro', 'Rolldown', 'Vite 8', 'queued
  rendering', 'CDN cache provider', 'Astro AI', 'related content',
  'related posts', 'vector embeddings Astro', 'astro-related-content',
  or asks about static site generation with Astro.
metadata:
  author: ft.ia.br
  version: "1.0.0"
  date: 2026-06-22
  repository: https://github.com/fabricioctelles/skills
  license: Apache-2.0
  category: ci-cd-and-deployment

Astro Framework — v7

MCP Documentation Access

This skill works alongside the **Astro Docs MCP server**. Before answering Astro questions, check if the `astro-docs` MCP tool is available and query it for the latest documentation. The MCP server provides real-time access to docs.astro.build and is the single source of truth for current APIs.

MCP Server: astro-docs
Tool: search_astro_docs

If the MCP server is unavailable, fall back to the reference material in this skill and https://docs.astro.build.

---

Best Practices

Component Design

• One `.astro` component per file. Keep components small and focused.
• Use frontmatter (`---`) for data fetching and logic; template below for markup only.
• Prefer Astro components over framework components unless client interactivity is needed.
• Use `client:*` directives sparingly — each adds JavaScript to the bundle.
• Directive hierarchy: `client:idle` > `client:visible` > `client:load` (prefer lazy).

Routing & Pages

• Use file-based routing in `src/pages/`. Dynamic routes: `[slug].astro`, `[...path].astro`.
• Always export `getStaticPaths()` for prerendered dynamic routes.
• For SSR pages: `export const prerender = false` at the top.
• Use `src/fetch.ts` (v7) only when you need control beyond middleware — don't use it for simple auth.

Content Collections

• Define schemas in `content.config.ts` with Zod — never trust untyped content.
• Use `getCollection()` for lists, `getEntry()` for single items.
• Prefer `glob()` loader for local files, custom loaders for CMS data.

Performance

• Default to static (`prerender = true`). Use SSR only for personalized/dynamic content.
• Use `<Image />` from `astro:assets` — never raw `<img>` for local images.
• Prefer Sätteri (default v7) over unified for Markdown — it's significantly faster.
• Use Server Islands (`server:defer`) for mixing static shells with dynamic fragments.

Styling

• Scoped `<style>` in `.astro` files is default and preferred.
• Use `is:global` only when truly needed (third-party component styling).
• Tailwind: install with `astro add tailwind`, don't configure manually.

TypeScript

• Run `astro sync` after changing content schemas or env variables.
• Run `astro check` before committing — catches template type errors other tools miss.
• Use `astro:env/server` and `astro:env/client` for typed env variables (never `process.env` directly).

Development Workflow

• Use `astro dev` for HMR. Never use `python -m http.server` or other static servers.
• Use `astro add` for official integrations — don't manually edit config for them.
• Use `astro build && astro preview` to test production behavior locally.
• In AI agent workflows: use `astro dev --background` and validate via `/_astro/status`.

---

CLI Commands

npx astro dev              # Dev server (foreground)
npx astro dev --background # Dev server (detached, for AI agents)
npx astro dev --json       # Dev server with JSON structured logs
npx astro build            # Production build
npx astro preview          # Serve production build locally
npx astro check            # Type checking and diagnostics
npx astro sync             # Generate TypeScript types
npx astro add <integration># Install and configure integration

Background Dev Server (AI Agents)

When working as an AI agent, use background mode:

# Start (blocks until ready, then detaches)
astro dev --background
# → Dev server running at http://localhost:4321 (pid 12345)

# Check status
astro dev status

# Read logs
astro dev logs

# Stop
astro dev stop

# Health check endpoint (JSON)
curl http://localhost:4321/_astro/status
# → {"ok": true}

**Key behaviors:**

• Lockfile prevents duplicate instances — starting again returns existing instance
• All commands are idempotent (stop when not running = silent success)
• Auto-detected when running inside an AI agent (no flag needed)
• Opt out: `ASTRO_DEV_BACKGROUND=0 astro dev`

---

Project Structure

src/
├── pages/          # File-based routing (.astro, .md, .mdx)
├── layouts/        # Reusable page layouts
├── components/     # Astro & framework components
├── content/        # Content collections (type-safe)
├── middleware.ts   # Request middleware
├── fetch.ts        # Advanced routing (v7, optional)
├── styles/         # Global CSS
├── assets/         # Optimized assets (images, fonts)
├── actions/        # Server actions
└── env.d.ts        # Environment type declarations
astro.config.mjs    # Main configuration
content.config.ts   # Content collection schemas
tsconfig.json       # TypeScript config

---

Configuration (v7)

import { defineConfig, memoryCache, logHandlers } from 'astro/config';

export default defineConfig({
  // Output mode
  output: 'static', // or configure per-page with server adapte