Communitygithub.com

IncomeStreamSurfer/astro-builder-skill

Astro와 Tailwind CSS, 콘텐츠 컬렉션, 선택적 Turso 데이터베이스를 사용하여 완전한 SEO 최적화 웹사이트를 구축합니다. 사용자가 웹사이트 제작, 구글 SEO 사이트 구축, Astro 프로젝트 시작, 랜딩 페이지 제작, 비즈니스 웹사이트 구축, 블로그 생성 등 SEO가 중요한 웹 프로젝트를 원할 때 이 스킬을 사용하세요.

astro-builder-skill란 무엇인가요?

이 스킬은 Astro 프레임워크를 기반으로 구글 검색 최적화(SEO)에 특화된 완전한 웹사이트를 구축하는 AI 어시스턴트입니다. 제품, 블로그, 비즈니스 사이트 등 모든 웹 프로젝트에서 SEO가 중요할 때 자동으로 활성화되며, 사용자의 니치와 목표를 파악하는 '발견 및 조사' 단계부터 프로젝트 설정, 페이지 빌드, 콘텐츠 컬렉션/데이터베이스 설정, 배포 준비까지 5단계 워크플로를 따릅니다. Astro의 정적 사이트 생성과 React 아일랜드, Tailwind CSS를 사용하며, 선택적으로 Turso(엣지 SQLite)와 Drizzle ORM으로 동적 데이터(문의 폼, 예약 등)를 처리합니다. 또한 `references/taste-skill.md`에 정의된 디자인 규칙을 적용해 'AI 티가 나는' 제네릭한 결과물을 방지하고, 모든 페이지에 메타 태그, 구조화된 데이터, 시맨틱 HTML, 최적화된 이미지, 사이트맵을 포함시켜 검색 엔진에서 높은 순위를 얻을 수 있도록 합니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용 가능합니다.

지원 대상✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/IncomeStreamSurfer/astro-builder-skill/tree/HEAD/skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Astro SEO 웹사이트 빌더

당신은 구글에서 순위를 올리도록 설계된, 완전하고 배포 준비된 Astro 웹사이트를 구축합니다. 모든 사이트에는 적절한 메타 태그, 구조화된 데이터, 시맨틱 HTML, 최적화된 이미지, 사이트맵, 그리고 플레이스홀더 텍스트가 아닌 실제 조사된 콘텐츠가 포함됩니다.

당신이 만드는 모든 프론트엔드는 프리미엄 수준이어야 하며 제네릭하지 않아야 합니다. UI 코드를 작성하기 전에 references/taste-skill.md를 읽으십시오. 이 파일에는 제네릭한 "AI 찌꺼기" 출력을 방지하는 디자인 규칙이 포함되어 있습니다.

기술 스택

  • Astro — 정적 우선 프레임워크, 기본적으로 JS 제로, SEO에 완벽함
  • React — Astro 아일랜드(폼, 내비게이션, 애니메이션)를 통한 인터랙티브 컴포넌트
  • Tailwind CSS — 모든 스타일링. shadcn 기본값은 사용 금지. taste-skill 규칙에 따라 모든 것을 커스터마이즈하세요
  • Astro 콘텐츠 컬렉션 — 블로그 게시물, 서비스, 사용후기를 위한 타입 안전 Markdown/MDX 콘텐츠
  • Turso + Drizzle — 엣지 SQLite 데이터베이스 (선택 사항, 폼/동적 데이터용)

워크플로 개요

모든 프로젝트는 다음 순서를 따릅니다. 단계를 건너뛰지 마세요.

1단계: 발견 및 조사

  1. 사용자에게 니치, 비즈니스, 목표에 대해 묻습니다
  2. 데이터베이스(문의 폼, 리드, 예약 등)가 필요한지 묻습니다
  3. 니치를 조사합니다 — 무엇이 순위에 오르는지, 어떤 키워드가 중요한지, 어떤 콘텐츠 격차가 있는지
  4. 페이지 목록, 콘텐츠 전략, 키워드 타겟을 포함한 사이트 구조를 제안합니다
  5. 구축 전에 사용자 승인을 받습니다

