Communitygithub.com

ASoudy/AGS

Astro 웹 프레임워크를 사용하여 콘텐츠 중심의 웹사이트를 구축합니다. 기본적으로 JS를 전혀 사용하지 않으며, 아일랜드 아키텍처, 멀티 프레임워크 컴포넌트, Markdown/MDX를 지원합니다.

AGS란 무엇인가요?

이 스킬은 콘텐츠 중심 웹사이트(블로그, 문서, 포트폴리오, 마케팅 사이트, 전자상거래)를 구축하기 위한 Astro 웹 프레임워크를 다룹니다. Astro의 핵심 혁신은 **Islands Architecture**로, 기본적으로 브라우저에 제로 자바스크립트를 전송하며, 필요한 컴포넌트만 선택적으로 하이드레이션(hydration)합니다. React, Vue, Svelte, Solid 등 다양한 UI 프레임워크를 동일 프로젝트에서 동시에 사용할 수 있어 컴포넌트별로 최적의 도구를 선택할 수 있습니다. `.astro` 파일 문법, 콘텐츠 컬렉션, 파일 기반 라우팅, SSG 및 SSR 모드, `client:` 지시문을 통한 아일랜드 패턴 등을 상세히 설명하며, Astro의 성능 최적화 모범 사례와 일반적인 문제 해결 방법도 제공합니다. 이 스킬은 코드 작성 환경에서 Astro 기반 프로젝트를 설정하고, 마크다운/MDX 콘텐츠를 타입-세이프하게 관리하며, 인터랙티브한 아일랜드 컴포넌트를 효율적으로 배포하는 데 유용합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/AGAS/plugins/antigravity-awesome-skills-claude/skills/astro

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

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

문서

Astro 웹 프레임워크

개요

Astro는 콘텐츠가 풍부한 웹사이트(블로그, 문서, 포트폴리오, 마케팅 사이트, 전자상거래)를 위해 설계된 웹 프레임워크입니다. 핵심 혁신은 Islands Architecture입니다. 기본적으로 Astro는 브라우저에 제로 자바스크립트를 전송하며, 인터랙티브 컴포넌트는 격리된 아일랜드(islands)로서 선택적으로 하이드레이션됩니다. Astro는 동일 프로젝트에서 React, Vue, Svelte, Solid 등 여러 UI 프레임워크를 동시에 지원하므로, 컴포넌트별로 적합한 도구를 선택할 수 있습니다.

이 스킬을 사용해야 하는 경우

  • 블로그, 문서 사이트, 마케팅 페이지, 포트폴리오를 구축할 때
  • 성능 및 Core Web Vitals가 최우선일 때
  • 프로젝트가 Markdown 또는 MDX 파일로 콘텐츠가 많을 때
  • 동적 라우트에 선택적 SSR을 사용한 SSG(정적) 출력을 원할 때
  • 사용자가 .astro 파일, Astro.props, 콘텐츠 컬렉션 또는 client: 지시문에 대해 물어볼 때

작동 방식

1단계: 프로젝트 설정

npm create astro@latest my-site
cd my-site
npm install
npm run dev

필요에 따라 통합 기능 추가:

npx astro add tailwind        # Tailwind CSS
npx astro add react           # React 컴포넌트 지원
npx astro add mdx             # MDX 지원
npx astro add sitemap         # 자동 sitemap.xml
npx astro add vercel          # Vercel SSR 어댑터

프로젝트 구조:

src/
  pages/          ← 파일 기반 라우팅 (.astro, .md, .mdx)
  layouts/        ← 재사용 가능한 페이지 셸
  components/     ← UI 컴포넌트 (.astro, .tsx, .vue, 등)
  content/        ← 타입-세이프 콘텐츠 컬렉션 (Markdown/MDX)
  styles/         ← 전역 CSS
public/           ← 정적 자산 (그대로 복사됨)
astro.config.mjs  ← 프레임워크 설정

2단계: Astro 컴포넌트 문법

.astro 파일은 상단에 코드 펜스(서버 전용)를 가지며, 그 아래에 템플릿이 있습니다:

---
// src/components/Card.astro
// 이 블록은 서버에서만 실행되며 브라우저에서는 절대 실행되지 않습니다.
interface Props {
  title: string;
  href: string;
  description: string;
}

const { title, href, description } = Astro.props;
---

<article class="card">
  <h2><a href={href}>{title}</a></h2>
  <p>{description}</p>
</article>

<style>
  /* 이 컴포넌트에 자동으로 스코프 지정됨 */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

