diegosouzapw/awesome-omni-skills

Astro 웹 프레임워크

개요

이 공개 복사본은 https://github.com/sickn33/antigravity-awesome-skills에서 plugins/antigravity-awesome-skills/skills/astro를 기본 Omni Skills 에디터 형식으로 패키징하며, 원본 출처를 숨기지 않습니다.

운영자가 업스트림 워크플로우, 지원 파일 및 저장소 컨텍스트를 온전하게 유지하면서 공개 검증기와 비공개 강화기가 정상적인 다운스트림 흐름을 계속해야 할 때 사용합니다.

이 복사본은 복사된 업스트림 파일을 변경하지 않고 유지하며, metadata.json의 external_source 블록과 ORIGIN.md를 검토를 위한 출처 증거 앵커로 사용합니다.

Astro 웹 프레임워크

공개 제목에 명확하게 매핑되지 않은 가져온 소스 섹션은 아래나 지원 파일에 그대로 보존됩니다. 주목할 만한 가져온 섹션: 작동 방식, 보안 및 안전 참고 사항, 일반적인 함정, 제한 사항.

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

이 섹션을 트리거 필터로 사용하십시오. 운영자가 파일을 로드하거나, 명령을 실행하거나, 풀 리퀘스트를 열기 전에 활성화 경계를 명확히 해야 합니다.

• 블로그, 문서 사이트, 마케팅 페이지 또는 포트폴리오를 구축할 때 사용
• 성능 및 Core Web Vitals가 최우선 순위일 때 사용
• 프로젝트가 Markdown 또는 MDX 파일로 콘텐츠가 많은 경우 사용
• 동적 라우트에 대해 선택적 SSR과 함께 SSG(정적) 출력을 원할 때 사용
• 사용자가 .astro 파일, Astro.props, 콘텐츠 컬렉션 또는 client: 지시문에 대해 물을 때 사용
• 요청이 가져온 소스 의도와 명확히 일치할 때 사용: Astro로 콘텐츠 중심 웹사이트 구축 — 기본적으로 JS 제로, 아일랜드 아키텍처, 다중 프레임워크 컴포넌트, Markdown/MDX 지원.

운영 테이블

상황	시작 위치	중요성
최초 사용	metadata.json	복사된 워크플로우를 건드리기 전에 external_source 블록을 통해 저장소, 브랜치, 커밋 및 가져온 경로를 확인
출처 검토	ORIGIN.md	검토자에게 가져온 소스에 대한 일반 언어 감사 추적 제공
워크플로우 실행	SKILL.md	실행을 실질적으로 변경하는 가장 작은 복사 파일부터 시작
지원 컨텍스트	SKILL.md	전체 패키지를 로드하지 않고 다음으로 가장 관련성 높은 복사된 소스 파일 추가
인계 결정	## 관련 스킬	작업이 표류할 때 운영자가 더 강력한 기본 스킬로 전환하도록 도움

워크플로우

이 워크플로우는 의도적으로 편집 및 운영 측면을 동시에 수행합니다. 가져온 소스를 운영자에게 유용하게 유지하면서 다운스트림 강화기 흐름을 공급하는 공개 복사 기준을 충족시킵니다.

1. 사용자 목표, 가져온 워크플로우의 범위 및 이 스킬이 여전히 작업에 적합한 라우터인지 확인합니다.
2. 복사된 업스트림 지원 파일을 로드하기 전에 개요 및 출처 파일을 읽습니다.
3. 현재 요청의 결과를 실질적으로 변경하는 참조, 예제, 프롬프트 또는 스크립트만 로드합니다.
4. 작업 노트에서 출처 및 소스 경계를 명시적으로 유지하면서 업스트림 워크플로우를 실행합니다.
5. 업스트림 기대치와 복사된 파일에서 증명할 수 있는 증거를 기준으로 결과를 검증합니다.
6. 작업이 이 가져온 워크플로우의 중심 범위를 벗어나면 관련 스킬로 에스컬레이션하거나 인계합니다.
7. 병합 또는 종료 전에 사용된 내용, 변경된 내용 및 검토자가 여전히 확인해야 할 사항을 기록합니다.

가져온 워크플로우 노트

가져온: 개요

Astro는 콘텐츠가 풍부한 웹사이트(블로그, 문서, 포트폴리오, 마케팅 사이트, 전자상거래)를 위해 설계된 웹 프레임워크입니다. 핵심 혁신은 **아일랜드 아키텍처(Islands Architecture)**입니다. 기본적으로 Astro는 브라우저에 0 JavaScript를 제공합니다. 대화형 컴포넌트는 격리된 "아일랜드"로 선택적으로 하이드레이션됩니다. Astro는 동일한 프로젝트에서 React, Vue, Svelte, Solid 및 기타 UI 프레임워크를 동시에 지원하므로 컴포넌트별로 적합한 도구를 선택할 수 있습니다.