2단계: 프로젝트 설정

  1. Astro 프로젝트를 스캐폴딩합니다
  2. 통합(React, Tailwind, sitemap)을 설치하고 구성합니다
  3. 기본 레이아웃, SEO 컴포넌트, 디자인 시스템을 설정합니다

3단계: 모든 페이지 구축

  1. 디자인 규칙을 위해 references/taste-skill.md를 읽습니다
  2. 사용자가 생성된 이미지를 원하면 references/image-generation.md를 읽고 각 페이지에 대한 이미지를 생성합니다
  3. 실제 조사된 콘텐츠로 각 페이지를 만듭니다
  4. 모든 페이지에 완전한 SEO 적용 — 메타 태그, OG 태그, 구조화된 데이터, 시맨틱 HTML
  5. 인터랙티브 컴포넌트(폼, 내비게이션 등)를 연결합니다

4단계: 콘텐츠 컬렉션 및 데이터베이스

  1. 블로그 게시물, 서비스 등을 위한 Astro 콘텐츠 컬렉션을 구성합니다
  2. 데이터베이스가 요청된 경우: Turso 설정, 스키마 생성, API 경로 구축
  3. 해당하는 경우 데이터베이스 데이터를 위한 관리자 대시보드를 구축합니다

5단계: 배포 준비

  1. 사이트맵, robots.txt 생성
  2. 배포 구성(Vercel/Netlify)
  3. 모든 페이지의 최종 SEO 감사

1단계: 발견 및 조사

사용자에게 묻기

코드를 작성하기 전에 프로젝트를 이해하십시오:

  1. 당신의 니치/비즈니스는 무엇인가요? — "저는 더블린에 사는 배관공입니다" 또는 "저는 온라인에 손으로 만든 촛불을 판매합니다"
  2. 사이트의 주요 목표는 무엇인가요? — 리드 생성, 전자상거래, 포트폴리오, 블로그, SaaS 랜딩 페이지
  3. 몇 페이지를 원하시나요? — 소규모(5-10페이지) 또는 콘텐츠 중심(블로그 포함 15-30+ 페이지)
  4. 데이터베이스가 필요하신가요? — 폼 제출, 예약, 사용자 데이터 등을 저장하기 위해. 필요한 경우 Turso를 설정합니다.
  5. 생성된 이미지를 원하시나요? — "Gemini를 사용하여 사이트에 맞춤형 스톡 이미지를 생성할 수 있습니다. 원하시면 .env 파일에 GEMINI_API_KEY를 추가해 주세요."
  6. 도메인을 가지고 계신가요? — 사이트맵/표준 URL에 필요합니다. 아직 구매하지 않은 경우 플레이스홀더를 사용하십시오.
  7. 디자인 선호 사항이 있으신가요? — 색상, 스타일, 기존 브랜딩

니치 조사

웹 검색을 사용하여 다음을 찾으십시오:

  • 현재 순위에 오르는 것 — 타겟 키워드에 대해 상위 5-10개 결과
  • 콘텐츠 격차 — 어떤 질문이 제대로 답변되지 않고 있는지
  • 롱테일 키워드 — 경쟁이 덜한 구체적인 구문
  • 로컬 SEO 신호 — 로컬 비즈니스인 경우
  • 경쟁사 사이트 구조 — 어떤 페이지가 있고, 무엇이 빠져 있는지

사이트 구조 제안

조사에 기초하여 구체적인 제안을 작성하십시오. 배관공의 예:

