Communitygithub.com

curiositech/windags-skills

当构建以内容为主的网站,使用Astro时,在SSG/SSR/混合模式间做选择,挑选客户端指令(idle/visible/load/media),使用类型安全的结构化内容集合,在同一项目中集成React/Vue/Solid/Svelte组件,或从Next.js迁移至营销/文档站点时使用。

windags-skills 是什么?

该技能面向基于Astro框架、以内容为中心的网站架构师。其核心优势在于:默认仅输出静态HTML,仅对需要JavaScript的组件进行客户端水合,从而显著减少客户端JS体积,尤其适用于营销、文档和内容密集型站点。技能详细介绍了内容集合的类型安全schema定义、客户端指令(client:idle/load/visible/media)的选择策略、多框架集成、服务端岛屿(Server Islands)、图像优化、视图过渡动画以及MDX组件使用等核心功能。它帮助开发者区分静态内容与交互区域,避免常见的反模式(如滥用client:load、在客户端组件中获取数据、前端无类型、混合使用public/assets导致图像未优化等),并构建过质量门禁(如默认指令选择、内容schema、图像优化、LCP指标等)。该技能明确指出不适用于完整SPA、插件开发、Vite构建调优、重客户端状态应用或原生移动端。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/curiositech/windags-skills/tree/HEAD/skills/astro-islands-architect

在你喜欢的 AI 中提问

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

文档

Astro Islands 架构师

Astro 的理念是“默认输出 HTML,仅对需要 JS 的部分进行水合”。对于营销、文档和内容为主的站点,它能产生比 React/Next.js 小得多的包体积。核心在于决定哪些组件是静态的,哪些是岛屿(需要交互的组件)。

适用场景

  • 营销站点、博客、文档门户——内容为王。
  • 从客户端 JS 过重的 Next.js 营销站点迁移。
  • 多框架——同时使用 React 组件库与 Vue 或 Svelte 组件。
  • 使用 MDX + 类型安全前端数据(frontmatter)进行大量内容创作。
  • 无需 SPA 就能实现页面间的视图过渡。

核心能力

页面结构