가져온: 작동 방식

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 — 브라우저로 전송되는 JavaScript 없음 -->
<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="en">
  <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: 업스트림 워크플로우 직접 요청

<task>를 처리하려면 @astro-v2를 사용하십시오. 복사된 업스트림 워크플로우부터 시작하여 결과를 변경하는 파일만 로드하고 답변에 출처가 표시되도록 유지하십시오.

설명: 운영자가 가져온 워크플로우는 필요하지만 전체 저장소는 필요하지 않을 때 가장 안전한 시작점입니다.

예제 2: 출처 기반 검토 요청

metadata.json 및 ORIGIN.md에 대해 @astro-v2를 검토한 다음, 어떤 복사된 업스트림 파일을 먼저 로드하고 그 이유를 설명하십시오.

설명: 출처 및 파일 선택에 대한 정확하고 감사 가능한 설명이 필요할 때 검토 또는 문제 해결 전에 사용하십시오.

예제 3: 실행 전 복사된 지원 파일 범위 좁히기

<task>에 @astro-v2를 사용하십시오. 결과를 변경하는 복사된 참조, 예제 또는 스크립트만 로드하고 진행하기 전에 파일 이름을 명시적으로 지정하십시오.

설명: 기본적으로 전체 복사 패키지를 로드하는 대신 스킬을 점진적 공개에 맞추는 방법입니다.

예제 4: 검토자 패키지 구축

복사된 업스트림 파일과 출처를 사용하여 @astro-v2를 검토한 다음, 병합 전에 발생할 수 있는 격차를 요약하십시오.

설명: PR이 사람의 검토를 기다리고 있고 반복 가능한 감사 패키지를 원할 때 유용합니다.

가져온 사용 노트

가져온: 예제

예제 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 콘텐츠에 콘텐츠 컬렉션 사용 — 타입 안전성 및 자동 검증 제공
• ✅ 초기 JS를 줄이기 위해 폴드 아래 컴포넌트에는 client:load보다 client:visible 선호
• ✅ 환경 변수에 import.meta.env 사용 — 공개 변수는 PUBLIC_ 접두사 사용
• ✅ 전체 SPA 없이 부드러운 페이지 탐색을 위해 astro:transitions에서 추가
• ❌ 모든 컴포넌트에 client:load 사용 금지 — Astro의 성능 이점을 무효화함
• ❌ 클라이언트 직면 템플릿에서 사용되는 .astro 프론트매터에 비밀 정보를 넣지 마십시오

가져온 운영 노트

가져온: 모범 사례

• ✅ 대부분의 컴포넌트를 정적 .astro 파일로 유지 — 대화형이어야 하는 것만 하이드레이션
• ✅ 모든 Markdown/MDX 콘텐츠에 콘텐츠 컬렉션 사용 — 타입 안전성 및 자동 검증 제공
• ✅ 초기 JS를 줄이기 위해 폴드 아래 컴포넌트에는 client:load보다 client:visible 선호
• ✅ 환경 변수에 import.meta.env 사용 — 공개 변수는 PUBLIC_ 접두사 사용
• ✅ 전체 SPA 없이 부드러운 페이지 탐색을 위해 astro:transitions에서 <ViewTransitions /> 추가
• ❌ 모든 컴포넌트에 client:load 사용 금지 — Astro의 성능 이점을 무효화함
• ❌ 클라이언트 직면 템플릿에서 사용되는 .astro 프론트매터에 비밀 정보를 넣지 마십시오
• ❌ 정적 모드에서 동적 라우트에 getStaticPaths를 건너뛰지 마십시오 — 빌드가 실패합니다

문제 해결

문제: 운영자가 가져온 컨텍스트를 건너뛰고 너무 일반적으로 답변함

증상: 결과가 plugins/antigravity-awesome-skills/skills/astro의 업스트림 워크플로우를 무시하고 출처를 언급하지 않으며 복사된 소스 파일을 전혀 사용하지 않습니다. 해결책: metadata.json, ORIGIN.md 및 가장 관련성 높은 복사된 업스트림 파일을 다시 엽니다. 먼저 external_source 블록을 확인한 다음 계속하기 전에 출처를 다시 설명하십시오.

문제: 가져온 워크플로우가 검토 중에 불완전하게 느껴짐

…

[번역을 위해 잘림]