제안된 페이지:
1. 홈 — "더블린 배관공 | 24/7 긴급 배관 서비스"
2. 서비스 — 모든 서비스 개요
3. 서비스/긴급-배관 — 타겟 랜딩 페이지
4. 서비스/욕실-리모델링 — 타겟 랜딩 페이지
5. 서비스/보일러-수리 — 타겟 랜딩 페이지
6. 소개 — 신뢰 신호, 팀, 자격
7. 블로그 — 지속적인 SEO 콘텐츠
8. 블로그/[slug] — 롱테일 키워드를 타겟으로 하는 개별 게시물
9. 문의 — 폼 + 지도 + 전화
10. 서비스 지역 — 로컬 SEO 페이지
11. 사용후기 — 사회적 증명

타겟 키워드: 더블린 긴급 배관공, 내 근처 배관공 더블린, 더블린 보일러 수리...
콘텐츠 전략: "[일반적인 문제] 해결 방법" 질문을 타겟으로 하는 주간 블로그 게시물

진행하기 전에 사용자의 승인을 받으십시오.


2단계: 프로젝트 설정

정확한 명령어와 구성은 references/astro-setup.md를 참조하십시오.

1. 프로젝트 생성

npm create astro@latest [project-name] -- --template minimal --install --no-git
cd [project-name]

2. 통합 설치

npx astro add react tailwind sitemap
npm install @astrojs/check typescript
npm install @fontsource/geist-sans @fontsource/geist-mono  # taste-skill 기준 프리미엄 폰트

3. 데이터베이스가 요청된 경우

전체 Turso 구성은 references/turso-setup.md를 참조하십시오.

npm install @libsql/client drizzle-orm

4. 프로젝트 구조

src/
├── components/
│   ├── SEOHead.astro
│   ├── Header.astro
│   ├── Footer.astro
│   ├── Navigation.tsx    # React 아일랜드
│   └── ContactForm.tsx   # React 아일랜드
├── content.config.ts     # 콘텐츠 컬렉션 스키마 (content/ 안에 두지 마세요)
├── content/
│   ├── blog/
│   ├── services/
│   └── testimonials/
├── layouts/
│   └── BaseLayout.astro
├── lib/
│   ├── turso.ts          # 데이터베이스가 있는 경우
│   └── utils.ts
├── pages/
│   ├── index.astro
│   ├── about.astro
│   ├── contact.astro
│   ├── blog/
│   │   ├── index.astro
│   │   └── [...slug].astro
│   └── api/              # API 경로 (데이터베이스가 있는 경우)
├── styles/
│   └── globals.css
└── middleware.ts
astro.config.mjs

3단계: 모든 페이지 구축 — 디자인 + SEO

페이지를 작성하기 전에 다음 두 파일을 모두 읽으십시오:

  • references/seo-checklist.md — 모든 페이지의 SEO 규칙
  • references/taste-skill.md — 제네릭 출력을 방지하는 디자인 규칙

SEOHead 컴포넌트

src/components/SEOHead.astro 생성 — 모든 페이지의 <head>에 들어갑니다. 다음을 처리합니다:

  • 제목 태그 (페이지별 고유, 기본 키워드 포함, 60자 미만)
  • 메타 설명 (고유, CTA 포함, 160자 미만)
  • 표준 URL
  • 오픈 그래프 태그
  • 트위터 카드 태그
  • JSON-LD 구조화된 데이터

정확한 컴포넌트 코드는 references/seo-checklist.md를 참조하십시오.

콘텐츠 작성 규칙

  • 사람을 위해 먼저 쓰고, 검색 엔진은 다음으로.
  • 모든 페이지는 특정 키워드 클러스터를 타겟으로 합니다. 제목, H1, 첫 번째 단락, 메타 설명, URL 슬러그에 기본 키워드를 사용합니다.
  • 올바른 제목 계층 구조. 하나의 H1. 섹션에는 H2. 하위 섹션에는 H3. 레벨을 건너뛰지 마십시오.
  • 내부 링크. 모든 페이지는 2-3개 이상의 다른 페이지에 링크합니다. 설명적인 앵커 텍스트를 사용합니다.
  • 이미지 대체 텍스트. 모든 이미지에는 자연스러운 키워드가 포함된 설명적인 대체 텍스트가 있어야 합니다.
  • 콘텐츠 길이. 서비스 페이지: 800-1500 단어. 블로그 게시물: 1500-3000 단어. 홈: 500-1000 단어.
  • 스키마 마크업. 모든 페이지에 적절한 JSON-LD를 적용합니다.

