Astro Blog를 위한 Agent Skill

• 에이전트는 Astro 6의 breaking change를 모른 채 옛날 패턴을 생성한다.
• Astro Docs MCP는 에이전트가 질문할 때만 동작하는데, 에이전트는 자기가 틀린 줄 모르니까 질문을 안 한다.
• 그래서 에이전트가 코드를 생성하기 전에 참조하는 Agent Skill을 만들었다.

GitHub: gigio1023/astro-dev-skill

이 블로그는 Astro로 만들어져 있다. Claude Code나 Codex를 사용하면서 블로그를 작업하는 중인데, 에이전트가 생성하는 Astro 코드가 반복적으로 틀리는 걸 발견했다. Astro 6에서 꽤 큰 breaking change가 있었는데 에이전트의 학습 데이터에는 Astro 3/4/5 시절 코드가 많다 보니, 에이전트 입장에서는 자기가 아는 패턴이 맞다고 생각하고 그대로 생성하는 거다.

Astro Docs MCP도 쓰고 있는데, MCP는 에이전트가 질문할 때만 동작한다. 에이전트가 entry.render()를 쓸 때 “이 API 바뀌었나?”라고 MCP에 물어보지 않는다. 자기가 아는 게 맞다고 확신하니까 그냥 코드를 생성한다. MCP가 “이거 어떻게 쓰나요?”에 답해주는 거라면, 필요했던 건 “그렇게 쓰면 안 돼”를 말해주는 쪽이었다.

그래서 Agent Skill을 만들었다. 에이전트가 코드를 생성하기 전에 참조하는 가이드라인 같은 것이고, MCP를 대체하는 게 아니라 MCP가 커버하지 못하는 영역을 보완하는 용도다.

에이전트가 반복적으로 틀리는 것들

몇 가지 대표적인 사례를 보면 상황이 이해가 된다.

Astro 6에서 render()가 entry 메서드에서 standalone 함수로 바뀌었다. 에이전트한테 블로그 포스트 렌더링을 시키면 거의 확실하게 post.render()를 쓴다.

1
// 에이전트가 생성하는 코드
2
const { Content } = await post.render()
3

4
// Astro 6에서는 이렇게 바뀌었다
5
import { render } from 'astro:content'
6
const { Content } = await render(post)

Astro.glob()은 Astro 6에서 아예 삭제된 API인데, 에이전트가 포스트 목록을 가져올 때 여전히 쓴다.

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

4
// Content Collections를 사용해야 한다
5
import { getCollection } from 'astro:content'
6
const posts = await getCollection('blog')

Astro 6는 Zod 4를 쓰는데, import 경로부터 다르고 validator 체이닝도 달라졌다.

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

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

Content Collections의 loader가 필수로 바뀐 것도 있다. 설정 파일 위치도 src/content/config.ts에서 src/content.config.ts로 바뀌었다.

1
// loader 없이는 동작하지 않는다
2
const blog = defineCollection({ schema: z.object({...}) })
3

4
// loader가 필수이고, schema는 함수 형태다
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
})

이런 식으로 정리한 패턴이 20개 정도 된다. Tailwind v4의 CSS 네이티브 설정, client:load를 모든 컴포넌트에 붙이는 것, <ClientRouter />에서 이벤트 리스너가 날아가는 것 등이다.

어떤 기준으로 만들었나

스킬을 만들면서 Thariq의 Lessons from Building Claude Code: How We Use Skills를 참고했다. Anthropic 내부에서 수백 개의 스킬을 운영하면서 나온 이야기인데, gotchas 중심으로 만들라거나 progressive disclosure를 하라는 것 같은 기본적인 내용 외에 몇 가지 참고할 만한 포인트가 있었다.

스킬이 커버하는 범위는 .astro/.mdx 파일 수정, Content Collections, Tailwind v4, client: 디렉티브, Actions/Zod 4, 서버 기능(세션, i18n, 환경변수, CSP), View Transitions, 어댑터 설정 등이다. 나는 습관적으로 /astro-dev를 직접 달아서 프롬프팅하긴 하는데, description을 트리거 조건으로 작성해뒀기 때문에 Astro 프로젝트에서 코드를 건드리면 자동으로 트리거되기도 한다.

에이전트에게 코드를 줘서 composition에 턴을 쓰게 하라. 스킬에 스크립트나 템플릿을 포함하면 에이전트가 보일러플레이트를 처음부터 만드는 대신 조합하는 데 시간을 쓴다는 이야기다. 이 스킬에서는 templates/ 디렉토리에 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

에이전트가 프로젝트를 셋업할 때 이 파일들을 복사해서 시작하면 설정에서 틀릴 여지가 줄어든다. 가드레일이 “이렇게 쓰면 안 돼”를 말해주는 거라면, 템플릿은 “이걸 복사해서 시작해”를 말해주는 쪽이다.

가드레일 자체는 에이전트가 틀리는 걸 볼 때마다 하나씩 추가하는 방식으로 만들었다. 처음부터 20개를 설계한 게 아니다. 글에서도 “Most of ours began as a few lines and a single gotcha, and got better because people kept adding to them”이라고 하는데 실제로 그렇게 된다.

스킬 구조

1
skills/astro-dev/
2
├── SKILL.md                    # 진입점. 20개 가드레일 + 라우터
3
├── references/
4
│   ├── astro-core-patterns.md  # Core API, 스타일, 스크립트, 미들웨어
5
│   ├── content-collections.md  # 빌드/라이브 컬렉션, 로더, Zod 4
6
│   ├── blog-recipes.md         # RSS, 페이지네이션, 태그, SEO, TOC
7
│   ├── tailwind.md             # Vite 플러그인, CSS 테마, 폰트 API
8
│   ├── islands-and-hydration.md
9
│   ├── actions-and-forms.md
10
│   ├── view-transitions.md
11
│   ├── server-features.md
12
│   └── doc-endpoints.md        # MCP 설정, LLM 최적화 문서 URL
13
└── templates/
14
    ├── astro.config.ts
15
    ├── content.config.ts
16
    └── global.css

가드레일이 SKILL.md에 들어 있고, 세부 레퍼런스는 references/ 아래에 주제별로 분리되어 있다. 블로그 작업에서 자주 필요한 멀티 컨셉 패턴들(RSS, 페이지네이션, 태그 페이지 + 중첩 페이지네이션, Shiki 다크모드, MDX 컴포넌트 오버라이드, 읽기 시간, 목차, 이전/다음 글)은 blog-recipes.md에 모아뒀다. 이런 건 여러 개념이 얽혀 있어서 MCP 검색 한 번으로는 올바른 코드가 나오지 않는다.

client:load vs client:idle vs client:visible 선택, Actions vs API routes, 프리렌더 vs 온디맨드 같은 의사결정 프레임워크도 포함되어 있다. templates/에는 Astro 6 + Tailwind v4 기준 드롭인 설정 파일이 들어 있다.

쓰는 법

npx skills add gigio1023/astro-dev-skill

Astro Docs MCP와 같이 쓰면 MCP가 최신 문서 검색을, 스킬이 가드레일과 레시피를 담당하는 구조가 된다. Astro Docs MCP는 Astro 팀이 제공하는 원격 HTTP 서버로, npm 패키지 설치가 필요 없다.

Claude Code 기준:

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

Codex 등 다른 에디터 설정은 공식 Astro: Build with AI 가이드를 참고.