Agent Skill for Astro Blog

Agents generate outdated Astro patterns without knowing Astro 6’s breaking changes.
The Astro Docs MCP only works when the agent asks, and agents don’t ask when they think they’re right.
So I made an Agent Skill that the agent references before generating code.

This blog is built with Astro. I’ve been working on it with Claude Code and Codex, and I noticed agents repeatedly generate incorrect Astro code. Astro 6 introduced significant breaking changes, but agents have mostly been trained on Astro 3/4/5 era code, so they generate old patterns without realizing they’re wrong.

I also use the Astro Docs MCP, but MCP only activates when the agent asks a question. When an agent writes entry.render(), it doesn’t ask MCP “has this API changed?” It’s confident the pattern is correct and just generates the code. If MCP answers “how do I use this?”, what I needed was something that says “not like that.”

So I made an Agent Skill. It’s essentially a set of guidelines the agent references before generating code, and it complements MCP rather than replacing it.

What Agents Repeatedly Get Wrong

A few representative examples make the situation clear.

In Astro 6, render() changed from an entry method to a standalone function. Ask an agent to render a blog post and it will almost certainly use post.render().

1
// what the agent generates
2
const { Content } = await post.render()
3

4
// what changed in Astro 6
5
import { render } from 'astro:content'
6
const { Content } = await render(post)

Astro.glob() was removed entirely in Astro 6, but agents still use it when fetching post lists.

1
// removed API
2
const posts = await Astro.glob('./posts/*.md')
3

4
// Content Collections is the replacement
5
import { getCollection } from 'astro:content'
6
const posts = await getCollection('blog')

Astro 6 ships Zod 4, where both the import path and validator chaining have changed.

1
// Zod 3 syntax
2
import { defineCollection, z } from 'astro:content'
3
z.string().email()
4

5
// Zod 4 syntax
6
import { defineCollection } from 'astro:content'
7
import { z } from 'astro/zod'
8
z.email()

Content Collections now require an explicit loader, and the config file moved from src/content/config.ts to src/content.config.ts.

1
// doesn't work without a loader
2
const blog = defineCollection({ schema: z.object({...}) })
3

4
// loader is required, schema is a function
5
import { glob } from 'astro/loaders'
6
const blog = defineCollection({
7
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
8
  schema: ({ image }) => z.object({...})
9
})

I’ve cataloged about 20 patterns like these, including Tailwind v4’s CSS-native config, agents applying client:load to every component, and event listeners breaking under <ClientRouter />.

Design Principles

I referenced Thariq’s Lessons from Building Claude Code: How We Use Skills while putting this together. It covers how Anthropic runs hundreds of skills internally. Beyond the basics like gotchas-first structure and progressive disclosure, a few points were worth noting.

The skill covers .astro/.mdx files, Content Collections, Tailwind v4, client: directives, Actions/Zod 4, server features (sessions, i18n, env vars, CSP), View Transitions, and adapter setup. I tend to invoke /astro-dev explicitly out of habit, but since the description is written as a trigger condition, it also fires automatically when the agent touches Astro code.

Give the agent code so it spends turns on composition. Including scripts or templates in a skill means the agent assembles from known-good pieces instead of reconstructing boilerplate from scratch. In this skill, the templates/ directory has drop-in config files for Astro 6 + Tailwind v4.

1
templates/
2
├── astro.config.ts    # Astro 6 + Tailwind v4 + MDX + Fonts API
3
├── content.config.ts  # Content Collections with glob loader
4
└── global.css         # Tailwind v4 CSS entry point

When the agent sets up a project, it copies these and starts from a correct baseline. If guardrails say “don’t do it like that,” templates say “start from this.”

The guardrails themselves were added one at a time as I watched agents fail. I didn’t design 20 upfront. The article puts it well: “Most of ours began as a few lines and a single gotcha, and got better because people kept adding to them.” That’s exactly how it went.

Skill Structure

1
skills/astro-dev/
2
├── SKILL.md                    # Entry point. 20 guardrails + router
3
├── references/
4
│   ├── astro-core-patterns.md  # Core APIs, styles, scripts, middleware
5
│   ├── content-collections.md  # Build/live collections, loaders, Zod 4
6
│   ├── blog-recipes.md         # RSS, pagination, tags, SEO, TOC
7
│   ├── tailwind.md             # Vite plugin, CSS theming, Fonts API
8
│   ├── islands-and-hydration.md
9
│   ├── actions-and-forms.md
10
│   ├── view-transitions.md
11
│   ├── server-features.md
12
│   └── doc-endpoints.md        # MCP setup, LLM-optimized doc URLs
13
└── templates/
14
    ├── astro.config.ts
15
    ├── content.config.ts
16
    └── global.css

Guardrails live in SKILL.md. Detailed references are split by topic under references/. Multi-concept blog patterns (RSS, pagination, tag pages with nested pagination, Shiki dark mode, MDX component overrides, reading time, table of contents, prev/next navigation) are collected in blog-recipes.md. These involve several concepts interacting, so a single MCP search doesn’t produce working code.

Decision frameworks for choices like client:load vs client:idle vs client:visible, Actions vs API routes, and prerender vs on-demand are also included. The templates/ directory has drop-in config files for Astro 6 + Tailwind v4.

Usage

npx skills add gigio1023/astro-dev-skill

Using it alongside the Astro Docs MCP gives you a setup where MCP handles doc searches and the skill handles guardrails and recipes. The Astro Docs MCP is a remote HTTP server provided by the Astro team — no npm package to install.

For Claude Code:

claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp

For Codex and other editors, see the official Astro: Build with AI guide.