디자인 규칙 (taste-skill 기준)

다음은 구축하는 모든 페이지에 대해 절대적으로 지켜야 할 사항입니다:

  • 타이포그래피: Geist, Satoshi, Outfit 또는 Cabinet Grotesk를 사용하십시오. Inter는 절대 사용하지 마세요. 제목: text-4xl md:text-6xl tracking-tighter leading-none.
  • 색상: 최대 1개의 악센트 색상, 채도 80% 미만. 보라색/파란색 AI 그라데이션 사용 금지. 중성 베이스(Zinc/Slate).
  • 레이아웃: DESIGN_VARIANCE > 4일 때 중앙 히어로 사용 금지. 분할 화면, 비대칭 또는 왼쪽 정렬 레이아웃을 사용하십시오.
  • 카드: 계층 구조를 전달할 때만 사용. 제네릭한 3열 카드 레이아웃 사용 금지.
  • 간격: h-screen 대신 min-h-[100dvh]. flexbox 수학 대신 그리드. max-w-7xl mx-auto.
  • 상태: 모든 인터랙티브 컴포넌트는 로딩, 빈 상태, 오류 상태가 필요합니다.
  • AI 찌꺼기 금지: 이모지, "John Doe", "Acme Corp", "seamless" 또는 "unleash" 같은 필러 단어 사용 금지.

인터랙티브를 위한 Astro 아일랜드

  • 정적 콘텐츠 (제목, 텍스트, 이미지) — .astro 컴포넌트, JS 제로
  • 인터랙티브 요소 (폼, 모바일 내비게이션, 스크롤 애니메이션) — client:visible 또는 client:load가 있는 React .tsx
  • 애니메이션: 모션(MOTION_INTENSITY > 5)의 경우, 격리된 React 아일랜드에서 Framer Motion을 사용하십시오. 스프링 물리: type: "spring", stiffness: 100, damping: 20.

컴포넌트 패턴(내비게이션, 폼, FAQ 등)은 references/tailwind-components.md를 참조하십시오.


4단계: 콘텐츠 컬렉션 및 데이터베이스

Astro 콘텐츠 컬렉션

전체 설정은 references/content-collections.md를 참조하십시오. 콘텐츠 컬렉션은 CMS를 대체합니다. 콘텐츠는 타입 안전 스키마와 함께 src/content/에 Markdown 파일로 존재합니다.

중요: 스키마는 src/content.config.ts에 정의하십시오 (src/content/config.ts가 아닙니다. 이전 경로는 Astro v5+에서 LegacyContentConfigError를 발생시킵니다). 모든 컬렉션에는 loader가 있어야 합니다 (astro/loaders에서 glob() 사용).

src/content.config.ts에 스키마를 정의합니다:

  • 블로그 게시물: title, description, pubDate, image, tags, author, draft
  • 서비스: title, description, icon, order, featured
  • 사용후기: name, role, quote, rating

페이지에서 getCollection() 및 getEntry()로 컬렉션을 쿼리합니다.

Turso 데이터베이스 (요청된 경우)

전체 설정은 references/turso-setup.md를 참조하십시오. Turso는 동적 데이터(폼 제출, 리드, 예약, 뉴스레터 가입)를 처리합니다.

  1. src/lib/turso.ts에 데이터베이스 클라이언트를 생성합니다
  2. Drizzle ORM으로 스키마를 정의합니다
  3. 폼 처리를 위해 src/pages/api/에 API 경로를 만듭니다
  4. 제출된 데이터를 보기 위한 관리자 대시보드를 구축합니다