---
// src/pages/blog/[slug].astro — 前端数据在构建/SSR 时运行
import { getCollection, getEntry } from 'astro:content';
import Layout from '../../layouts/Default.astro';
import Newsletter from '../../components/Newsletter.tsx';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((p) => ({ params: { slug: p.slug }, props: { post: p } }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---
<Layout title={post.data.title}>
  <h1>{post.data.title}</h1>
  <article><Content /></article>

  {/* 岛屿 — 只有这个组件会加载 JS */}
  <Newsletter client:visible />
</Layout>

--- 定界符内的代码是服务端代码。在 <...> 中,默认输出静态 HTML。带有 client:* 指令的组件将成为岛屿。

客户端指令 — 选择合适的指令

指令水合时机用途
client:load页面加载时首屏交互(购物车、搜索)。
client:idle浏览器空闲时非关键交互(聊天窗口)。
client:visible滚动到视口时视口下方内容(新闻订阅、评论)。
client:media="(min-width: 768px)"媒体查询匹配时仅桌面端的小部件。
client:only="react"跳过 SSR;仅客户端渲染组件初始化需要浏览器 API。

client:idle 是大多数非关键岛屿的合适默认值。client:load 是重量级选择,应谨慎使用。

内容集合

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

const blog = defineCollection({
  type: 'content',                    // markdown/MDX 文件
  schema: z.object({
    title: z.string().max(120),
    description: z.string().max(160),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    cover: z.object({ src: z.string(), alt: z.string() }).optional(),
  }),
});

export const collections = { blog };

现在,getCollection('blog') 是完全类型安全的。前端数据错误会在构建时失败,而不是在生产环境中暴露。

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

多框架

npx astro add react vue svelte
---
import ReactSearch from '../components/Search.tsx';
import VueChart from '../components/Chart.vue';
import SvelteToggle from '../components/Toggle.svelte';
---
<ReactSearch client:idle />
<VueChart client:visible />
<SvelteToggle client:load />

每个框架的运行时会被单独打包,并且仅在使用它的页面上加载。对于大部分是静态的文档站点,这意味着大多数页面可以不加载任何 React JS。

服务端岛屿(Astro 4+)

<Layout>
  <Header />
  <PersonalizedRecommendations server:defer>
    <p slot="fallback">正在加载推荐内容...</p>
  </PersonalizedRecommendations>
  <Footer />
</Layout>

server:defer 会立即渲染页面的其余部分,并通过单独的请求流传输延迟组件的 HTML。对于个性化内容,这很有用,否则会强制整个页面进行 SSR。

图像优化

---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---
<Image src={cover} alt="封面图片" widths={[400, 800, 1200]} sizes="(max-width: 768px) 400px, 1200px" />

Astro 生成 srcset,使用 Sharp 进行缩放,并仅加载所需尺寸。将图像放在 src/assets/ 下以进行完整优化;public/ 目录下的图像不经过处理。

视图过渡

---
import { ViewTransitions } from 'astro:transitions';
---
<html>
  <head>
    <ViewTransitions />
  </head>
  ...
</html>
<a href="/about" transition:name="hero">关于我们</a>

无需 SPA 即可实现跨页面过渡。浏览器完成大部分工作;Astro 负责协调元素匹配。

使用组件 MDX

---
title: 我的文章
date: 2026-04-30
---

import Callout from '../../components/Callout.astro';

# {frontmatter.title}

<Callout type="warn">
这是一个服务端渲染的警告。无需 JS。
</Callout>

在 MDX 中导入的组件会在构建/SSR 时运行,除非它们是岛屿。

混合 SSR

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

export default defineConfig({
  output: 'hybrid',
  adapter: cloudflare(),
});
---
// src/pages/api/search.ts — 在边缘运行
export const prerender = false;

export async function GET({ request }) {
  const url = new URL(request.url);
  const q = url.searchParams.get('q') ?? '';
  const results = await search(q);
  return new Response(JSON.stringify(results), { headers: { 'content-type': 'application/json' } });
}

prerender = false 将该路由设为 SSR;站点的其余部分保持静态。

反模式

到处都用 client:load

症状: Lighthouse JS 包体积膨胀;Astro 的水合优势消失。 诊断: 工程师默认使用 client:load,因为它最熟悉。 修复: 默认使用 client:idle 或 client:visible。仅在首屏交互时使用 client:load。

在客户端组件中获取数据

症状: 每个页面都出现加载动画;SEO 受损。 诊断: 数据获取被移到 React 组件中,而不是在 Astro 前端代码中完成。 修复: 在 --- 定界符内获取数据,在服务端渲染,然后将数据作为 props 传递给岛屿组件。

前端数据无类型

症状: 构建成功;生产环境标题显示 undefined。 诊断: 没有内容集合 schema;前端数据拼写错误未被发现。 修复: 使用带有 zod schema 的 defineCollection。前端数据错误会在构建时失败。

混合使用 public/ 和 src/assets/ 存放图像

症状: 部分图像被优化,其他图像保持原始大小。 诊断: public/ 直接原样提供;只有 src/assets/ 会经过 Sharp 处理。 修复: 将图像移动到 src/assets/。始终使用 <Image> 组件。public/ 仅用于 OG 图像和 favicon。

尝试使用 Astro 构建 SPA

症状: 不断与水合机制作斗争;岛屿不断膨胀直到整个页面都是交互的。 诊断: 框架选择错误。Astro 擅长内容;SPA 需要使用 Next/Remix。 修复: 当大多数页面都需要交互时,使用 Next/Remix。对于营销 + 文档,使用 Astro。

过度使用 client:only

症状: 每次页面加载都出现布局偏移 (CLS);内容出现前有“闪烁”。 诊断: 跳过 SSR 意味着浏览器在 JS 运行前看到一个空占位符。 修复: 仅当组件确实无法在服务端渲染时才使用 client:only。提供一个能近似最终大小的占位符。

质量门禁

  • 默认客户端指令是 client:idle 或 client:visible;client:load 的使用需经理由说明。
  • 所有内容都通过 defineCollection 拥有类型化的 schema。
  • 图像位于 src/assets/ 下并使用 <Image> 组件。
  • 仅当组件存在时才添加多框架集成(@astrojs/react 等)。
  • 在速度最慢的代表性页面上,LCP 低于 2 秒。
  • 为每个页面设置首次加载 JS 预算;CI 在出现回归时失败。
  • MDX 使用 Astro 组件处理静态部分;仅在需要交互的地方使用岛屿。
  • 在主要导航路径上测试了视图过渡。

不适用场景

  • 完整 SPA — Next.js、Remix、TanStack Start 更合适。
  • Astro 插件/集成开发 — 单独技能(目前没有专门技能)。
  • Vite 构建调优 — Astro 底层使用 Vite。请参阅 vite-build-optimizer 处理代码分割、HMR、插件生命周期问题。
  • 重客户端状态应用(仪表盘、实时工具)— 需要过多 JS,岛屿难以发挥作用。
  • 原生移动端 — Astro 仅限 Web。

Individual skills in this repo

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

curiositech/windags-skills

Expert in 2000s-era music visualization (Milkdrop, AVS, Geiss) and modern WebGL implementations. Specializes in Butterchurn integration, Web Audio API AnalyserNode FFT data, GLSL shaders for audio-reactive visuals, and psychedelic generative art. Activate on "Milkdrop", "music visualization", "WebGL visualizer", "Butterchurn", "audio reactive", "FFT visualization", "spectrum analyzer". NOT for simple bar charts/waveforms (use basic canvas), video editing, or non-audio visuals.

curiositech/windags-skills

Expert legal research agent for finding and scraping expungement data state by state. Knows authoritative sources, URL patterns, Firecrawl configuration, and 2026 legal landscape.

curiositech/windags-skills

Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).

curiositech/windags-skills

Implement WCAG 2.2 AA/AAA compliance with automated testing, keyboard navigation, screen reader support, and focus management. Activate on: accessibility audit, WCAG compliance, keyboard navigation, screen reader, aria attributes, axe-core, focus trap. NOT for: design-level accessibility review (use design-accessibility-auditor), color contrast only (use css-in-js-architect).

curiositech/windags-skills

Time-blind friendly planning, executive function support, and daily structure for ADHD brains. Specializes in realistic time estimation, dopamine-aware task design, and building systems that actually work for neurodivergent minds.

curiositech/windags-skills

Designs digital experiences for ADHD brains using neuroscience research and UX principles. Expert in reducing cognitive load, time blindness solutions, dopamine-driven engagement, and compassionate design patterns. Activate on 'ADHD design', 'cognitive load', 'accessibility', 'neurodivergent UX', 'time blindness', 'dopamine-driven', 'executive function'. NOT for general accessibility (WCAG only), neurotypical UX design, or simple UI styling without ADHD context.

curiositech/windags-skills

>- Apply crisis decision-making research to agent routing, uncertainty triage, and coordination failure analysis in time-pressured systems. Use when diagnosing handoff failures, analytical paralysis, or expert judgment under incomplete information. NOT for routine coding, simple CRUD design, or static single-agent tasks with complete information.

curiositech/windags-skills

Extend and modify the admin dashboard, developer portal, and operations console. Use when adding new admin tabs, metrics, monitoring features, or internal tools. Activates for dashboard development, analytics, user management, and internal tooling.

curiositech/windags-skills

Conversation patterns and interaction protocols for multi-agent systems. Covers request/response, pub/sub, blackboard, delegation chains, debate, critique, consensus, fan-out/fan-in, supervisor-worker, and peer negotiation. Deep analysis of AutoGen conversation patterns, CrewAI delegation, LangGraph state passing, and FIPA-ACL performatives. Teaches how to design what agents say to each other and in what order. Activate on: "agent conversation", "agent protocol", "multi-agent debate", "agent delegation", "supervisor worker pattern", "agent voting", "consensus protocol", "fan-out fan-in", "agent negotiation", "blackboard pattern", "agent dialogue", "conversation topology", "agent handoff". NOT for: wire format or serialization (use agent-interchange-formats), orchestration infrastructure (use agentic-infrastructure-2026), single agent behavior (use agentic-patterns).

curiositech/windags-skills

Meta-agent for creating new custom agents, skills, and MCP integrations. Expert in agent design, MCP development, skill architecture, and rapid prototyping. Activate on 'create agent', 'new skill', 'MCP server', 'custom tool', 'agent design'. NOT for using existing agents (invoke them directly), general coding (use language-specific skills), or infrastructure setup (use deployment-engineer).

curiositech/windags-skills

AI-powered calendar management and agent-based scheduling coordination. Covers calendar APIs (Google Calendar, CalDAV/iCal), AI scheduling assistants (Reclaim, Clockwise, Motion, Cal.com), building custom calendar agents with MCP, multi-calendar merging, timezone management, focus block protection, meeting fatigue detection, and agent-to-agent meeting negotiation protocols. Activate on: "calendar agent", "AI scheduling", "calendar coordination", "meeting scheduling", "calendar API", "focus time protection", "calendar optimization", "Google Calendar MCP", "Reclaim", "Clockwise", "Motion", "Cal.com", "smart scheduling", "calendar-aware agent", "timezone scheduling", "agent negotiation meetings". NOT for: manual calendar UI component design (use form-validation-architect), project management scheduling or Gantt charts (use project-management-guru-adhd), general time-tracking or pomodoro apps (use adhd-daily-planner for time-awareness), building the agent itself from scratch (use agent-creator).

curiositech/windags-skills

Build and adopt production AI agent infrastructure in 2026. Covers framework selection (LangGraph, CrewAI, AutoGen, MCP), orchestration patterns, evaluation, observability, memory systems, and tool use. Also covers the SOCIAL dimension: how to sell agent infrastructure internally, change management, measuring ROI, building trust in autonomous systems, and scaling adoption across teams. Activate on: "agent infrastructure", "agent framework comparison", "which agent framework", "sell AI tools internally", "agent adoption", "agent observability", "agent evaluation", "MCP architecture", "agentic mesh", "enterprise AI agents", "AI change management", "agent ROI". NOT for: building specific agents (use ai-engineer), designing agent behavior patterns (use agentic-patterns), prompt tuning (use prompt-engineer).

curiositech/windags-skills

Fundamental patterns for effective agentic behavior. Teaches decomposition, tool orchestration, error recovery, context management, quality self-assessment, and knowing when to stop. Model-agnostic principles that make any agent more effective regardless of domain. Activate on: "how should I structure this agent", "agentic workflow", "agent patterns", "multi-step task", "tool orchestration", "/agentic-patterns", "decompose this", "agent best practices", "chain of actions", "when should the agent stop", "agent loop design". NOT for: creating agent infrastructure (use agent-creator), building DAGs (use windags-architect), specific tool implementation.

curiositech/windags-skills

Automated discovery and matching of agent skills for dynamic task routing and capability assessment

curiositech/windags-skills

Cryptographic security for agentic systems — zero-trust agent networking, signed message envelopes (JWS/JWE), capability-based security (ocaps), Merkle tree audit trails, WASM sandboxing, and formal verification. Covers CLI dev tool security, mTLS between agents, permission boundaries (least privilege for AI agents), and supply chain security for skills/plugins. Activate on: "agent security", "zero trust agents", "secure agent communication", "capability-based security", "ocap", "signed messages between agents", "agent audit trail", "sandbox agent execution", "agent permissions", "mTLS agents", "cryptographic verification", "agent supply chain", "OWASP agentic", "prove agent did X", "tamper-proof agent logs". NOT for: application-level SAST scanning (use security-auditor), network firewall rules (use infrastructure), SOC2/HIPAA compliance (organizational), or prompt injection defense (use prompt-engineer).

curiositech/windags-skills

Data structures and serialization formats for agent-to-agent communication. Covers message envelopes, structured output schemas, capability declarations, task handoff payloads, error/retry signaling, and context windows as data structures. Deep comparison of A2A protocol, MCP, OpenAI function calling, and LangChain message types. Teaches when to use rigid schemas vs free-form with validation, typed vs untyped, streaming vs batch. Activate on: "agent message format", "agent communication schema", "agent-to-agent protocol", "A2A protocol", "MCP message format", "structured output for agents", "agent interop", "interchange format", "agent serialization", "task handoff format", "capability declaration". NOT for: what agents say to each other (use agent-conversation-protocols), orchestration topology (use multi-agent-coordination), building agent infrastructure (use agentic-infrastructure-2026).

curiositech/windags-skills

Logic-based agent programming language implementing BDI architecture for practical autonomous agent development

curiositech/windags-skills

>- Design AgentSpeak(L)-style BDI agents with context-guarded plans, selection functions, and intention stacks. Use for interruptible autonomy, agent policy, and multi-agent orchestration in dynamic environments. NOT for simple rule engines, static planners, or centralized workflows.

curiositech/windags-skills

Foundational concurrent computation model where actors communicate exclusively through asynchronous message passing

curiositech/windags-skills

license: Apache-2.0 NOT for unrelated tasks outside this domain.

相关技能