Communitygithub.com

Anhvu1107/all-agent-skill

总是当请求与 Astro 相关时使用此技能:使用 Astro 构建以内容为中心的网站——默认零 JavaScript、孤岛架构、多框架组件和 Markdown/MDX 支持。

all-agent-skill 是什么?

此技能专为使用 Astro 框架构建内容丰富的网站而设计,例如博客、文档网站、作品集、营销页面和电子商务网站。其核心优势在于“孤岛架构”:默认情况下,Astro 不向浏览器发送任何 JavaScript,只有交互式组件才会被有选择地水合为独立的“孤岛”。该技能指导用户完成项目搭建、Astro 组件语法、基于文件的路由、内容集合(提供类型安全的 Markdown/MDX 访问)、孤岛水合指令、布局以及 SSR 模式。它还包含大量最佳实践、安全注意事项和常见陷阱的解决方案。它支持 React、Vue、Svelte 和 Solid 等框架在同一项目中并存,并可在 VS Code、终端、Claude Code、Cursor 和 Codex 等平台上使用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Anhvu1107/all-agent-skill/tree/HEAD/.agent/skills/astro

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Astro Web 框架

选择性阅读规则

从以下文件开始:

  • references/senior-master-standard.md
  • references/usage-routing.md
  • references/quality-checklist.md

然后,仅加载与用户实际任务匹配的继承文档、脚本、资源或示例。

概述

Astro 是一个专为内容丰富的网站设计的 Web 框架——博客、文档、作品集、营销网站和电子商务。其核心创新是孤岛架构:默认情况下,Astro 不向浏览器发送任何 JavaScript。交互式组件会被有选择地水合为独立的“孤岛”。Astro 支持在同一个项目中同时使用 React、Vue、Svelte、Solid 和其他 UI 框架,让您可以为每个组件选择合适的工具。

何时使用此技能

  • 当构建博客、文档网站、营销页面或作品集时使用
  • 当性能与核心 Web 指标是最高优先级时使用
  • 当项目内容繁重,包含大量 Markdown 或 MDX 文件时使用
  • 当需要 SSG(静态)输出,并带有用于动态路由的可选 SSR 时使用
  • 当用户询问 .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 框架组件会渲染为静态 HTML,不带任何 JavaScript。使用 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:带 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:visible 而非 client:load,以减少初始 JavaScript
  • ✅ 使用 import.meta.env 来管理环境变量——用 PUBLIC_ 前缀标记公开变量
  • ✅ 从 astro:transitions 添加 <ViewTransitions />,以实现平滑的页面导航,无需完整的 SPA
  • ❌ 不要在每一个组件上都使用 client:load——这会破坏 Astro 的性能优势
  • ❌ 不要将秘密信息放入会在面向客户端的模板中使用的 .astro 文件前端内容中
  • ❌ 在静态模式下,不要跳过动态路由的 getStaticPaths——否则构建会失败

安全与注意事项

  • .astro 文件中的前端内容代码仅在服务端运行,绝不会暴露给浏览器。
  • 仅对非敏感值使用 import.meta.env.PUBLIC_*。私有环境变量(无 PUBLIC_ 前缀)绝不会发送到客户端。
  • 使用 SSR 模式时,在数据库查询或 API 调用之前,验证所有 Astro.request 的输入。
  • 在使用 set:html 渲染用户提供的内容之前,务必进行清理——它会绕过自动转义。

常见陷阱

  • 问题: React/Vue 组件的 JavaScript 未在浏览器中运行 解决方案: 添加 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.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches 007: Security audit, hardening, threat modeling (STRIDE/PASTA), Red/Blue Team, OWASP checks, code review, incident response, and infrastructure security for any project.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Agentfolio: Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Animejs Animation: Advanced JavaScript animation library skill for creating complex, high-performance web animations.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Astropy: Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Emotional ARC Designer: One sentence - what this skill does and when to invoke it

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Fixing Motion Performance: Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches I18n Localization: Internationalization and localization patterns.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Interactive Portfolio: Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches JQ: Expert jq usage for JSON querying, filtering, transformation, and pipeline integration.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Landing Page Generator: Generates high-converting Next.js/React landing pages with Tailwind CSS.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches LEX: Centralized ''Truth Engine'' for cross-jurisdictional legal context (US, EU, CA) and contract scaffolding.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Magic Animator: AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Makepad Animation: CRITICAL: Use for Makepad animation system.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Nextjs APP Router Patterns: Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

Anhvu1107/all-agent-skill

ALWAYS use this when the user mentions Nextjs Best Practices, asks to build, debug, review, document, automate, test, configure, migrate, or make decisions in this domain, or the task clearly depends on Nextjs Best Practices; scope: Next.js App Router principles. Apply the bundled workflow, references, scripts, Senior Master standard, and Codex strict review gate before final output.

Anhvu1107/all-agent-skill

description: ALWAYS use this when the work is specifically about modern Next.js or React architecture, data flow, rendering strategy, routing, or performance-sensitive frontend behavior.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches Nextjs Supabase Auth: Expert integration of Supabase Auth with Next.js App Router

Anhvu1107/all-agent-skill

ALWAYS use this when the task involves reading, extracting, splitting, merging, rotating, creating, validating, OCR-ing, form-filling, or otherwise producing or modifying PDF files.

Anhvu1107/all-agent-skill

ALWAYS use this when the request matches React Nextjs Development: React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

Anhvu1107/all-agent-skill

ALWAYS use this when working with Remotion code, video compositions, rendering logic, timing, media assets, or React-based motion workflows.

相关技能