관리자 대시보드 (데이터베이스가 있는 경우)

Tailwind로 스타일링된 테이블과 카드를 사용하여 /admin에 React 아일랜드로 구축합니다. 다음을 사용합니다:

  • 기본 인증을 위한 미들웨어
  • Turso에서 데이터를 가져오는 API 경로
  • 깔끔하고 세련된 데이터 프레젠테이션 (taste-skill 규칙 준수 — 제네릭 카드 그리드 사용 금지)

5단계: 배포 준비

사이트맵 및 Robots.txt

@astrojs/sitemap이 사이트맵을 자동 생성합니다. astro.config.mjs에 site를 설정하십시오.

동적 robots.txt를 src/pages/robots.txt.ts에 생성:

import type { APIRoute } from 'astro';

const getRobotsTxt = (siteURL: string) => `User-agent: *
Allow: /
Disallow: /admin
Sitemap: ${siteURL}sitemap-index.xml`;

export const GET: APIRoute = ({ site }) => {
  return new Response(getRobotsTxt(site?.toString() || ''));
};

배포 구성

Vercel/Netlify 구성은 references/deployment.md를 참조하십시오.

API 경로 또는 Turso가 있는 사이트의 경우 어댑터를 추가하지만 기본 정적 출력은 유지합니다. 개별 서버 경로에 export const prerender = false;를 표시하십시오:

import vercel from '@astrojs/vercel';

export default defineConfig({
  // output: 'hybrid'를 사용하지 마십시오. Astro v5에서 제거되었습니다.
  // 기본값은 'static'입니다. 서버 렌더링 경로는 개별적으로 옵트아웃합니다.
  adapter: vercel(),
});

각 API 경로 또는 서버 렌더링 페이지에서:

// src/pages/api/contact.ts
export const prerender = false; // 이 경로는 서버에서 실행됩니다

export const POST: APIRoute = async ({ request }) => {
  // ...
};

최종 SEO 감사

references/seo-checklist.md에 따라 모든 페이지를 감사합니다:

  • 페이지별 고유한 제목, 설명, 표준 URL
  • 모든 이미지에 대체 텍스트가 있음
  • JSON-LD가 유효함
  • 내부 링크가 작동함
  • 모바일 반응형 (taste-skill 모바일 재정의 규칙 테스트)
  • 사이트맵에 모든 페이지가 포함됨
  • robots.txt가 올바름

중요 참고 사항

  • output: 'hybrid'를 사용하지 마십시오 — Astro v5에서 제거되었습니다. 기본 'static' 출력을 사용하십시오. 서버 렌더링 경로(API 엔드포인트, 폼 핸들러)의 경우 각 파일에 export const prerender = false;를 추가하십시오.
  • React 아일랜드에는 수화 지시문이 필요합니다 — client:load 또는 client:visible.
  • 콘텐츠 컬렉션은 파일 기반입니다. 블로그 게시물과 서비스는 src/content/에 .md 파일로 존재합니다. Turso는 동적 데이터(폼 제출) 전용입니다.
  • 구축 전에 조사하십시오. 니치 조사 단계가 SEO 품질을 결정합니다.
  • 실제 콘텐츠가 승리합니다. 실질적이고 도움이 되는 콘텐츠를 작성하십시오. Lorem ipsum은 사용하지 마십시오.
  • 항상 프리미엄 디자인. taste-skill 규칙을 따르십시오. 모든 페이지는 제네릭한 AI 출력이 아닌 $10k 에이전시 빌드처럼 보여야 합니다.
  • 이미지 생성은 선택 사항입니다. 사용자가 GEMINI_API_KEY를 제공하면 references/image-generation.md에 따라 맞춤형 이미지를 생성하십시오. 그렇지 않으면 적절한 대체 텍스트와 함께 스타일링된 플레이스홀더 div를 사용하십시오.

관련 스킬