3단계: 파일 기반 페이지 및 라우팅

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (동적)
src/pages/blog/[...path].astro → /blog/* (모든 경로)

getStaticPaths를 사용한 동적 라우트:

---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<h1>{post.data.title}</h1>
<Content />

4단계: 콘텐츠 컬렉션

콘텐츠 컬렉션은 Markdown 및 MDX 파일에 대한 타입-세이프 접근을 제공합니다:

// src/content/config.ts
import { z, defineCollection } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content';

const posts = (await getCollection('blog'))
  .filter(p => !p.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---

<ul>
  {posts.map(post => (
    <li>
      <a href={`/blog/${post.slug}`}>{post.data.title}</a>
      <time>{post.data.date.toLocaleDateString()}</time>
    </li>
  ))}
</ul>

5단계: 아일랜드 — 선택적 하이드레이션

기본적으로 UI 프레임워크 컴포넌트는 JS 없이 정적 HTML로 렌더링됩니다. client: 지시문을 사용하여 하이드레이션합니다:

---
import Counter from '../components/Counter.tsx';  // React 컴포넌트
import VideoPlayer from '../components/VideoPlayer.svelte';
---

<!-- 정적 HTML — 브라우저에 자바스크립트 전송 없음 -->
<Counter initialCount={0} />

<!-- 페이지 로드 시 즉시 하이드레이션 -->
<Counter initialCount={0} client:load />

<!-- 컴포넌트가 화면에 보일 때 하이드레이션 -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- 브라우저가 유휴 상태일 때만 하이드레이션 -->
<Analytics client:idle />

<!-- 특정 미디어 쿼리에서만 하이드레이션 -->
<MobileMenu client:media="(max-width: 768px)" />

6단계: 레이아웃

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}
const { title, description = 'My Astro Site' } = Astro.props;
---

<html lang="ko">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <nav>...</nav>
    <main>
      <slot />  <!-- 페이지 콘텐츠가 여기에 렌더링됨 -->
    </main>
    <footer>...</footer>
  </body>
</html>
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="About Us">
  <h1>About Us</h1>
  <p>Welcome to our company...</p>
</BaseLayout>

7단계: SSR 모드 (주문형 렌더링)

어댑터를 설정하여 동적 페이지에 SSR을 활성화합니다:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',  // 'static' | 'server' | 'hybrid'
  adapter: vercel(),
});

export const prerender = false를 사용하여 개별 페이지를 SSR로 선택합니다.

예제

예제 1: RSS 피드가 있는 블로그

// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'My Blog',
    description: 'Latest posts',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}

예제 2: API 엔드포인트 (SSR)

// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const { email } = await request.json();

  if (!email) {
    return new Response(JSON.stringify({ error: 'Email required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  await addToNewsletter(email);
  return new Response(JSON.stringify({ success: true }), { status: 200 });
};

예제 3: 아일랜드로서의 React 컴포넌트

// src/components/SearchBox.tsx
import { useState } from 'react';

export default function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  async function search(e: React.FormEvent) {
    e.preventDefault();
    const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
    setResults(data);
  }

  return (
    <form onSubmit={search}>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <button type="submit">Search</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- 즉시 하이드레이션 — 이 아일랜드는 인터랙티브합니다 -->
<SearchBox client:load />

모범 사례

  • ✅ 대부분의 컴포넌트를 정적 .astro 파일로 유지 — 인터랙티브해야 하는 것만 하이드레이션
  • ✅ 모든 Markdown/MDX 콘텐츠에 콘텐츠 컬렉션 사용 — 타입 안전성과 자동 검증 제공
  • ✅ 스크롤 아래 컴포넌트는 client:load보다 client:visible 선호 — 초기 JS 감소
  • ✅ 환경 변수에는 import.meta.env 사용 — 공개 변수는 PUBLIC_ 접두사
  • ✅ 전체 SPA 없이 부드러운 페이지 탐색을 위해 astro:transitions에서 <ViewTransitions /> 추가
  • ❌ 모든 컴포넌트에 client:load 사용 금지 — Astro의 성능 이점을 무효화
  • ❌ 클라이언트 측 템플릿에서 사용되는 .astro 프론트매터에 비밀 정보 넣지 않음
  • ❌ 정적 모드에서 동적 라우트에 getStaticPaths를 생략하지 않음 — 빌드 실패

보안 및 안전 참고 사항

  • .astro 파일의 프론트매터 코드는 서버 측에서만 실행되며 브라우저에 노출되지 않습니다.
  • 민감하지 않은 값에만 import.meta.env.PUBLIC_*를 사용하세요. 개인 환경 변수(PUBLIC_ 접두사 없음)는 클라이언트로 전송되지 않습니다.
  • SSR 모드를 사용할 때는 데이터베이스 쿼리나 API 호출 전에 모든 Astro.request 입력을 검증하세요.
  • set:html로 렌더링하기 전에 사용자가 제공한 콘텐츠를 살균(sanitize)하세요 — 자동 이스케이프를 우회합니다.

일반적인 문제점

  • 문제: React/Vue 컴포넌트의 자바스크립트가 브라우저에서 실행되지 않음 해결책: client: 지시문(client:load, client:visible 등)을 추가하세요 — 없으면 컴포넌트가 정적 HTML로만 렌더링됩니다.

  • 문제: 개발 중 콘텐츠 업데이트 후 getStaticPaths 데이터가 오래됨 해결책: Astro의 개발 서버는 콘텐츠 파일을 감시합니다. content/config.ts 변경 사항이 반영되지 않으면 다시 시작하세요.

  • 문제: Astro.props 타입이 any — 자동 완성 없음 해결책: 프론트매터에 Props 인터페이스 또는 타입을 정의하면 Astro가 자동으로 추론합니다.

  • 문제: .astro 컴포넌트의 CSS가 다른 컴포넌트로 누출됨 해결책: .astro <style> 태그의 스타일은 자동으로 스코프가 지정됩니다. 의도적으로 자식 요소를 대상으로 할 때만 :global()을 사용하세요.

관련 스킬

  • @sveltekit — 반응형 UI를 갖춘 풀스택 프레임워크가 필요할 때 (Astro의 콘텐츠 중심과 대비)
  • @nextjs-app-router-patterns — React 우선 풀스택 프레임워크가 필요할 때
  • @tailwind-patterns — Tailwind CSS로 Astro 사이트 스타일링
  • @progressive-web-app — Astro 사이트에 PWA 기능 추가

제한 사항

  • 이 스킬은 작업이 위에 설명된 범위와 명확히 일치할 때만 사용하세요.
  • 출력을 환경별 검증, 테스트 또는 전문가 검토의 대체물로 취급하지 마세요.
  • 필요한 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 중단하고 명확히 요청하세요.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

관련 스킬